初次提交
This commit is contained in:
314
backend/BUILD_GUIDE.md
Normal file
314
backend/BUILD_GUIDE.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 云盘后端Linux打包指南
|
||||
|
||||
## 概述
|
||||
|
||||
本指南说明如何使用PyInstaller将云盘后端应用打包成Linux可执行文件，以便在没有Python环境的Linux服务器上部署运行。
|
||||
|
||||
## 文件说明
|
||||
|
||||
### 打包配置文件
|
||||
- `build.spec` - PyInstaller配置文件，定义了打包规则和依赖
|
||||
- `build_linux.py` - 完整的打包脚本，包含检查、清理、打包和部署包创建功能
|
||||
- `requirements-build.txt` - 打包所需的依赖包列表
|
||||
|
||||
### 部署配置文件
|
||||
- `cloud-drive.service` - systemd服务配置文件
|
||||
- `install.sh` - 自动化安装脚本
|
||||
- `uninstall.sh` - 卸载脚本
|
||||
- `quick_build.sh` - 快速打包脚本
|
||||
|
||||
## 环境要求
|
||||
|
||||
### 开发环境（打包用）
|
||||
- Python 3.8+
|
||||
- PyInstaller 5.0+
|
||||
- 操作系统：Linux或Windows（交叉编译）
|
||||
|
||||
### 目标环境（部署用）
|
||||
- Linux 64位系统
|
||||
- MySQL 5.7+ 或 8.0+
|
||||
- Redis (可选)
|
||||
- 至少512MB内存
|
||||
- 至少100MB磁盘空间
|
||||
|
||||
## 打包步骤
|
||||
|
||||
### 方法一：使用完整打包脚本
|
||||
|
||||
```bash
|
||||
# 1. 进入后端目录
|
||||
cd backend
|
||||
|
||||
# 2. 安装依赖
|
||||
pip install -r requirements.txt
|
||||
pip install pyinstaller
|
||||
|
||||
# 3. 运行打包脚本
|
||||
python build_linux.py
|
||||
|
||||
# 或者只清理构建目录
|
||||
python build_linux.py --clean
|
||||
```
|
||||
|
||||
### 方法二：使用快速脚本
|
||||
|
||||
```bash
|
||||
# 1. 进入后端目录
|
||||
cd backend
|
||||
|
||||
# 2. 运行快速打包脚本
|
||||
chmod +x quick_build.sh
|
||||
./quick_build.sh
|
||||
```
|
||||
|
||||
### 方法三：手动打包
|
||||
|
||||
```bash
|
||||
# 1. 安装PyInstaller
|
||||
pip install pyinstaller
|
||||
|
||||
# 2. 清理之前的构建
|
||||
rm -rf build dist __pycache__
|
||||
|
||||
# 3. 执行打包
|
||||
pyinstaller --clean build.spec
|
||||
|
||||
# 4. 创建部署包
|
||||
mkdir -p deploy/logs deploy/uploads
|
||||
cp dist/cloud-drive-server deploy/
|
||||
cp .env.example deploy/
|
||||
```
|
||||
|
||||
## 打包输出
|
||||
|
||||
成功打包后，会生成以下文件：
|
||||
|
||||
```
|
||||
backend/
|
||||
├── deploy/ # 部署包目录
|
||||
│ ├── cloud-drive-server # 主程序可执行文件
|
||||
│ ├── start.sh # 启动脚本
|
||||
│ ├── .env.example # 环境配置示例
|
||||
│ ├── README.md # 部署说明
|
||||
│ ├── logs/ # 日志目录
|
||||
│ └── uploads/ # 上传文件目录
|
||||
├── build/ # PyInstaller构建临时文件
|
||||
├── dist/ # 打包输出目录
|
||||
└── build.spec # 打包配置文件
|
||||
```
|
||||
|
||||
## 部署到Linux服务器
|
||||
|
||||
### 方法一：使用自动化安装脚本
|
||||
|
||||
```bash
|
||||
# 1. 将整个deploy目录上传到服务器
|
||||
scp -r deploy/ user@server:/tmp/cloud-drive
|
||||
|
||||
# 2. 在服务器上运行安装脚本（需要root权限）
|
||||
sudo /tmp/cloud-drive/install.sh
|
||||
```
|
||||
|
||||
### 方法二：手动部署
|
||||
|
||||
```bash
|
||||
# 1. 创建服务用户
|
||||
sudo useradd -r -s /bin/false cloud-drive
|
||||
|
||||
# 2. 创建安装目录
|
||||
sudo mkdir -p /opt/cloud-drive/{logs,uploads}
|
||||
|
||||
# 3. 复制文件
|
||||
sudo cp deploy/cloud-drive-server /opt/cloud-drive/
|
||||
sudo cp deploy/.env.example /opt/cloud-drive/
|
||||
sudo chmod +x /opt/cloud-drive/cloud-drive-server
|
||||
|
||||
# 4. 设置权限
|
||||
sudo chown -R cloud-drive:cloud-drive /opt/cloud-drive
|
||||
|
||||
# 5. 配置环境变量
|
||||
sudo cp /opt/cloud-drive/.env.example /opt/cloud-drive/.env
|
||||
sudo nano /opt/cloud-drive/.env # 编辑配置
|
||||
|
||||
# 6. 安装systemd服务
|
||||
sudo cp cloud-drive.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable cloud-drive
|
||||
|
||||
# 7. 启动服务
|
||||
sudo systemctl start cloud-drive
|
||||
```
|
||||
|
||||
## 环境配置
|
||||
|
||||
编辑 `/opt/cloud-drive/.env` 文件：
|
||||
|
||||
```env
|
||||
# 数据库配置
|
||||
DATABASE_URL=mysql+pymysql://用户名:密码@主机:端口/数据库名
|
||||
|
||||
# Redis配置
|
||||
REDIS_URL=redis://主机:端口
|
||||
|
||||
# JWT配置
|
||||
JWT_SECRET_KEY=你的密钥
|
||||
JWT_EXPIRE_MINUTES=30
|
||||
|
||||
# 运行环境
|
||||
ENVIRONMENT=production
|
||||
|
||||
# 文件上传配置
|
||||
UPLOAD_DIR=uploads
|
||||
MAX_FILE_SIZE=10485760 # 10MB
|
||||
```
|
||||
|
||||
## 服务管理
|
||||
|
||||
```bash
|
||||
# 查看服务状态
|
||||
sudo systemctl status cloud-drive
|
||||
|
||||
# 启动服务
|
||||
sudo systemctl start cloud-drive
|
||||
|
||||
# 停止服务
|
||||
sudo systemctl stop cloud-drive
|
||||
|
||||
# 重启服务
|
||||
sudo systemctl restart cloud-drive
|
||||
|
||||
# 查看日志
|
||||
sudo journalctl -u cloud-drive -f
|
||||
|
||||
# 查看应用日志
|
||||
tail -f /opt/cloud-drive/logs/app.log
|
||||
```
|
||||
|
||||
## 验证部署
|
||||
|
||||
```bash
|
||||
# 健康检查
|
||||
curl http://localhost:8000/api/v1/health
|
||||
|
||||
# API文档
|
||||
curl http://localhost:8000/docs
|
||||
|
||||
# 根路径
|
||||
curl http://localhost:8000/
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 1. 打包问题
|
||||
|
||||
**问题**: `ImportError: No module named 'xxx'`
|
||||
**解决**: 在 `build.spec` 的 `hiddenimports` 列表中添加缺失的模块
|
||||
|
||||
**问题**: 打包文件过大
|
||||
**解决**: 在 `build.spec` 的 `excludes` 列表中添加不需要的库
|
||||
|
||||
### 2. 运行问题
|
||||
|
||||
**问题**: 端口被占用
|
||||
```bash
|
||||
# 检查端口占用
|
||||
sudo netstat -tlnp | grep 8000
|
||||
# 或修改配置文件中的端口
|
||||
```
|
||||
|
||||
**问题**: 数据库连接失败
|
||||
```bash
|
||||
# 检查数据库配置
|
||||
cat /opt/cloud-drive/.env
|
||||
# 测试连接
|
||||
mysql -h 主机 -u 用户 -p 数据库名
|
||||
```
|
||||
|
||||
**问题**: 权限问题
|
||||
```bash
|
||||
# 检查文件权限
|
||||
ls -la /opt/cloud-drive/
|
||||
# 修复权限
|
||||
sudo chown -R cloud-drive:cloud-drive /opt/cloud-drive/
|
||||
```
|
||||
|
||||
### 3. 性能优化
|
||||
|
||||
**启用UPX压缩**（减小文件大小）：
|
||||
```bash
|
||||
# 安装UPX
|
||||
sudo apt install upx # Ubuntu/Debian
|
||||
sudo yum install upx # CentOS/RHEL
|
||||
|
||||
# 在build.spec中确保 upx=True
|
||||
```
|
||||
|
||||
**启用strip**（减小文件大小）：
|
||||
```bash
|
||||
# 在build.spec中确保 strip=True
|
||||
```
|
||||
|
||||
## 更新和维护
|
||||
|
||||
### 更新应用
|
||||
|
||||
```bash
|
||||
# 1. 停止服务
|
||||
sudo systemctl stop cloud-drive
|
||||
|
||||
# 2. 备份当前版本
|
||||
sudo cp /opt/cloud-drive/cloud-drive-server /opt/cloud-drive/cloud-drive-server.bak
|
||||
|
||||
# 3. 替换新版本
|
||||
sudo cp new-cloud-drive-server /opt/cloud-drive/cloud-drive-server
|
||||
sudo chmod +x /opt/cloud-drive/cloud-drive-server
|
||||
|
||||
# 4. 启动服务
|
||||
sudo systemctl start cloud-drive
|
||||
```
|
||||
|
||||
### 日志管理
|
||||
|
||||
日志会自动轮转（通过logrotate配置），也可以手动管理：
|
||||
|
||||
```bash
|
||||
# 查看日志轮转配置
|
||||
cat /etc/logrotate.d/cloud-drive
|
||||
|
||||
# 手动执行日志轮转
|
||||
sudo logrotate -f /etc/logrotate.d/cloud-drive
|
||||
```
|
||||
|
||||
### 监控
|
||||
|
||||
可以使用以下工具监控服务：
|
||||
|
||||
```bash
|
||||
# systemd监控
|
||||
sudo systemctl status cloud-drive
|
||||
|
||||
# 进程监控
|
||||
ps aux | grep cloud-drive-server
|
||||
|
||||
# 网络连接
|
||||
sudo netstat -tlnp | grep 8000
|
||||
|
||||
# 磁盘空间
|
||||
df -h /opt/cloud-drive
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **防火墙配置**: 只开放必要的端口（8000）
|
||||
2. **用户权限**: 使用专用用户运行服务，避免root权限
|
||||
3. **文件权限**: 确保敏感文件只有服务用户可读
|
||||
4. **SSL/TLS**: 在生产环境使用HTTPS
|
||||
5. **定期更新**: 保持系统和依赖包的更新
|
||||
|
||||
## 技术支持
|
||||
|
||||
如遇到问题，请检查：
|
||||
1. 系统日志：`journalctl -u cloud-drive`
|
||||
2. 应用日志：`/opt/cloud-drive/logs/app.log`
|
||||
3. 配置文件：`/opt/cloud-drive/.env`
|
||||
4. 服务状态：`systemctl status cloud-drive`
|
||||
Reference in New Issue
Block a user