314 lines
6.6 KiB
Markdown
314 lines
6.6 KiB
Markdown
# 云盘后端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` |