diff --git a/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md index c573d8f..a0d535e 100644 --- a/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md +++ b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md @@ -28,6 +28,23 @@ cd ai_knowledge_base_v2 docker compose -f docker-compose.dev.yml up --build ``` +## 生产环境启动 + +生产环境必须使用 `docker-compose.prod.yml`。先复制根目录 `.env.example` 为 `.env`,替换其中全部示例密码和密钥,再执行: + +```bash +docker compose -f docker-compose.prod.yml config --quiet +docker compose -f docker-compose.prod.yml up -d --build +``` + +生产编排只向宿主机暴露统一网关端口;MySQL、Redis、后端、用户端和管理端均仅在容器网络内访问。用户端与管理端使用 Nginx 静态镜像,后端默认启动 4 个 worker。 + +`DATABASE_URL` 和 `REDIS_URL` 中的密码如包含 `@`、`:`、`/`、`#` 等特殊字符,必须先进行 URL 编码。`CONFIG_ENCRYPTION_KEY` 可通过以下命令生成,生成后必须妥善备份且不能随意更换: + +```bash +python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" +``` + 如果用户端问答需要直读飞书知识库,优先在管理后台“系统设置 / 外部服务”中配置飞书 AppID 和 AppSecret,保存后即可生效,不需要重建容器。 也可以在启动前通过后端运行环境变量配置,作为系统设置为空时的兜底: @@ -126,7 +143,7 @@ BACKUP_DIR=./backups ./scripts/mysql_backup.sh ## 生产待补事项 -- 前端生产镜像建议改为 Nginx 静态服务,不使用 Vite dev server。 -- 模型 API Key 建议加密保存或使用密钥管理服务。 -- 后端需要接入结构化日志采集。 -- 需要配置 HTTPS、域名、访问日志和基础监控。 +- 在域名入口或上游反向代理配置 HTTPS 证书。 +- 接入集中式结构化日志、主机与容器指标监控和异常告警。 +- 根据正式流量压测结果调整 worker、数据库连接池和问答队列参数。 +- 定期执行数据库备份和恢复演练,并单独备份 `CONFIG_ENCRYPTION_KEY`。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-remediation.md b/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-remediation.md index b9fc9eb..82194c7 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-remediation.md +++ b/ai_knowledge_base_v2/development_records/2026-07-10-production-readiness-remediation.md @@ -28,4 +28,28 @@ ## 实施记录 -实施过程中按批次记录对应提交、验证结果和必要决策。每批代码修改均单独提交并推送。 +### 已完成批次 + +1. `5aca872`:修复排队分支未定义变量;新增每日额度日期、数据库迁移和按上海自然日自动重置。 +2. `aedecb3`:新增短信手机号/IP 限流、短信验证码错误锁定、管理员登录限流与锁定,并将退出 Token 撤销状态迁移到 Redis。 +3. `9fb3dad`:新增敏感配置加密服务;模型 API Key、飞书 AppSecret、阿里云 AccessKey Secret 加密保存,后台接口仅返回掩码。 +4. `fb39c9c`:新增生产前端静态镜像、生产网关和 `docker-compose.prod.yml`,关闭 debug/mock,内部服务不暴露宿主机端口。 +5. `7f835ec`:锁定后端直接依赖版本,修复 SQLite 验证,新增六项关键测试并扩展自动验证脚本。 +6. `076fcb9`:将后台登录页面从总控页面提取为独立组件;安全状态与敏感配置已分别由独立后端服务承载。 + +### 验证结果 + +- `./scripts/phase6_verify.sh` 全部通过:44 个 OpenAPI 路径、6 项关键测试、4 个数据库迁移、用户端构建、管理端构建、开发与生产 Compose 配置检查。 +- 三个生产镜像均构建成功:后端、用户端 Nginx 静态镜像、管理后台 Nginx 静态镜像。 +- 隔离生产环境以 4 个后端 worker 启动成功,MySQL 和 Redis 健康检查通过。 +- `/api/health`、`/`、`/login/` 和 `/login/assets/...` 均返回 200。 +- 实际接口验证:管理员登录成功;飞书 Secret 接口返回 `******`;数据库保存值以 `enc:v1:` 开头且不包含明文;管理员退出后原 Token 返回 401。 +- 验证完成后已删除隔离容器、网络和测试数据卷,不影响开发环境及正式数据。 + +### 实施决策 + +- 自然日统一按 `Asia/Shanghai` 计算,符合国内用户业务口径。 +- Redis 是生产环境安全状态和并发队列的共享存储;短暂故障时使用进程内降级,保证接口仍有基础保护。 +- 历史明文密钥允许兼容读取,下一次后台保存时转为密文,避免升级直接破坏现有配置。 +- 生产环境缺少 `CONFIG_ENCRYPTION_KEY` 时后端拒绝启动,防止误以为已经加密而实际使用弱兜底密钥。 +- 本轮只拆分行为边界清晰的登录页、安全状态和密钥服务,不重写已经稳定运行的飞书检索算法;后续页面继续按业务模块渐进拆分。