cavin/full-stack-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e4e48fdd28c40c8bd0b4a7f6fb2565e99785d1c
full-stack-doc/backend/BUILD_GUIDE.md
peng 6e4e48fdd2 初次提交
2025-10-14 20:05:29 +08:00

6.6 KiB
Raw Blame History

云盘后端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磁盘空间

打包步骤

方法一：使用完整打包脚本

# 1. 进入后端目录
cd backend

# 2. 安装依赖
pip install -r requirements.txt
pip install pyinstaller

# 3. 运行打包脚本
python build_linux.py

# 或者只清理构建目录
python build_linux.py --clean

方法二：使用快速脚本

# 1. 进入后端目录
cd backend

# 2. 运行快速打包脚本
chmod +x quick_build.sh
./quick_build.sh

方法三：手动打包

# 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服务器

方法一：使用自动化安装脚本

# 1. 将整个deploy目录上传到服务器
scp -r deploy/ user@server:/tmp/cloud-drive

# 2. 在服务器上运行安装脚本（需要root权限）
sudo /tmp/cloud-drive/install.sh

方法二：手动部署

# 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 文件：

# 数据库配置
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

服务管理

# 查看服务状态
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

验证部署

# 健康检查
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. 运行问题

问题: 端口被占用

# 检查端口占用
sudo netstat -tlnp | grep 8000
# 或修改配置文件中的端口

问题: 数据库连接失败

# 检查数据库配置
cat /opt/cloud-drive/.env
# 测试连接
mysql -h 主机 -u 用户 -p 数据库名

问题: 权限问题

# 检查文件权限
ls -la /opt/cloud-drive/
# 修复权限
sudo chown -R cloud-drive:cloud-drive /opt/cloud-drive/

3. 性能优化

启用UPX压缩（减小文件大小）：

# 安装UPX
sudo apt install upx  # Ubuntu/Debian
sudo yum install upx  # CentOS/RHEL

# 在build.spec中确保 upx=True

启用strip（减小文件大小）：

# 在build.spec中确保 strip=True

更新和维护

更新应用

# 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配置），也可以手动管理：

# 查看日志轮转配置
cat /etc/logrotate.d/cloud-drive

# 手动执行日志轮转
sudo logrotate -f /etc/logrotate.d/cloud-drive

监控

可以使用以下工具监控服务：

# 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