eval_752
  • 简体中文

      • Docker Compose v2（FastAPI + Celery 架构）

      更新日期：2026-03-13 · 对应任务：P2-OPS-013 / P2-DOC-014

      该文档介绍如何在本地通过 Docker Compose 启动 FastAPI API、Celery Worker/Beat、PostgreSQL、Redis 与 React SPA。默认路径现在是 real-provider-first workspace：基础拓扑会启动，但不会自动注入 fake provider、fake gateway 或 sample dataset。

      如果你是部署用户而不是仓库开发者，优先使用仓库根目录的 docker-compose.ghcr.yml：它直接拉取 GHCR 中预构建的 backend / celery / frontend 镜像，不需要本地 build。

      1. 目录结构

      .
├── docker/
│   ├── backend.Dockerfile   # FastAPI + Celery 基础镜像（uv）
│   ├── celery.Dockerfile    # Celery stand-alone 构建入口（可选）
│   └── frontend.Dockerfile  # Vite SPA 占位镜像
├── docker-compose.yml       # 新架构 Compose 文件
└── .env.example             # 环境变量模板（仓库根目录）

      2. 环境变量

      默认用户路径应先复制仓库模板，再启动 Compose：

      推荐步骤：

      cp .env.example .env
openssl rand -hex 32  # 填入 ENCRYPTION_KEY
# 编辑 POSTGRES_PASSWORD / DATABASE_URL 保持一致
docker compose up --build

      .env.example 现在只保留启动拓扑、密钥与构建层变量。工作区级的 completion timeout / retry / cancellation policy 已迁入 Settings 页面并持久化到数据库，不再要求用户通过 .env 调整。

      其他默认：

      • REDIS_URL=redis://redis:6379/0
      • CELERY_BROKER_URL / CELERY_RESULT_BACKEND 默认指向 Redis
      • Provider 配置改由应用内的「Provider 管理」界面维护，不再通过环境变量注入。
      • 仅执行镜像构建时，可使用 docker-compose.build.yml（只包含 api/worker/frontend build 配置），避免在 CI 环境中解析数据库/Redis 变量。

      集成测试小贴士：local OpenAI-compatible test gateway 已移到 docker-compose.integration.yml。scripts/tests/run_docker_integration.sh 会自动把它与主 Compose 文件叠加，只在 integration / CI 路径中启用。

      3. 启动服务

      docker compose up --build

      该命令会同时启动：

      • FastAPI API（8000）
      • Celery worker / Celery beat
      • PostgreSQL 与 Redis
      • React SPA 预览容器（监听 5173，直接托管 pnpm build 产物）

      首次打开 UI 时，工作区应为空白但可用。请从 Providers 显式添加真实 provider，再导入或构建真实 dataset。

      Backend-only 模式

      仅需要 API + worker 时，可以点名需要的服务：

      docker compose up backend celery-worker celery-beat postgres redis -d

      或为 CI 创建一个极简 override/Make 目标，避免构建前端镜像。

      Integration-only gateway

      若你需要本地 deterministic fake gateway，请走集成测试路径，而不是默认用户路径：

      docker compose -f docker-compose.yml -f docker-compose.integration.yml up -d fake-openai

      或直接使用：

      scripts/tests/run_docker_integration.sh --up --with-beat

      本地开发模式（热重载）

      生产 Compose 配置会在构建阶段生成静态文件。若需要在本地开发时启用前端热重载，可复制 override 模板：

      cp docker-compose.override.example.yml docker-compose.override.yml

      该文件会挂载本地 frontend/ 目录到容器，允许实时修改代码。docker-compose.override.yml 已在 .gitignore 中，仅用于本地开发，不会提交到版本库。

      4. 数据持久化

      • PostgreSQL 数据保持在 pgdata volume。
      • Redis 数据保持在 redisdata volume。
      • 若需映射 Alembic 或应用日志，可在 docker-compose.yml 中追加自定义卷。

      5. 常用操作

      命令用途
      docker compose logs -f backend查看 API 日志
      docker compose exec backend uv run alembic upgrade head执行数据库迁移
      docker compose exec celery-worker uv run python -m eval_752.workers.app对 worker 运行诊断（示例）
      docker compose -f docker-compose.build.yml build backend frontendCI/本地仅构建镜像（无需数据库变量）
      docker compose down -v停止并删除 volume（慎用）

      6. 注意事项

      • 编译镜像时使用 uv sync --frozen，确保依赖与 uv.lock 一致。
      • 在生产环境部署前，请将 change-me 等默认密码替换为安全值，并考虑启用 TLS。
      • LiteLLM/第三方密钥应通过 Compose .env 或外部秘密管理服务注入，切勿写入镜像。
      • 后端与 Celery 镜像默认以 eval752 非 root 用户运行；如果挂载宿主机目录，请确保目录拥有者或权限允许该用户写入。
      • ENCRYPTION_KEY 是强制项；虽然 Compose 内置演示值，但在保存真实 Provider Key 前必须替换并在 API/worker/beat 间保持一致。
      • 每次容器启动前，backend entrypoint 会运行 python -m eval_752.scripts.check_database（日志前缀 [db-check]）。若提示 password authentication failed，说明 POSTGRES_PASSWORD 与 pgdata 中已有的密码不一致——请恢复旧密码或执行 docker compose down -v 后重新初始化。
      • 前端默认通过同源路径 /api 访问后端，frontend 容器会把 /api/* 反代到 backend:8000，因此即使走 HTTPS 或额外的反向代理也无需额外 CORS 配置。
      • 如需让前端访问其他 API（例如外部环境），设置 VITE_API_BASE_URL=https://api.example.com 后重新执行 docker compose build frontend（Vite 会在编译期嵌入值）。
      • 构建镜像时若网络较慢或在 ARM 设备上下载大体积 wheel（如 pyarrow）容易超时，可设置更长的超时： UV_HTTP_TIMEOUT=600 docker compose build backend（或写入 .env 并重试）。

      7. Prometheus 抓取配置

      后端默认暴露 /metrics，可被 Prometheus 抓取。以下示例片段可添加到你的 prometheus.yml：

      scrape_configs:
  - job_name: "eval752-api"
    metrics_path: /metrics
    static_configs:
      - targets:
          - "backend:8000"

      若通过反向代理或 Kubernetes 暴露服务，可根据实际地址调整 targets。更多指标说明请参考 运维监控。

      更多运维细节请参考：

      • ../development/backend.md — uv 命令参考
      • ../operations/configuration.md — 环境变量说明
      • docs/migration/backup-strategy.md — 数据备份策略