跳转至

数据库迁移与版本管理

本页描述 Chameleon 当前的 Alembic 迁移链路、执行方式与团队协作规范。

总览

项目使用 Alembic 管理 PostgreSQL 模式演进：

  • 配置入口：alembic.ini
  • 迁移环境：ai_service/migrations/env.py
  • 版本脚本目录：ai_service/migrations/versions/

env.py 会按顺序加载项目根目录的 .env 与 .env.local，再从环境变量读取 DATABASE_URL 作为迁移连接字符串。

运行时迁移策略

默认采用“开发自动，staging/production 手动”策略：

  • APP_ENV=development：默认 DB_MIGRATION_MODE=auto，应用启动前自动执行 uv run alembic upgrade head。
  • APP_ENV=staging/production：默认 DB_MIGRATION_MODE=manual，应用启动时不会自动迁移。
  • 可通过环境变量覆盖默认值：DB_MIGRATION_MODE=auto|manual。

当前仓库的 Dokploy 发布链路会将 staging/production 的 DB_MIGRATION_MODE 写为 auto，因此迁移在 ai-service 容器启动阶段执行，而不是在 GitHub Actions 中单独执行。

空库（brand-new database）行为说明：

  • 当前 revision 链主要用于兼容历史库增量演进；在核心业务表不存在时会安全 no-op。
  • 随后应用启动事件会执行 init_database()（Base.metadata.create_all）创建当前模型所需全量表结构。
  • 因此首次部署到全新 PostgreSQL 时，alembic upgrade head 不应再因缺表而失败。

生产发布建议：

  1. 确保部署环境配置 DB_MIGRATION_MODE=auto，并保证容器内 DATABASE_URL 可连通目标数据库。
  2. 对高风险迁移优先采用单实例滚动或维护窗口发布，避免多个实例并发启动同时触发迁移。

当前迁移链

截至当前仓库版本，迁移链如下：

flowchart LR
    V1[58d932c51f0c]
    V2[a3f1b7c92d4e]
    V3[687229cd5ed4]

    V1 --> V2 --> V3

版本说明

Revision down_revision 主要变更
58d932c51f0c None 新增 agent_knowledge_links.priority
a3f1b7c92d4e 58d932c51f0c 新增 ingestion_jobs.status_message
687229cd5ed4 a3f1b7c92d4e 新增分块策略字段到 knowledge_sources、ingestion_jobs、document_chunks

常用命令

先确保环境变量可用，尤其是 DATABASE_URL 或 POSTGRES_* 组合配置。

# 查看当前数据库版本
uv run alembic current

# 升级到最新版本
uv run alembic upgrade head

# 回滚一个版本
uv run alembic downgrade -1

# 基于模型变更生成迁移脚本
uv run alembic revision --autogenerate -m "describe change"

团队协作规范

1. 变更模型必须配套迁移

涉及以下文件变更时，应同时提交 Alembic revision：

  • ai_service/storage/models.py
  • 与表结构强耦合的服务逻辑或 API 字段

2. 迁移脚本应可读可回滚

  • upgrade() 和 downgrade() 都必须可执行。
  • 对线上敏感变更应拆分为多步小迁移，避免一次性高风险改动。

3. 与文档保持同步

修改数据模型后，请至少同步以下文档：

  • docs/database/schema.md
  • docs/database/migrations.md
  • 若 API 字段变化，同步 docs/guides/rag-knowledge-management.md 或 docs/api/endpoints.md

变更检查清单

在提交与数据库相关的 PR 前，建议逐项确认：

  • 已生成并提交迁移脚本
  • 本地执行 uv run alembic upgrade head 成功
  • 关键回滚路径可用 uv run alembic downgrade -1
  • 文档导航与内容已同步