7.3 KiB

Raw Blame History

Docker 生产就绪改造

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

概述

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

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

核心变更

1. 多环境配置文件

新增文件：

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

使用方式：

# 方式 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 确保每个副本有独立标识

扩展方式：

# 默认启动 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）
自动校验配置文件是否存在
生产环境部署前二次确认
自动健康检查
显示常用运维命令

用法：

chmod +x deploy.sh

# 本地开发
./deploy.sh local

# 测试环境
./deploy.sh staging

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

迁移步骤

现有用户升级指南

1. 备份现有配置

cd server
cp .env .env.backup

2. 创建多环境配置文件

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

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

3. 更新 .gitignore

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

4. 停止现有服务

docker-compose down

5. 使用新方式启动

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

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

6. 验证服务状态

# 检查所有服务是否健康
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

回滚方案

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

恢复配置文件：

cd server
cp .env.backup .env

使用旧版 docker-compose.yml：

git checkout HEAD~1 docker-compose.yml

重启服务：

docker-compose down
docker-compose up -d

影响评估

正面影响

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

潜在风险

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

兼容性

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

后续优化建议

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

变更作者

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

7.3 KiB Raw Blame History