跳转至

数据库迁移与版本管理

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

总览

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

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

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

当前迁移链

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

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
  • 文档导航与内容已同步