# 云盘后端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`