graph_rag_server/DEPLOYMENT_CHECKLIST.md

部署前检查清单

在将 RAG 系统部署到生产环境之前，请确保完成以下所有检查项。

📋 代码质量

• 所有代码通过 flake8 检查（无语法错误）
• 代码格式符合 black 标准
• 导入语句按 isort 规范排序
• 类型提示完整（mypy 检查通过）
• 所有公共 API 有文档字符串

验证命令:

flake8 src tests
black --check src tests
isort --check-only src tests
mypy src

🧪 测试

• 所有单元测试通过
• 所有集成测试通过（如果适用）
• 端到端测试通过（如果适用）
• 测试覆盖率 ≥ 80%
• 领域层覆盖率 ≥ 90%
• 关键路径有测试覆盖

验证命令:

pytest tests/unit -v
pytest tests/integration -v
pytest --cov=src --cov-report=html

📚 文档

• README.md 已更新
• API 文档完整（docs/api.md）
• 架构文档完整（docs/architecture.md）
• 部署文档完整（docs/deployment.md）
• 开发指南完整（docs/development.md）
• 配置文档完整（docs/configuration.md）
• 变更日志已更新（CHANGELOG.md）
• 迁移指南已创建（如果有破坏性变更）

🔧 配置

• .env.example 包含所有必需的配置项
• 生产环境配置已准备
• 数据库连接配置正确
• 向量数据库配置正确
• 日志配置适合生产环境
• 安全配置已审查（密钥、密码等）

🗄️ 数据库

• 数据库迁移脚本已创建
• 迁移脚本在测试环境验证
• 数据库备份策略已制定
• 回滚计划已准备

验证命令:

alembic current
alembic history
alembic upgrade head --sql  # 预览 SQL

🐳 Docker

• Dockerfile 已优化
• docker-compose.yml 配置正确
• 多阶段构建正常工作
• 健康检查配置正确
• 数据卷配置正确
• 网络配置正确
• 资源限制已设置

验证命令:

docker build -f docker/Dockerfile --target production -t rag-system:test .
docker-compose -f docker/docker-compose.yml config

🔒 安全

• 所有密码和密钥使用环境变量
• 不在代码中硬编码敏感信息
• CORS 配置正确
• API 速率限制已配置
• 依赖包安全扫描通过
• 代码安全扫描通过

验证命令:

safety check
bandit -r src

📊 性能

• 关键 API 端点性能测试通过
• 数据库查询已优化
• 索引已创建
• 缓存策略已实施（如果需要）
• 连接池配置合理

🔄 CI/CD

• GitHub Actions 工作流配置正确
• 所有 CI 检查通过
• 代码覆盖率报告正常
• 部署流程已测试

🔙 向后兼容性

• 旧 API 端点仍然可用（通过适配器）
• 废弃警告已添加
• 迁移指南已提供
• 向后兼容性测试通过

📝 代码清理

• 旧代码已标记为废弃
• 未使用的导入已清理
• 调试代码已移除
• TODO 注释已处理
• 临时文件已删除

🚀 部署准备

• 部署脚本已准备
• 回滚脚本已准备
• 监控和告警已配置
• 日志聚合已配置
• 备份策略已实施
• 灾难恢复计划已制定

✅ 最终验证

运行最终验证脚本：

python scripts/final_verification.py

所有检查应该通过。

📞 部署后验证

部署完成后，执行以下验证：

• [ ] 健康检查端点响应正常

  curl http://your-domain/health
  

• [ ] API 文档可访问

  curl http://your-domain/docs
  

• [ ] 创建测试文档成功

  curl -X POST http://your-domain/api/v1/documents/ \
  -H "Content-Type: application/json" \
  -d '{"content": "test", "metadata": {}}'
  

• [ ] 搜索功能正常

  curl -X POST http://your-domain/api/v1/documents/search \
  -H "Content-Type: application/json" \
  -d '{"query_text": "test", "top_k": 10}'
  

• [ ] 日志正常输出

• [ ] 监控指标正常

• [ ] 数据库连接正常

• [ ] 向量数据库连接正常

🆘 回滚计划

如果部署出现问题，执行以下步骤：

1. 立即回滚到上一个版本

   # Docker
   docker-compose down
   docker-compose up -d --force-recreate
      
   # Kubernetes
   kubectl rollout undo deployment/rag-system
   

2. 恢复数据库（如果需要）

   alembic downgrade -1
   # 或从备份恢复
   psql rag_system < backup.sql
   

3. 通知相关人员

4. 记录问题和原因

5. 修复问题后重新部署

📋 签署

完成所有检查后，请相关人员签署：

• 开发负责人: _________________ 日期: _______
• 测试负责人: _________________ 日期: _______
• 运维负责人: _________________ 日期: _______
• 项目经理: _________________ 日期: _______

---

注意: 此检查清单应该在每次部署前完整执行。不要跳过任何步骤！