Dograh 开源语音AI平台 Alembic 数据库迁移体系解析80 版本迁移的设计经验【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograhDograh 是一个开源语音 AI 平台也是 Vapi、Retell 的自托管替代方案支持 On-Prem 部署、自带密钥BYOK、可视化工作流构建器、MCP 原生集成和电话系统对接。围绕这样一个快速迭代的语音 AI 平台数据库结构几乎每天都在变化。打开 api/alembic/versions/ 目录你会看到95 个版本迁移文件从第一张 workflows 表到最新的 webhook 投递记录完整记录了一次又一次的 schema 演进。本文将带你读懂这套基于 Alembic 的数据库迁移体系以及其中 80 版本沉淀下来的设计经验。为什么语音AI平台的数据库变化这么快从迁移历史能清晰看到产品演进的脉络——几乎每接入一个电话服务商就新增一组迁移演进阶段代表性迁移文件核心引擎93a1ddbb6ffd_add_workflow_model.py工作流、workflow_runs、workflow_definitions多租户与计费f6f19156bcb7_add_organisation_table.py、2159d4ac431a_added_quota_tables.py、7feef09d7cc6_add_price_per_second_usd.py电话服务商接入f2e1d0c9b8a7_add_plivo_mode.py、a188ff90e76f_add_vobiz_mode_for_workflow.py、b3a1c7e94f12_add_telnyx_mode.py、488eb58e4e6e_add_cloudonix_mode.py外呼活动与排队08bb6e7f1397_added_campaign_table.py、4735a1f0cdb3_add_queued_runs_table.py、fefdd1835b7d_retry_outbound_calls_for_campaigns.py知识与工具dc33eef8dabe_add_document_tables.py、ebc80cea7965_add_tools_model.py、0a1b2c3d4e5f_add_mcp_in_toolcategory.py对新手来说理解这套体系只需要先记住三样东西alembic.ini配置、env.py运行环境、versions/迁移链。迁移目录结构一览 整套迁移体系位于 api/alembic/结构非常标准文件作用api/alembic.iniAlembic 入口配置指定script_location %(here)s/alembicapi/alembic/env.py迁移运行环境数据库连接、autogenerate 钩子api/alembic/script.py.mako新迁移文件的生成模板api/alembic/versions/95 个迁移脚本构成一条完整版本链几个值得注意的细节数据库地址不写死在 ini 里。api/alembic.ini 中sqlalchemy.url 真正的连接串由 api/alembic/env.py 的get_url()从环境变量DATABASE_URL读取ini 仅作兜底。这让同一套代码在本地、Docker、远程主机上都能直接跑迁移。async 数据库引擎。Dograh 使用 SQLAlchemy 异步驱动env.py通过create_async_engineasyncio.run运行迁移见 api/alembic/env.py这是很多同步 Alembic 模板里见不到的适配。PostgreSQL 枚举插件。env.py顶部导入alembic_postgresql_enum让枚举类型的变更能被 autogenerate 正确感知避免枚举漏迁移。生成与执行两条命令走完全流程项目用脚本把迁移流程封装成了两步# 生成迁移交互式输入迁移名自动 autogenerate bash scripts/makemigrate.sh # 执行所有未应用的迁移到最新版本 bash scripts/migrate.shscripts/makemigrate.sh加载api/.env环境变量校验迁移名不少于 5 个字符后执行alembic revision --autogenerate。scripts/migrate.sh执行alembic upgrade head。scripts/run_migrate.sh容器/部署场景使用加载环境变量后同样upgrade head。autogenerate的对比基线来自 api/db/models.py 中的Base.metadata——模型定义就是 schema 的单一事实来源迁移文件只是它演进的快照。80 版本迁移沉淀的 7 条设计经验1️⃣ 命名即文档revision 描述性 slug所有迁移文件都遵循修订号_动作描述.py的格式例如384be6596b36_make_email_case_insensitive.py。95 个文件按字母序排列时恰好能按时间线读一遍产品历史。文件名里的 slug 由makemigrate.sh输入的迁移名生成模板见 api/alembic/script.py.mako。2️⃣ 用 env.py 钩子驯服 autogenerateautogenerate 并不总是对的Dograh 在 api/alembic/env.py 中注册了两个钩子include_object自动跳过主键上的冗余非唯一索引主键本身已有隐式唯一索引render_item修正唯一索引的生成逻辑模型列标记unique时确保生成的索引也是唯一的。同时开启了compare_typeTrue和compare_server_defaultTrue让字段类型和默认值的变更也能被自动捕获。3️⃣ 每个迁移独立事务env.py中设置了transaction_per_migrationTrueapi/alembic/env.py每个迁移脚本在一个独立事务中执行失败即整体回滚不会留下改了一半的中间状态对多租户平台尤其重要。4️⃣ 数据迁移也是迁移schema 变更之外迁移链里还夹着真正的数据修复例如3cd3155084a2_dedup_org_scoped_recordings.py用窗口函数找出各组织内的重复录音重写工作流 JSON 中的引用再软删除冗余行fefdd1835b7d_retry_outbound_calls_for_campaigns.py活动外呼失败重试00b0201ad918_backfill_org_model_configuration_v2.py模型配置 V2 回填。经验值得借鉴不可逆的数据迁移要显式声明——3cd3155084a2的downgrade()直接是pass并在注释里说明软删除的行仍在表中必要时可手动恢复。这比假装可回滚诚实得多。5️⃣ 并行分支用 merge revision 收口4d8e9b2a3c5f_drop_workflow_run_mode_enum.py 的down_revision是一个元组(cdcf9f65913b, f2e1d0c9b8a7)——典型的分支合并迁移两条并行开发线各自产生了头节点由这一个文件把分叉合回主线。Alembic 支持这种线性历史外的拓扑遇到alembic upgrade报多个 head错误时生成 merge revision 是标准解法。6️⃣ 渐进式 schema 演进为少写迁移而设计同一份文件展示了高级玩法把数据库枚举workflow_run_mode改成VARCHAR(64)。原因是——每次新增电话服务商都要改枚举类型都要发一次迁移改为 VARCHAR 后新服务商只需在应用代码里注册即可数据库零改动Python 侧枚举仍作为常量集合保留。文件里还硬编码了迁移时刻的旧值列表用于降级时重建枚举边界情况考虑得很细。类似的演进还有bee2a9fcc6a6_fix_datetime_to_be_in_utc.py时间戳统一为带时区的 UTC384be6596b36_make_email_case_insensitive.py用lower(email)函数式部分索引实现邮箱大小写不敏感的唯一约束ec010596a0b4_change_datatype_of_usage_to_float.py计费字段精度修正。7️⃣ 修复型迁移承认错误就地修正d0060de90c18_fix_migrations.py 是一个给迁移打补丁的迁移早期 autogenerate 为每张表的id主键生成了冗余索引这个迁移一次性清掉 12 张表的ix_*_id索引。配合env.py的include_object钩子经验 2保证问题不再复现。迁移写错了不改旧文件而是追加新的修复迁移是 Alembic 铁律——历史迁移文件一经应用就不可篡改。从迁移链看项目活跃度 ⭐一个开源项目迁移链的长度基本等于它迭代强度的刻度。Dograh 的 95 个迁移覆盖了语音工作流、外呼活动、多租户计费、知识库、webhook 投递等全部核心模块且每个迁移都成对提供upgrade()/downgrade()数据类迁移除外体现了可回滚优先的工程习惯。新手上手3 条常用命令命令用途alembic -c api/alembic.ini upgrade head应用全部未执行迁移alembic -c api/alembic.ini revision --autogenerate -m 描述对比模型生成新迁移alembic -c api/alembic.ini history查看版本链配套文档可参考 docs/deployment/update.mdx 中的部署更新流程以及 docs/contribution/setup.mdx 的本地开发环境搭建。总结Dograh 的 Alembic 迁移体系给新手的启示可以浓缩为三句话让 autogenerate 干活但用人写钩子兜底——env.py中的include_object/render_item是精华迁移链就是产品史——命名规范 线性历史 merge revision让 95 个文件依然可读数据迁移、修复迁移与 schema 迁移平级对待——不可逆就明确标注写错了就追加修复绝不篡改历史。对于正在用 SQLAlchemy Alembic 构建自己项目的开发者api/alembic/env.py 和 api/alembic/versions/ 值得当作一套活教材仔细研读。【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dograh 开源语音AI平台 Alembic 数据库迁移体系解析：80+ 版本迁移的设计经验
Dograh 开源语音AI平台 Alembic 数据库迁移体系解析80 版本迁移的设计经验【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograhDograh 是一个开源语音 AI 平台也是 Vapi、Retell 的自托管替代方案支持 On-Prem 部署、自带密钥BYOK、可视化工作流构建器、MCP 原生集成和电话系统对接。围绕这样一个快速迭代的语音 AI 平台数据库结构几乎每天都在变化。打开 api/alembic/versions/ 目录你会看到95 个版本迁移文件从第一张 workflows 表到最新的 webhook 投递记录完整记录了一次又一次的 schema 演进。本文将带你读懂这套基于 Alembic 的数据库迁移体系以及其中 80 版本沉淀下来的设计经验。为什么语音AI平台的数据库变化这么快从迁移历史能清晰看到产品演进的脉络——几乎每接入一个电话服务商就新增一组迁移演进阶段代表性迁移文件核心引擎93a1ddbb6ffd_add_workflow_model.py工作流、workflow_runs、workflow_definitions多租户与计费f6f19156bcb7_add_organisation_table.py、2159d4ac431a_added_quota_tables.py、7feef09d7cc6_add_price_per_second_usd.py电话服务商接入f2e1d0c9b8a7_add_plivo_mode.py、a188ff90e76f_add_vobiz_mode_for_workflow.py、b3a1c7e94f12_add_telnyx_mode.py、488eb58e4e6e_add_cloudonix_mode.py外呼活动与排队08bb6e7f1397_added_campaign_table.py、4735a1f0cdb3_add_queued_runs_table.py、fefdd1835b7d_retry_outbound_calls_for_campaigns.py知识与工具dc33eef8dabe_add_document_tables.py、ebc80cea7965_add_tools_model.py、0a1b2c3d4e5f_add_mcp_in_toolcategory.py对新手来说理解这套体系只需要先记住三样东西alembic.ini配置、env.py运行环境、versions/迁移链。迁移目录结构一览 整套迁移体系位于 api/alembic/结构非常标准文件作用api/alembic.iniAlembic 入口配置指定script_location %(here)s/alembicapi/alembic/env.py迁移运行环境数据库连接、autogenerate 钩子api/alembic/script.py.mako新迁移文件的生成模板api/alembic/versions/95 个迁移脚本构成一条完整版本链几个值得注意的细节数据库地址不写死在 ini 里。api/alembic.ini 中sqlalchemy.url 真正的连接串由 api/alembic/env.py 的get_url()从环境变量DATABASE_URL读取ini 仅作兜底。这让同一套代码在本地、Docker、远程主机上都能直接跑迁移。async 数据库引擎。Dograh 使用 SQLAlchemy 异步驱动env.py通过create_async_engineasyncio.run运行迁移见 api/alembic/env.py这是很多同步 Alembic 模板里见不到的适配。PostgreSQL 枚举插件。env.py顶部导入alembic_postgresql_enum让枚举类型的变更能被 autogenerate 正确感知避免枚举漏迁移。生成与执行两条命令走完全流程项目用脚本把迁移流程封装成了两步# 生成迁移交互式输入迁移名自动 autogenerate bash scripts/makemigrate.sh # 执行所有未应用的迁移到最新版本 bash scripts/migrate.shscripts/makemigrate.sh加载api/.env环境变量校验迁移名不少于 5 个字符后执行alembic revision --autogenerate。scripts/migrate.sh执行alembic upgrade head。scripts/run_migrate.sh容器/部署场景使用加载环境变量后同样upgrade head。autogenerate的对比基线来自 api/db/models.py 中的Base.metadata——模型定义就是 schema 的单一事实来源迁移文件只是它演进的快照。80 版本迁移沉淀的 7 条设计经验1️⃣ 命名即文档revision 描述性 slug所有迁移文件都遵循修订号_动作描述.py的格式例如384be6596b36_make_email_case_insensitive.py。95 个文件按字母序排列时恰好能按时间线读一遍产品历史。文件名里的 slug 由makemigrate.sh输入的迁移名生成模板见 api/alembic/script.py.mako。2️⃣ 用 env.py 钩子驯服 autogenerateautogenerate 并不总是对的Dograh 在 api/alembic/env.py 中注册了两个钩子include_object自动跳过主键上的冗余非唯一索引主键本身已有隐式唯一索引render_item修正唯一索引的生成逻辑模型列标记unique时确保生成的索引也是唯一的。同时开启了compare_typeTrue和compare_server_defaultTrue让字段类型和默认值的变更也能被自动捕获。3️⃣ 每个迁移独立事务env.py中设置了transaction_per_migrationTrueapi/alembic/env.py每个迁移脚本在一个独立事务中执行失败即整体回滚不会留下改了一半的中间状态对多租户平台尤其重要。4️⃣ 数据迁移也是迁移schema 变更之外迁移链里还夹着真正的数据修复例如3cd3155084a2_dedup_org_scoped_recordings.py用窗口函数找出各组织内的重复录音重写工作流 JSON 中的引用再软删除冗余行fefdd1835b7d_retry_outbound_calls_for_campaigns.py活动外呼失败重试00b0201ad918_backfill_org_model_configuration_v2.py模型配置 V2 回填。经验值得借鉴不可逆的数据迁移要显式声明——3cd3155084a2的downgrade()直接是pass并在注释里说明软删除的行仍在表中必要时可手动恢复。这比假装可回滚诚实得多。5️⃣ 并行分支用 merge revision 收口4d8e9b2a3c5f_drop_workflow_run_mode_enum.py 的down_revision是一个元组(cdcf9f65913b, f2e1d0c9b8a7)——典型的分支合并迁移两条并行开发线各自产生了头节点由这一个文件把分叉合回主线。Alembic 支持这种线性历史外的拓扑遇到alembic upgrade报多个 head错误时生成 merge revision 是标准解法。6️⃣ 渐进式 schema 演进为少写迁移而设计同一份文件展示了高级玩法把数据库枚举workflow_run_mode改成VARCHAR(64)。原因是——每次新增电话服务商都要改枚举类型都要发一次迁移改为 VARCHAR 后新服务商只需在应用代码里注册即可数据库零改动Python 侧枚举仍作为常量集合保留。文件里还硬编码了迁移时刻的旧值列表用于降级时重建枚举边界情况考虑得很细。类似的演进还有bee2a9fcc6a6_fix_datetime_to_be_in_utc.py时间戳统一为带时区的 UTC384be6596b36_make_email_case_insensitive.py用lower(email)函数式部分索引实现邮箱大小写不敏感的唯一约束ec010596a0b4_change_datatype_of_usage_to_float.py计费字段精度修正。7️⃣ 修复型迁移承认错误就地修正d0060de90c18_fix_migrations.py 是一个给迁移打补丁的迁移早期 autogenerate 为每张表的id主键生成了冗余索引这个迁移一次性清掉 12 张表的ix_*_id索引。配合env.py的include_object钩子经验 2保证问题不再复现。迁移写错了不改旧文件而是追加新的修复迁移是 Alembic 铁律——历史迁移文件一经应用就不可篡改。从迁移链看项目活跃度 ⭐一个开源项目迁移链的长度基本等于它迭代强度的刻度。Dograh 的 95 个迁移覆盖了语音工作流、外呼活动、多租户计费、知识库、webhook 投递等全部核心模块且每个迁移都成对提供upgrade()/downgrade()数据类迁移除外体现了可回滚优先的工程习惯。新手上手3 条常用命令命令用途alembic -c api/alembic.ini upgrade head应用全部未执行迁移alembic -c api/alembic.ini revision --autogenerate -m 描述对比模型生成新迁移alembic -c api/alembic.ini history查看版本链配套文档可参考 docs/deployment/update.mdx 中的部署更新流程以及 docs/contribution/setup.mdx 的本地开发环境搭建。总结Dograh 的 Alembic 迁移体系给新手的启示可以浓缩为三句话让 autogenerate 干活但用人写钩子兜底——env.py中的include_object/render_item是精华迁移链就是产品史——命名规范 线性历史 merge revision让 95 个文件依然可读数据迁移、修复迁移与 schema 迁移平级对待——不可逆就明确标注写错了就追加修复绝不篡改历史。对于正在用 SQLAlchemy Alembic 构建自己项目的开发者api/alembic/env.py 和 api/alembic/versions/ 值得当作一套活教材仔细研读。【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考