# Docker 生产就绪改造

**日期**：2026-02-14  
**类型**：架构优化  
**影响范围**：Docker Compose 配置、环境变量管理、Celery Worker 扩展

---

## 概述

将 Jointo 项目的 Docker Compose 配置从"开发玩具"升级为"生产就绪"架构，采取四个层面的改进：

1. **配置层**：支持多环境配置文件（`.env.local/.staging/.production`）
2. **安全层**：消除硬编码密码和密钥，强制生产环境安全检查
3. **扩展层**：Celery AI Worker 支持水平扩展（`docker-compose scale`）
4. **工程层**：建立"零敏感信息"的 Git 提交规范

---

## 核心变更

### 1. 多环境配置文件

**新增文件**：

```
server/
├── .env.example         # 配置模板（提交到 Git）
├── .env.local           # 本地开发（不提交）
├── .env.staging         # 测试环境（不提交）
└── .env.production      # 生产环境（不提交）
```

**使用方式**：

```bash
# 方式 1：使用 --env-file 显式指定（推荐）
docker-compose --env-file .env.local up -d
docker-compose --env-file .env.production up -d

# 方式 2：软链接 .env（适合固定环境）
ln -sf .env.production .env
docker-compose up -d

# 方式 3：使用部署脚本
./deploy.sh production
```

### 2. 环境变量化改造

**新增配置变量**：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `POSTGRES_USER` | PostgreSQL 用户名 | `jointo_admin` |
| `POSTGRES_PASSWORD` | PostgreSQL 密码 | `change_this_password` |
| `POSTGRES_DB` | 数据库名 | `jointo_db` |
| `POSTGRES_HOST` | 数据库主机 | `postgres` |
| `RABBITMQ_DEFAULT_USER` | RabbitMQ 用户名 | `jointo_user` |
| `RABBITMQ_DEFAULT_PASS` | RabbitMQ 密码 | `jointo_mq_password` |
| `CELERY_AI_CONCURRENCY` | AI Worker 并发数 | `1` |
| `CELERY_AI_REPLICAS` | AI Worker 副本数 | `2` |
| `CELERY_EXPORT_CONCURRENCY` | 导出 Worker 并发数 | `4` |

**docker-compose.yml 变更**：

- **PostgreSQL**：使用 `${POSTGRES_USER}`、`${POSTGRES_PASSWORD}` 等变量
- **RabbitMQ**：使用 `${RABBITMQ_DEFAULT_USER}` 和 `${RABBITMQ_DEFAULT_PASS}`
- **FastAPI/Celery**：数据库和消息队列连接字符串全部环境变量化

### 3. Celery AI Worker 水平扩展

**关键改造**：

- **移除固定容器名**：允许 `docker-compose scale` 扩展
- **单并发架构**：`concurrency=1`，避免 AI 模型重复加载导致内存溢出
- **资源限制**：CPU 限制 2 核，内存限制 4GB
- **唯一命名**：`-n ai-worker@%h` 确保每个副本有独立标识

**扩展方式**：

```bash
# 默认启动 2 个副本（.env 中配置）
docker-compose up -d

# 动态扩展到 5 个
docker-compose up -d --scale celery-worker-ai=5

# 查看运行的 Worker
docker ps --filter "name=celery-worker-ai"
```

### 4. 生产环境安全检查

**文件**：`server/app/core/config.py`

**新增功能**：

- 启动时自动检查生产环境配置安全性
- 检查项包括：
  - `SECRET_KEY` 是否为默认值
  - 数据库密码是否为弱密码（`123456`、`change_this_password`）
  - RabbitMQ 密码是否为默认值
  - `DEBUG` 模式是否关闭
  - AI API Key 是否已配置
  - 存储服务是否使用本地 MinIO

**示例输出**：

```
🚫 生产环境配置安全检查失败:

⚠️ 生产环境禁止使用默认 SECRET_KEY！请使用 `openssl rand -hex 32` 生成强密钥
⚠️ 生产环境禁止使用弱密码！POSTGRES_PASSWORD 必须是强密码
⚠️ 生产环境必须关闭 DEBUG 模式！设置 DEBUG=False
```

### 5. 部署脚本

**文件**：`server/deploy.sh`

**功能**：

- 参数化环境选择（`./deploy.sh production`）
- 自动校验配置文件是否存在
- 生产环境部署前二次确认
- 自动健康检查
- 显示常用运维命令

**用法**：

```bash
chmod +x deploy.sh

# 本地开发
./deploy.sh local

# 测试环境
./deploy.sh staging

# 生产环境（需要二次确认）
./deploy.sh production
```

---

## 迁移步骤

### 现有用户升级指南

#### 1. 备份现有配置

```bash
cd server
cp .env .env.backup
```

#### 2. 创建多环境配置文件

```bash
# 基于现有 .env 创建本地配置
cp .env .env.local

# 创建生产配置
cp .env.example .env.production
vim .env.production  # 修改为生产密钥和密码
```

#### 3. 更新 .gitignore

已自动更新，确保 `.env.local/.staging/.production` 不被提交。

#### 4. 停止现有服务

```bash
docker-compose down
```

#### 5. 使用新方式启动

```bash
# 使用部署脚本（推荐）
./deploy.sh local

# 或使用 --env-file
docker-compose --env-file .env.local up -d
```

#### 6. 验证服务状态

```bash
# 检查所有服务是否健康
docker-compose ps

# 检查 FastAPI 健康
curl http://localhost:6170/health

# 检查 AI Worker 数量
docker ps --filter "name=celery-worker-ai"
```

---

## 安全检查清单

部署生产环境前，请确认以下检查项：

- [ ] `SECRET_KEY` 已使用 `openssl rand -hex 32` 生成
- [ ] `POSTGRES_PASSWORD` 已修改为强密码
- [ ] `RABBITMQ_DEFAULT_PASS` 已修改为强密码
- [ ] `DEBUG=False`（生产环境）
- [ ] `AIHUBMIX_API_KEY` 已配置生产密钥
- [ ] `OPENAI_API_KEY` 已配置生产密钥
- [ ] `ELEVENLABS_API_KEY` 已配置生产密钥
- [ ] `S3_ACCESS_KEY_ID` 和 `S3_SECRET_ACCESS_KEY` 已配置生产凭证
- [ ] `STORAGE_PROVIDER` 设置为 `oss` 或 `s3`（而非 `minio`）
- [ ] `SMS_TEST_MODE=False`（生产环境）
- [ ] 所有敏感配置文件（`.env.local/.staging/.production`）已添加到 `.gitignore`

---

## 回滚方案

如果升级后出现问题，可按以下步骤回滚：

1. **恢复配置文件**：

```bash
cd server
cp .env.backup .env
```

2. **使用旧版 docker-compose.yml**：

```bash
git checkout HEAD~1 docker-compose.yml
```

3. **重启服务**：

```bash
docker-compose down
docker-compose up -d
```

---

## 影响评估

### 正面影响

- ✅ **安全性提升**：消除硬编码密码，强制生产环境检查
- ✅ **扩展性增强**：AI Worker 支持水平扩展，应对流量高峰
- ✅ **运维效率**：多环境配置分离，部署流程标准化
- ✅ **配置清晰**：环境变量集中管理，易于理解和维护
- ✅ **错误防护**：生产环境自动安全检查，避免低级错误

### 潜在风险

- ⚠️ **迁移成本**：现有用户需要创建多环境配置文件
- ⚠️ **学习曲线**：新增 `--env-file` 参数和部署脚本
- ⚠️ **资源消耗**：AI Worker 默认 2 个副本，增加内存使用

### 兼容性

- ✅ **向后兼容**：保留 `.env` 方式（通过软链接）
- ✅ **数据库无变更**：仅配置层面改造，不影响数据
- ✅ **API 无变更**：不影响前端调用

---

## 后续优化建议

1. **CI/CD 集成**：在 GitHub Actions 中使用 `--env-file` 参数
2. **监控告警**：配置 Prometheus + Grafana 监控 Celery Worker 状态
3. **日志聚合**：集成 ELK/Loki 进行日志集中管理
4. **密钥管理**：考虑使用 AWS Secrets Manager 或 Vault
5. **健康检查增强**：为 Celery Worker 添加自定义健康检查

---

## 相关文档

- [技术栈文档 - Infrastructure](../../.claude/skills/jointo-tech-stack/references/infrastructure.md)
- [部署脚本使用指南](../guides/deploy-script-usage.md)（待创建）
- [环境配置最佳实践](../guides/environment-config-best-practices.md)（待创建）

---

## 变更作者

Claude (Sonnet 4.5)  
协助人员：@panta