Hindsight Admin CLI 运维指南迁移、备份恢复与 Worker 治理实战【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读hindsight-admin是 Hindsight 内置的管理命令行工具它绕过 HTTP API、直接连接 PostgreSQL为数据库迁移、整库备份恢复、向量索引修复、跨实例迁移以及分布式 Worker 任务治理提供了一整套运维入口。本文以 Admin CLI 参考文档 为骨架结合 hindsight-api-slim 源码 与 测试用例完整讲解每个子命令的用法、底层原理与实战注意点帮助你独立完成 Hindsight 部署的生命周期管理。安装与运行前提安装方式hindsight-admin随hindsight-api包一起分发安装后即可在PATH中使用pip install hindsight-api # 或使用 uv uv add hindsight-api对应的命令行入口在 pyproject.toml 中声明为hindsight-admin hindsight_api.admin.cli:main也就是说你执行的每个子命令最终都会进入 cli.py 的 Typer 应用。连接模型直连数据库不走 HTTPhindsight-admin通过asyncpg直接连接 PostgreSQL见 _admin_connect因此只支持 PostgreSQL不支持 Oracle 后端。源码模块 docstring 明确说明其依赖asyncpg.connect()、二进制COPY、TRUNCATE CASCADE、REFRESH MATERIALIZED VIEW等 PostgreSQL 专有能力它读取与 API 服务完全相同的配置环境变量 当前工作目录下的.env文件作用于HINDSIGHT_API_DATABASE_URL指向的数据库默认指向pg0嵌入式开发数据库此时必须在持有 pg0 数据的主机上运行生产环境则通过环境变量指定外部数据库例如HINDSIGHT_API_DATABASE_URLpostgresql://user:passhost:5432/hindsight。因此推荐的执行方式是在 API 部署所在的同一主机/容器内运行从而继承正确的配置并拥有数据库网络访问权# 裸机 / virtualenv复用 API 的环境变量或在工作目录放 .env hindsight-admin worker-status # Docker —— 进入 API 容器执行 docker exec -it hindsight-api hindsight-admin backup /data/backup.zip # Kubernetes —— 进入 API Pod 执行 kubectl exec deploy/hindsight-api -- hindsight-admin run-db-migration关于.env的加载有一个容易忽略的细节管理员 CLI 在main()入口显式调用load_dotenv_for_entrypoint()config.py它会从当前工作目录向上发现.env并以overrideTrue加载、随后清空配置缓存确保入口程序读取到的是.env生效后的最新配置。所有命令都支持--schema参数指定目标租户 schema默认作用于配置中的 base schema。run-db-migration独立执行数据库迁移命令与参数hindsight-admin run-db-migration [OPTIONS]Option说明默认值--schema,-s只迁移指定 schema省略时迁移 base schema 加所有已发现的租户 schema全部 schema--embedding-dimension迁移后强制校验的期望 embedding 维度省略则跳过迁移后的维度同步跳过--skip-extension-reconcile跳过迁移后的向量/全文检索索引对账仅当HINDSIGHT_API_VECTOR_EXTENSION/HINDSIGHT_API_TEXT_SEARCH_EXTENSION与 schema 现有索引不一致时才真正干活可大幅加速多租户 schema 的无变更重复迁移仅在后端未变更时使用执行对账示例# 迁移 base schema 加所有已发现的租户 schema hindsight-admin run-db-migration # 只迁移指定租户 schema hindsight-admin run-db-migration --schema tenant_acme源码级原理从 run_db_migration / _run_migration 可以看到实际执行逻辑未指定--schema时会通过TenantExtension.list_tenants()枚举全部租户 schema与 base schema 去重合并后一起迁移迁移按migration_concurrency并发执行每个 schema 一个独立进程schema 内部保持串行迁移完成后还会调用租户扩展的provision_bank_tables()为扩展自有的 bank 级表执行一次幂等建表使扩展 schema 与核心 schema 走同一生命周期。关闭启动期自动迁移API 启动时默认会自动执行迁移若希望把迁移作为部署流水线中的独立步骤可设置HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPfalse对应源码中的开关为 config.py 中的 ENV_RUN_MIGRATIONS_ON_STARTUP默认值为trueDEFAULT_RUN_MIGRATIONS_ON_STARTUP并在 main.py 与 server.py 中驱动。repair-bank修复 bank 级向量索引覆盖为什么需要修复Hindsight 为每个(bank, fact_type)组合维护部分向量索引。这些索引通常在 bank 首次创建时瞬时建立空 bank 上瞬间完成之后由 PostgreSQL 随数据增长增量维护。但一旦 bank绕过了创建路径被填充——例如逻辑恢复、跨版本升级、向量扩展切换——这些索引就不会自动出现导致该 bank 的召回查询静默回退到全局索引 后过滤模式。后过滤既更慢又可能漏召回近似最近邻搜索从所有 bank 抽取候选再过滤到你所在的 bank。repair-bank用于在以上任何事件之后恢复完整覆盖。它能识别缺失或无效的覆盖中断构建遗留的INVALID索引、后端切换后类型漂移的索引均视为缺失并用CREATE INDEX CONCURRENTLY重建——因此不会阻塞在线的 retain / recall / consolidation 流量。命令是幂等的可安全重复执行。命令与参数hindsight-admin repair-bank (--bank BANK_ID | --all) [OPTIONS]Option说明默认值--bank,-b要修复的 bank id与--all互斥—--all修复 base schema 与所有已发现租户 schema 中的每个 bank—--schema,-s限定单个 schema全部 schema--dry-run只报告将要修复的内容不创建/删除任何索引关闭--bank与--all必须二选一。对于使用单一全局向量索引的后端AlloyDB ScaNN、Oracle该命令是无操作。示例# 先查看哪些 bank 缺少覆盖不改变任何东西 hindsight-admin repair-bank --all --dry-run # 恢复/升级后一次性修复所有 bank hindsight-admin repair-bank --all # 修复单个 bank hindsight-admin repair-bank --bank acme-prod源码级原理从 _run_repair_bank / repair_bank 可以确认使用单条 autocommit 连接因为CREATE INDEX CONCURRENTLY不能在事务块内执行先通过_vector_index_clause()判断当前后端是否存在 per-bank 索引None即 AlloyDB ScaNN / Oracle直接提示无可修复遍历目标 schema 与 bank调用reconcile_bank_vector_indexes()对账并在--all模式下顺带清理孤儿索引bank 行已删除、从任何 bank 路径都无法触达的索引结束时输出present / created / dropped / failed等统计有失败索引时会打印清单并返回非零退出码提示重跑即可。另外源码中提到默认HINDSIGHT_API_VECTOR_INDEX_MIN_ROWS0时每个 bank 从存在那一刻起就应拥有全部三个索引设置了阈值后(bank, fact_type)行数达标才会建索引写入侧会通过vector_index_maintenance操作自动维持收敛——repair-bank的价值在于不等待写入、主动触发收敛如恢复、升级、后端切换后。backup / restore整库备份与恢复backuphindsight-admin backup OUTPUT [OPTIONS]ArgumentsArgument说明OUTPUT输出文件路径无.zip后缀会自动补上OptionsOption说明默认值--schema,-s要备份的数据库 schemapublic示例# 备份到文件 hindsight-admin backup /backups/hindsight-2024-01-15.zip # 备份指定租户 schema hindsight-admin backup /backups/tenant-acme.zip --schema tenant_acme备份内容源码 BACKUP_TABLES 严格按外键依赖顺序排列记忆库banks及其配置、attachments、documents、document_attachmentsentities、chunks、memory_units、invalidated_memory_units、unit_entities、entity_cooccurrences、memory_links、observation_historymental_models、mental_model_history、knowledge_pages、directiveswebhooks、file_storage内部运维表async_operations、audit_log、llm_requests、graph_maintenance_queue、entity_maintenance_queue 等保证恢复后能复现完整的全库快照。一致性保证备份在REPEATABLE READ隔离级别的事务内完成见 _backup所有表处于一致的快照避免entity_cooccurrences引用到entities备份之后才创建的行这类竞态。restorehindsight-admin restore INPUT [OPTIONS]⚠️ 警告恢复会删除目标 schema 中的全部现有数据。ArgumentsArgument说明INPUT输入备份文件.zipOptionsOption说明默认值--schema,-s恢复到的目标 schemapublic--yes,-y跳过确认提示false示例# 带确认提示恢复 hindsight-admin restore /backups/hindsight-2024-01-15.zip # 脚本中使用跳过确认 hindsight-admin restore /backups/hindsight-2024-01-15.zip --yes # 恢复到指定租户 schema hindsight-admin restore /backups/tenant-acme.zip --schema tenant_acme --yes恢复流程的源码级细节从 _restore 可以看到完整的恢复管线校验 manifest检查备份版本是否为MANIFEST_VERSION当前为2事务外预检 schema 兼容性_validate_restore_schema逐个表对比备份列与目标列的format_type。目标缺失的列不会报错——通过_strip_binary_copy_fields()从二进制 COPY 流中按位置剔除对应字段后继续恢复否则任何列删除迁移都会让旧备份永久不可恢复而类型不匹配仍然致命会在破坏性操作开始前给出明确报错单事务内原子恢复按BACKUP_TABLES逆序TRUNCATE ... CASCADE先清子表再清父表尊重外键再正序以二进制 COPY 回放刷新物化视图memory_units_bm25同步自增序列_sync_owned_sequences把非循环 identity 序列推进到恢复出的最大列值之后避免后续插入主键冲突。测试文件 test_admin_backup_restore.py 中还有一条重要约束BACKUP_TABLES必须覆盖 schema 的全部持久表test_backup_tables_covers_entire_schema漏掉一张表会在恢复时因TRUNCATE banks CASCADE连带清空其外键子表数据——所以任何新增建表迁移都必须同步更新该列表否则 CI 会失败。务必确认恢复前请确认手头有最近的备份。decommission-worker / decommission-workersWorker 任务释放decommission-worker释放单个 Workerhindsight-admin decommission-worker WORKER_ID [OPTIONS]ArgumentsArgument说明WORKER_ID要退役的 worker 的 IDOptionsOption说明默认值--schema,-s数据库 schemapublic--yes,-y跳过确认提示false示例# 缩容前释放被移除 worker 的任务 hindsight-admin decommission-worker hindsight-worker-4 hindsight-admin decommission-worker hindsight-worker-3 # 释放崩溃 worker 的任务 hindsight-admin decommission-worker worker-2 # 指定租户 schema hindsight-admin decommission-worker worker-1 --schema tenant_acme适用场景缩容在 Kubernetes 移除 worker 副本之前优雅下线维护时让 worker 离线崩溃恢复worker 处理任务期间崩溃卡死 Workerworker 无响应时。寻找 Worker ID 的技巧Worker ID 默认取主机名。Kubernetes StatefulSet 中即 Pod 名如hindsight-worker-0。也可用HINDSIGHT_API_WORKER_ID环境变量或--worker-id参数自定义。decommission-workers释放全部 Workerhindsight-admin decommission-workers [OPTIONS]OptionsOption说明默认值--schema,-s数据库 schemapublic--yes,-y跳过确认提示false示例# 释放所有 worker 的全部处理中任务带确认 hindsight-admin decommission-workers # 跳过确认脚本中用 hindsight-admin decommission-workers --yes # 释放指定租户 schema 中的任务 hindsight-admin decommission-workers --schema tenant_acme适用场景未知的死亡 Worker多个 Worker 崩溃且不知道它们的 ID全队列级恢复基础设施事件后大量 Worker 下线一次性全部修复逐个清理过于繁琐时快速排空队列。⚠️ 注意该命令会释放每一个处理中的任务包括健康 Worker 拥有的。知道具体目标时应优先用decommission-worker WORKER_ID。底层实现两者都是对async_operations表执行一次状态翻转见 _decommission_worker 与 _decommission_all_workersUPDATE schema.async_operations SET status pending, worker_id NULL, claimed_at NULL, updated_at now() WHERE worker_id $1 AND status processing -- 单 worker 版 -- WHERE status processing -- 全量版把processing行重置为pending后存活的 Worker 会在下一次轮询时重新认领。注意两个命令默认都带确认提示除非加--yes。worker-status排查处理中任务hindsight-admin worker-status [OPTIONS]OptionsOption说明默认值--schema,-s数据库 schemapublic示例# 展示所有 Worker 的处理中任务 hindsight-admin worker-status # 查看指定租户 schema 的处理中任务 hindsight-admin worker-status --schema tenant_acme输出内容对应 _worker_status 的查询按 Worker 分组展示每个处理中任务的operation_id前 8 位、operation_type、bank_id、running_for运行时长与last_update_ago距上次更新的时间。适用场景退役前排查查看哪些 Worker 有陈旧任务、卡了多久吞吐调试队列迟迟不排空时判断任务是否卡在processing健康检查last_update_ago持续增长的 Worker 往往已死或失联。export-bank / import-bank跨实例迁移单个 Bankexport-bank导出hindsight-admin export-bank --bank BANK_ID --output FILE.zip [OPTIONS]OptionsOption说明默认值--bank,-b要导出的 bank id必填--output,-o输出的.zip归档路径必填--schema,-sbank 所在的 schemabase schema--include-history同时导出运维历史audit_log、llm_requestsfalse示例hindsight-admin export-bank --bank my-bank --output my-bank.zip # 包含运维历史 hindsight-admin export-bank --bank my-bank --output my-bank.zip --include-history导出内容为文档、事实、观察、bank 配置、心理模型、指令与 webhooks。Embedding 永不导出导入时会在目标实例上重新生成。只读操作可对在线实例安全执行。PostgreSQL only。源码层面导出由 engine/transfer/export.py 的 export_bank 实现它以文档/事实/观察的逻辑导出为基座附上各 bank 级表的 JSON 行转储与知识页--include-history额外携带audit_log、llm_requests运维尾巴。文档注释明确说明目标端会重新生成每个向量因此这里没有任何编码器相关的内容。import-bank导入hindsight-admin import-bank --archive FILE.zip [OPTIONS]OptionsOption说明默认值--archive,-aexport-bank产出的.zip路径必填--schema,-s目标 schemabase schema--target-bank覆盖 bank id默认用归档中的源 bank id源 bank--include-history归档中存在历史时一并恢复false示例hindsight-admin import-bank --archive my-bank.zip导入时事实会用本实例配置的 embedding 模型重新向量化并重建链接与索引bank 配置、心理模型、指令与 webhooks 原样恢复。不会运行 LLM 事实抽取且因为是迁移恢复状态不会触发 webhook也不会重跑 consolidation。PostgreSQL only。从源码看_run_import_bank导入会惰性启动一个MemoryEngine(run_migrationsTrue)——这样全新目标实例会在恢复前按本实例的 embedding 维度/向量/全文检索后端完成建库迁移再以internalTrue的请求上下文调用engine.import_bank_async()回放归档。⚠️ 目标 bank 必须不存在导入恢复的是整个 bank配置、事实、心理模型等不是合并。若目标 id 的 bank 已存在命令会失败。请先删除该 bank或用--target-bank以全新 id 恢复。蓝绿迁移手册Blue-Green Runbook更换 bank 的embedding 模型如 384 维编码器 → 1024 维、向量扩展pgvector / vchord / pgvectorscale或全文检索后端时无法在已填充数据的 bank 上原地完成——存量向量与索引与这些设置强绑定。由于每个 embedding 和索引都是磁盘上文本的确定性函数官方支持路径是把 bank 迁到配置了新设置的全新实例在那里重新推导一切且无需 LLM 重新抽取。在全新数据库上搭建新实例配置新的 embedding 模型 / 向量扩展 / 全文检索后端在维护窗口内停写源 bank 的写入并先运行hindsight-admin backup备份兜底源端导出、目标端导入# 源实例上 hindsight-admin export-bank --bank my-bank --output my-bank.zip # 目标实例上已配置新设置 hindsight-admin import-bank --archive my-bank.zip在目标端验证跑若干代表性召回查询并与源端对比将流量切换到新实例。旧实例保留作为即时回滚直到你完全放心。为什么必须新实例而非原地改embedding 模型是服务级配置且 bank 的memory_units.embedding列在 schema 内共享单一维度——不同维度/不同后端的 bank 需要自己的实例与数据库。旧向量从不被改动这让回滚变得极其简单。实战恢复卡死或僵尸操作僵尸操作指某任务因认领它的 Worker 已消失而永远卡在processing。最常见的根因是HINDSIGHT_API_WORKER_ID不稳定当它默认取容器主机名时Docker 重启会产生新容器 ID新 Worker 不承认旧 Worker 的认领这些任务就被搁浅。如何发现# 按 Worker 列出处理中任务 —— last_update_ago 持续增长的 Worker 已死 hindsight-admin worker-status # bank 级计数器pending_consolidation 只增不减是典型症状 curl -s http://localhost:8888/v1/default/banks/bank_id/stats如何恢复# 你知道哪个 Worker 死了例如从 worker-status 得知 hindsight-admin decommission-worker old-worker-id # 你不知道 —— 释放全队列的处理中任务 hindsight-admin decommission-workers两个命令都会把processing行重置为pending让存活的 Worker 在下次轮询时认领。如何预防设置稳定的HINDSIGHT_API_WORKER_ID使 Worker 身份在重启后保持不变Docker传-e HINDSIGHT_API_WORKER_IDhindsight-prod多容器时按副本命名KubernetesHelmChart 的 StatefulSet 自动使用 Pod 名无需额外配置裸机 / pip传--worker-id name或按进程设置环境变量。源码中DEFAULT_WORKER_ID Noneconfig.py未设置时回退到主机名——这正是僵尸操作的温床。环境变量速查Admin CLI 与 API 服务共用同一套环境变量最关键的是Variable说明默认值HINDSIGHT_API_DATABASE_URLPostgreSQL 连接串pg0嵌入式与之配套、在本文各场景中出现过的环境变量还包括Variable说明HINDSIGHT_API_DATABASE_SCHEMA默认数据库 schema默认publicHINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP是否在 API 启动时自动迁移默认trueHINDSIGHT_API_VECTOR_EXTENSION向量后端pgvector / vchord 等HINDSIGHT_API_TEXT_SEARCH_EXTENSION全文检索后端HINDSIGHT_API_WORKER_ID显式指定 Worker ID默认取主机名示例# 使用指定数据库 export HINDSIGHT_API_DATABASE_URLpostgresql://user:passlocalhost:5432/hindsight hindsight-admin backup /backups/mybackup.zip小结hindsight-admin覆盖了 Hindsight 运维的三个核心面Schema 生命周期run-db-migration、repair-bank、数据安全与迁移backup/restore/export-bank/import-bank以及分布式队列治理worker-status/decommission-worker/decommission-workers。它直连 PostgreSQL 的特性决定了所有操作都在数据库层完成因此务必牢记三个纪律恢复操作会清空目标 schema、导入目标 bank 不能已存在、decommission-workers会释放所有 Worker 的任务。结合稳定的HINDSIGHT_API_WORKER_ID与新实例 重新向量化的迁移范式即可在生产环境安全地完成 Hindsight 的部署、升级与演进。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考