部署指南
最后更新：2026-03-14 · 负责人：DevOps
本文汇总了 Python/FastAPI + React 技术栈当前可用的部署路径，取代此前散落在 docs/docker
和 docs/ops 下的说明。后续所有部署变更都应先更新本页，再回填到其他引用位置。
Compose 深入附录
/zh/docker/compose-v2/ 用来承接更底层的容器拓扑细节。本页只保留推荐部署路径，把过细的
实现说明推到附录里。
1. 拓扑矩阵
2. 部署前检查
- Secrets 与配置：复制
.env.example→.env，生成 32-byteENCRYPTION_KEY，并设置唯一的 Postgres 凭据。若使用 Compose 部署，可以提交.env.prod.example用于复现，但真实 secrets 必须放在 vault 中。 - 制品：优先使用
.github/workflows/docker-publish.yml发布到 GHCR 的镜像；只有在验证尚未发布的本地改动时，才回退到docker compose -f docker-compose.build.yml build。 - 数据库：运行
uv run alembic upgrade head（Compose 入口已自动执行），并确认迁移能在目标数据库上成功完成。 - 健康检查端点：确保编排平台可以访问
/healthz与/metrics。Prometheus 抓取示例见 运维监控。
3. 部署配方
3.1 本地与 QA（Docker Compose）
- 会启动 FastAPI（
backend）、Celery worker/beat、PostgreSQL、Redis，以及静态前端容器。 - 若只验证后端：
docker compose up backend celery-worker celery-beat postgres redis -d。 - 集成 smoke（与 CI 同拓扑）：
scripts/tests/run_docker_integration.sh --full-run --fresh。 - 热更新、bind mounts 等额外覆盖项在
docker-compose.override.example.yml。 - 启动后，打开 UI，在
Providers中添加真实 provider，导入数据集，并在Settings中按需调整工作区运行时策略。
3.2 生产 Compose（单机）
- 创建
.env.prod，填入强化后的 secrets（例如用openssl rand -hex 32生成ENCRYPTION_KEY，数据库密码也使用随机值）。 - 拉取已发布镜像并启动：
docker compose -f docker-compose.ghcr.yml --env-file .env.prod pull && docker compose -f docker-compose.ghcr.yml --env-file .env.prod up -d。 - 前端容器会反向代理
/api→backend:8000；若 TLS 在其他层终止，请设置BACKEND_ORIGIN，确保 SPA 指向正确主机名。 - 夜间备份：
docker exec postgres pg_dump -Fc -f /backups/$(date +%F).dump eval752。
3.3 Kubernetes（多节点）— WIP
虽然仓库尚未提供官方 manifests，参考拓扑已经确定：
- 使用你偏好的工具（Helm/Kustomize）部署镜像；各工作负载分别运行在独立 Deployment 中（
api、celery-worker、celery-beat）。 - 使用托管 PostgreSQL（RDS、Cloud SQL、Flexible Server）和托管 Redis/KeyDB，以降低持久化运维成本。
- 通过
SealedSecret/ExternalSecret接入 vault secrets，并使用带 TLS 的 Ingress 暴露/api。
任务 P3-OPS-004 负责产出并发布官方 manifests；在它完成前，请把 Compose 中的环境变量映射进你自己的集群部署工具。
3.4 云平台基础组件
4. 验证清单
- 针对已部署前端运行
pnpm test:e2e-smoke（或完整pnpm test:e2e）。 - 访问
/metrics，确认 Prometheus target 抓取成功且耗时 <10 秒。 - 通过 UI 运行一个样例数据集，并确认 Celery 更新能在 5 秒内通过 SSE 到达前端。
- 验证备份链路：模拟
docker compose exec postgres pg_isready失败，并确认告警触发。