Hindsight 如何关闭启动时自动迁移并在 CI/CD 中用 hindsight-admin 单独执行数据库迁移

Hindsight 如何关闭启动时自动迁移并在 CI/CD 中用 hindsight-admin 单独执行数据库迁移【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight如果你的 Hindsight 部署流程希望把“数据库 schema 变更”和“API 启动”拆开——迁移由 CI/CD 流水线里的独立步骤控制而不是让 API 进程在每次启动时顺手执行——本文给出完整操作路径通过环境变量HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPfalse关闭启动时自动迁移再用hindsight-admin run-db-migration在部署新镜像之前单独跑完迁移。以下事实来自 admin-cli 文档 与 configuration 文档。前置条件hindsight-admin随hindsight-api包一起安装安装后hindsight-admin可执行文件进入PATHpip install hindsight-api # 或 uv add hindsight-api两个关键特性决定了它在 CI/CD 里的用法hindsight-admin直连 PostgreSQL不走 HTTP API读取与 API 服务相同的配置环境变量以及当前工作目录下的.env文件。也就是说它操作的是HINDSIGHT_API_DATABASE_URL指向的那个数据库。文档建议把它跑在与 API 部署相同的主机/容器里以继承正确的配置并保证数据库网络可达。生产环境需要显式指定数据库连接串开发默认值是内嵌的pg0export HINDSIGHT_API_DATABASE_URLpostgresql://user:passhost:5432/hindsight其中user:passhost:5432/hindsight替换为你实际的数据库凭据与库名。在流水线中执行迁移run-db-migration用于把数据库迁移到最新版本。文档明确说明它的用途就是“把迁移与 API 启动分开例如在 CI/CD 流水线中或部署新版本之前执行”。不带选项时它迁移基础 schema 加上租户扩展发现到的全部租户 schema。# 基础 schema 所有已发现的租户 schema hindsight-admin run-db-migration # 只迁移某个租户 schema hindsight-admin run-db-migration --schema tenant_acme可选参数来自 admin-cli 文档 的选项表选项说明默认--schema,-s只迁移指定 schema省略则迁移基础 schema 加所有已发现的租户 schema所有 schema--embedding-dimension迁移后强制同步的 embedding 维度省略则跳过迁移后的维度同步跳过--skip-extension-reconcile跳过迁移后的向量/文本搜索索引 reconcile仅当HINDSIGHT_API_VECTOR_EXTENSION/HINDSIGHT_API_TEXT_SEARCH_EXTENSION与 schema 现有索引不一致时才会实际做工作。后端未变更时可让跨大量租户 schema 的无变更重迁移快很多执行 reconcile如果 CI 步骤运行在 API 镜像的容器内直接在容器/pod 里执行即可无需在 runner 上单独安装# Docker — exec into the API container docker exec -it hindsight-api hindsight-admin run-db-migration # Kubernetes — exec into an API pod kubectl exec deploy/hindsight-api -- hindsight-admin run-db-migration一个值得注意的部署细节如果数据库走 PgBouncer 之类的连接池configuration 文档 提供了HINDSIGHT_API_MIGRATION_DATABASE_URL——迁移专用的直连 URL设置后 advisory lock 和 Alembic 迁移会绕过连接池器使用它而不再走HINDSIGHT_API_DATABASE_URL。关闭 API 启动时的自动迁移configuration 文档 中该开关的定义是变量说明默认值HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPAPI 启动时是否执行数据库迁移trueadmin-cli 文档 也给出了同样的提示To disable automatic migrations on API startup, setHINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPfalse. This is useful when you want to run migrations as a separate step in your deployment pipeline.所以 API 的部署配置Docker-e参数、Kubernetes manifest、helm values 等需要加上HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPfalse验证文档给出两层可用的验证方式API 就绪检查。迁移完成后启动 APIAPI 暴露/health/live存活探针不碰数据库、/health/ready与/health就绪探针其中就绪探针会获取一个连接池连接并执行SELECT 1见 monitoring 文档。因此 CI 中迁移步骤之后API 容器返回 200 的就绪状态说明新 API 已成功连上并可使用迁移后的数据库curl -f http://localhost:8888/health/ready内嵌 Helm chart 已把readinessProbe配到/health如果你自己写了 manifest可按同样方式接线。核对迁移版本。Alembic 在数据库里维护alembic_version表迁移完成后可以直连数据库核对其值确认与本次部署版本对应的迁移记录一致。注意事项hindsight-admin是 PostgreSQL-only它使用二进制COPY、TRUNCATE等直接操作数据库数据类命令backup、restore、bank export/import、worker-status不支持 Oracle。但run-db-migration本身在 Oracle 上同样受支持见 oracle 文档且该文档建议迁移时与运行时使用相同的 embedding 模型必要时用--embedding-dimension N调整列维度。关闭自动迁移后迁移必须先于 API 启动完成流水线里的顺序应是“先跑run-db-migration再滚动新的 API 版本”。迁移命令默认还会执行向量/文本搜索索引的 reconcile当后端扩展未变更、且租户 schema 很多时可加--skip-extension-reconcile加速无变化的重迁移。同一份部署文档中还提供了HINDSIGHT_API_MIGRATION_CONCURRENCYPostgreSQL only用于并行迁移多个租户 schema仅当 schema 数量达到数十个以上或迁移本身很慢时才有收益每个并发 worker 约占 3 个数据库连接需保持在数据库max_connections的余量之内。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考