272 lines
4.8 KiB
Markdown
272 lines
4.8 KiB
Markdown
# FastAPI 应用生产部署说明
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境要求
|
||
- Python 3.10+
|
||
- Linux / macOS / Windows
|
||
- 20GB 磁盘空间（用于字体和数据）
|
||
|
||
### 2. 一键安装和启动
|
||
|
||
```bash
|
||
# 首次运行，会自动创建虚拟环境和安装依赖
|
||
bash run.sh
|
||
```
|
||
|
||
### 3. Docker 部署
|
||
|
||
```bash
|
||
# 构建 Docker 镜像
|
||
docker build -t lazy-fjh:latest .
|
||
|
||
# 运行容器
|
||
docker run -d \
|
||
-p 60201:60201 \
|
||
-v $(pwd)/uploads:/opt/lazy_fjh/uploads \
|
||
-v $(pwd)/logs:/opt/lazy_fjh/logs \
|
||
-e MY_API_KEY=sk-your-key \
|
||
lazy-fjh:latest
|
||
```
|
||
|
||
### 4. Systemd 部署 (Linux)
|
||
|
||
```bash
|
||
# 复制应用到系统目录
|
||
sudo cp -r /path/to/lazy_fjh /opt/
|
||
|
||
# 更新权限
|
||
sudo chown -R www-data:www-data /opt/lazy_fjh
|
||
|
||
# 安装 systemd 服务
|
||
sudo cp /opt/lazy_fjh/deploy/systemd/lazy-fjh.service /etc/systemd/system/
|
||
|
||
# 启用并启动服务
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable lazy-fjh
|
||
sudo systemctl start lazy-fjh
|
||
|
||
# 检查状态
|
||
sudo systemctl status lazy-fjh
|
||
```
|
||
|
||
### 5. Gunicorn 部署
|
||
|
||
```bash
|
||
# 激活虚拟环境
|
||
source .venv/bin/activate
|
||
|
||
# 使用 gunicorn 启动
|
||
gunicorn -c deploy/gunicorn_config.py main:app
|
||
```
|
||
|
||
## 字体配置
|
||
|
||
### Linux 用户
|
||
|
||
首先安装系统字体：
|
||
|
||
```bash
|
||
bash deploy/install_fonts.sh
|
||
```
|
||
|
||
或手动安装：
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt-get install -y fonts-wqy-microhei fonts-noto-cjk-extra
|
||
|
||
# CentOS/RHEL
|
||
sudo yum install -y wqy-microhei
|
||
|
||
# Arch Linux
|
||
sudo pacman -S --noconfirm wqy-microhei ttf-noto-sans-cjk
|
||
```
|
||
|
||
### macOS 用户
|
||
|
||
```bash
|
||
brew install --cask font-noto-sans-cjk
|
||
```
|
||
|
||
### Windows 用户
|
||
|
||
从 https://www.noto-fonts.cn 下载 Noto Sans CJK 并安装
|
||
|
||
## 环境变量配置
|
||
|
||
复制 `.env.example` 为 `.env` 并填入实际值：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件：
|
||
|
||
```env
|
||
# 环境
|
||
ENV=production
|
||
DEBUG=False
|
||
|
||
# 服务器
|
||
HOST=0.0.0.0
|
||
PORT=60201
|
||
|
||
# API 密钥 (阿里云千问)
|
||
MY_API_KEY=sk-your-api-key-here
|
||
MY_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
MY_MODEL=qwen-turbo
|
||
```
|
||
|
||
## 文件存储
|
||
|
||
### 上传目录
|
||
|
||
- **默认**: `./uploads/`
|
||
- **配置**: 设置 `UPLOAD_DIR` 环境变量
|
||
|
||
### 日志目录
|
||
|
||
- **默认**: `./logs/`
|
||
- **配置**: 设置 `LOG_DIR` 环境变量
|
||
|
||
## API 文档
|
||
|
||
启动应用后访问：
|
||
|
||
- **Swagger UI**: http://localhost:60201/docs
|
||
- **ReDoc**: http://localhost:60201/redoc
|
||
- **OpenAPI**: http://localhost:60201/openapi.json
|
||
|
||
## 常见问题
|
||
|
||
### 1. 字体显示为方块
|
||
|
||
**原因**: 系统未安装中文字体
|
||
|
||
**解决**:
|
||
```bash
|
||
bash deploy/install_fonts.sh
|
||
```
|
||
|
||
### 2. 内存占用过高
|
||
|
||
**原因**: 处理大型数据集时内存使用增多
|
||
|
||
**解决**:
|
||
- 调整 `MAX_MEMORY_MB` 环境变量
|
||
- 分批处理数据
|
||
- 增加服务器内存
|
||
|
||
### 3. 上传文件超时
|
||
|
||
**原因**: 文件过大或网络问题
|
||
|
||
**解决**:
|
||
- 检查 `MAX_UPLOAD_SIZE` 限制
|
||
- 增加 `ANALYSIS_TIMEOUT` 值
|
||
- 分割大文件
|
||
|
||
### 4. 无法访问 API
|
||
|
||
**原因**: 防火墙或端口被占用
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查端口占用
|
||
sudo lsof -i :60201
|
||
|
||
# 更改 PORT 环境变量
|
||
export PORT=8080
|
||
bash run.sh
|
||
```
|
||
|
||
## 监控和维护
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 实时日志
|
||
tail -f logs/app.log
|
||
|
||
# 访问日志 (Gunicorn)
|
||
tail -f logs/access.log
|
||
```
|
||
|
||
### 系统资源监控
|
||
|
||
```bash
|
||
# 使用 top/htop 监控
|
||
htop
|
||
|
||
# 或在 Python 中
|
||
python -c "from modules.linux_adapter import LinuxAdapter; print(LinuxAdapter.get_process_info())"
|
||
```
|
||
|
||
### 定期清理
|
||
|
||
```bash
|
||
# 清理临时文件（超过 7 天）
|
||
find ./temp -type f -mtime +7 -delete
|
||
|
||
# 清理旧上传文件（超过 30 天）
|
||
find ./uploads -type f -mtime +30 -delete
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### 1. 启用 Gzip 压缩
|
||
已默认启用，减少响应体积
|
||
|
||
### 2. 异步处理
|
||
使用异步 I/O，支持更多并发连接
|
||
|
||
### 3. 内存管理
|
||
自动监控和清理内存
|
||
|
||
### 4. 并发配置 (Gunicorn)
|
||
```
|
||
workers = cpu_count * 2 + 1
|
||
worker_connections = 1000
|
||
```
|
||
|
||
## 备份和恢复
|
||
|
||
### 备份上传的文件
|
||
|
||
```bash
|
||
tar -czf backup-uploads-$(date +%Y%m%d).tar.gz uploads/
|
||
```
|
||
|
||
### 备份数据库 (如果使用)
|
||
|
||
```bash
|
||
# PostgreSQL
|
||
pg_dump -U user db_name > backup.sql
|
||
```
|
||
|
||
## 更新应用
|
||
|
||
```bash
|
||
# 拉取最新代码
|
||
git pull origin main
|
||
|
||
# 重新安装依赖（如有更新）
|
||
/home/syy/.local/bin/uv pip install --upgrade -r requirements.txt
|
||
|
||
# 重启服务
|
||
systemctl restart lazy-fjh
|
||
```
|
||
|
||
## 安全建议
|
||
|
||
1. **API 密钥**: 不要在代码中硬编码，使用环境变量
|
||
2. **HTTPS**: 在生产环境使用 HTTPS，配置 SSL 证书
|
||
3. **CORS**: 根据需要限制 CORS 源
|
||
4. **速率限制**: 考虑添加 API 速率限制
|
||
5. **认证**: 为敏感端点添加身份验证
|
||
|
||
## 支持和反馈
|
||
|
||
如有问题或建议，请提交 issue 或联系技术支持。
|