Json-Python-Server/DEPLOYMENT.md

# 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 或联系技术支持。