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 仅 2 个服务:

服务	端口	说明
postgres	5432	PostgreSQL 16
api	8000	FastAPI 应用

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

本地开发部署

# 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	日志级别
DATABASE_URL	✅	—	PostgreSQL 连接 URL
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
BZZOIRO_BASE	❌	https://sports.bzzoiro.com/api/v2	bzzoiro 接口地址
API_FOOTBALL_KEY	❌	—	伤停数据源 Key
CORS_ORIGINS	❌	http://localhost:5173,...	允许的跨域来源

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 "描述"

已有迁移:

• 0001_initial: 初始 5 张表(leagues/teams/matches/match_stats/predictions)
• 0002_agent_outputs: predictions 加 mode + agent_outputs

备份与恢复

# 备份
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/校准度)