Profeto/docs/06-deployment.md

06 · 部署

前置要求

• Docker & Docker Compose
• bzzoiro API Key(必填)
• LLM API Key(必填,OpenAI / Deepseek / 兼容接口)

Docker Compose 部署(推荐)

# 1. 配置环境变量
cp .env.example .env
# 编辑 .env: 填 LLM_API_KEY / BZZOIRO_KEY

# 2. 启动(自动执行数据库迁移)
docker compose up -d --build

# 3. 验证
curl http://localhost:8000/health

docker-compose.yml 包含 3 个服务:

服务	端口	说明
postgres	5433	PostgreSQL 16
api	8000	FastAPI 应用(启动时自动执行 alembic upgrade head)
frontend	3000	React 前端(多阶段构建,nginx 服务静态文件)

数据卷 pgdata 持久化数据库,重启不丢数据。

注意: api 服务启动时会先执行 alembic upgrade head 迁移数据库,再启动 uvicorn。 容器内数据库连接自动使用 postgres 服务名(通过 compose environment 覆盖 .env 中的 DB_HOST)。

本地开发部署

# 1. 安装依赖
pip install -e ".[dev]"

# 2. 启动 PostgreSQL(单独)
docker run -d --name profeto-pg \
  -e POSTGRES_USER=football -e POSTGRES_PASSWORD=football -e POSTGRES_DB=football \
  -p 5432:5432 postgres:16-alpine

# 3. 配置 .env
cp .env.example .env

# 4. 建表
alembic upgrade head

# 5. 启动 API
uvicorn src.api.app:app --reload

# 6. 启动前端(另一个终端)
cd frontend && npm install && npm run dev

访问:

• API 文档: http://localhost:8000/docs
• 前端界面: http://localhost:5173

环境变量

变量	必需	默认值	说明
APP_ENV	❌	development	production / development
LOG_LEVEL	❌	INFO	日志级别
API_PORT	❌	8000	API 服务端口映射
FRONTEND_PORT	❌	3000	前端服务端口映射
POSTGRES_USER	✅	—	PostgreSQL 用户名
POSTGRES_PASSWORD	✅	—	PostgreSQL 密码
POSTGRES_DB	❌	football	PostgreSQL 数据库名
POSTGRES_PORT	❌	5433	PostgreSQL 端口映射
DATABASE_URL	✅	—	PostgreSQL 连接 URL(Docker 内会被覆盖)
LLM_PROVIDER	❌	openai	提供商名(仅标记)
LLM_API_KEY	✅	—	API Key
LLM_BASE_URL	❌	https://api.openai.com/v1	接口地址(Ollama/Deepseek 用)
LLM_MODEL	❌	gpt-4o	默认模型
LLM_TIMEOUT	❌	60	单次调用超时(秒)
LLM_SPECIALIST_MODEL	❌	—	专家模型(回落 LLM_MODEL)
LLM_AGGREGATOR_MODEL	❌	—	终裁模型(回落 LLM_MODEL)
BZZOIRO_KEY	✅	—	bzzoiro 数据源 Key
API_FOOTBALL_KEY	❌	—	伤停数据源 Key
CORS_ORIGINS	❌	http://localhost:5173,...	允许的跨域来源
SECRET_KEY	❌	—	加密主密钥(生产环境必填)
ADMIN_PASSWORD	❌	—	管理后台密码(留空=不启用)
ADMIN_API_KEY	❌	—	机器/脚本调用的 API Key

LLM 提供商配置示例

OpenAI

LLM_API_KEY=sk-xxxx
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o

Deepseek

LLM_API_KEY=sk-xxxx
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

Ollama(本地)

LLM_API_KEY=ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama3.1

分档配置(专家用便宜模型)

LLM_MODEL=gpt-4o
LLM_SPECIALIST_MODEL=gpt-4o-mini
LLM_AGGREGATOR_MODEL=gpt-4o

数据库迁移

Alembic 管理 schema 变更:

# 查看当前版本
alembic current

# 升级到最新
alembic upgrade head

# 回退一级
alembic downgrade -1

# 生成新迁移(改 models.py 后)
alembic revision --autogenerate -m "描述"

# 空迁移(手动写 SQL)
alembic revision -m "描述"

Docker Compose 自动迁移: api 容器启动时会自动执行 alembic upgrade head, 无需手动运行。本地开发时需手动执行迁移。

已有迁移:

• 0001_initial: 初始 5 张表
• 0002_agent_outputs: predictions 加 mode + agent_outputs
• 0003_injuries: 增加 injuries 表
• 0004_snapshot_and_constraints: 增加约束
• 0005_prediction_status_and_stats_provenance: 增加时间语义
• 0006-0012: 后续 schema 调整、约束命名对齐、partial unique index 等

备份与恢复

# 备份
docker exec profeto-postgres pg_dump -U football football > backup.sql

# 恢复
cat backup.sql | docker exec -i profeto-postgres psql -U football football

监控

• /health: 存活检查
• 日志:容器 stdout(docker compose logs -f api)
• 评估汇总:GET /api/v1/eval/summary(准确率/RMSAE/校准度)