尧图网站建设 
Hindsight Admin CLI 运维实战数据库迁移、备份恢复与 Worker 治理【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsighthindsight-admin是 Hindsight 部署自带的命令行管理工具覆盖数据库迁移、全库备份/恢复、按银行bank粒度导出导入、以及后台 Worker 任务治理等日常运维操作。本指南以 Admin CLI 官方文档 为主线结合仓库内 CLI 实现 与测试用例逐条讲解命令的用途、参数、适用场景与底层原理读完后你可以独立完成生产环境的迁移升级、灾难恢复与僵尸任务排查。一、认识 Admin CLI直连数据库的运维通道hindsight-admin是一组 PostgreSQL 专属的管理命令与 HTTP API 不同它不经过 API 服务而是通过asyncpg直接连接 PostgreSQL二进制COPY、TRUNCATE CASCADE、REFRESH MATERIALIZED VIEW等底层操作天然依赖 PG 特性因此不支持 Oracle 后端。这一点在源码模块 docstring 中有明确说明见 cli.py。它读取与 API 服务完全相同的配置——环境变量以及当前工作目录下的.env文件——所以它操作的就是HINDSIGHT_API_DATABASE_URL指向的那个数据库默认值pg0即 Hindsight 内置的嵌入式开发数据库必须在持有 pg0 数据的主机上运行生产环境设置HINDSIGHT_API_DATABASE_URLpostgresql://user:passhost:5432/hindsight。连接逻辑见 cli.py_admin_connect会先解析pg0://URL必要时启动嵌入式 PG再注册json/jsonb类型编解码器保证导出行数据能正确解码为 Python 对象。安装与入口Admin CLI 随hindsight-api包一起分发安装后hindsight-admin可执行文件即进入PATHpip install hindsight-api # 或 uv add hindsight-api其入口在 pyproject.toml 中注册hindsight-admin hindsight_api.admin.cli:main而main()首先调用load_dotenv_for_entrypoint()加载.env再启动 typer 应用见 cli.py。在裸机、Docker 与 Kubernetes 中运行由于命令直连数据库务必在与 API 部署相同的主机/容器上运行以继承正确配置并保证网络可达# 裸机 / virtualenv复用 API 的环境变量或在工作目录放 .env hindsight-admin worker-status # Docker —— exec 进 API 容器 docker exec -it hindsight-api hindsight-admin backup /data/backup.zip # Kubernetes —— exec 进 API Pod kubectl exec deploy/hindsight-api -- hindsight-admin run-db-migration命令默认操作配置的 base schema多租户部署下可用--schema指定某个租户 schema详见下文环境变量一节。二、run-db-migration把迁移从启动流程中拆出来run-db-migration将数据库迁移到最新版本。默认迁移 base schema加上租户扩展发现的所有租户 schema传--schema则只迁移指定 schema。适合在 CI/CD 流水线中、或部署新版本前作为独立步骤执行。hindsight-admin run-db-migration [OPTIONS]参数选项说明默认--schema,-s要迁移的数据库 schema省略则迁移 base schema 及全部已发现的租户 schema全部 schema--embedding-dimension迁移后要强制的预期 embedding 维度省略则跳过迁移后的维度同步跳过--skip-extension-reconcile跳过迁移后的向量 / 全文检索索引 reconcile仅在HINDSIGHT_API_VECTOR_EXTENSION/HINDSIGHT_API_TEXT_SEARCH_EXTENSION与 schema 现有索引不一致时才需要做事。后端未变更时可显著加速跨大量租户 schema 的无变更重迁移正常执行 reconcile示例# 迁移 base schema 全部已发现租户 schema hindsight-admin run-db-migration # 迁移指定租户 schema hindsight-admin run-db-migration --schema tenant_acme从源码看cli.py_run_migration先通过租户扩展的list_tenants()收集 schema 列表并去重保序再以migration_concurrency为并发度每个 schema 一个进程、schema 内部串行调用run_migrations_for_schemas核心迁移完成后还会对每个 schema 执行租户扩展声明的 bank 级扩展表的 provisioner_provision_extra_bank_tables让扩展 schema 与核心 schema 遵循同一生命周期演进cli.py。:::tip 关闭启动时自动迁移 若希望把迁移作为部署流水线中的独立步骤可设置HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPfalse默认开启见 config.py 与DEFAULT_RUN_MIGRATIONS_ON_STARTUP避免 API 启动时重复执行迁移。 :::三、repair-bank修复银行级向量索引覆盖Hindsight 会为每个(bank, fact_type)组合创建部分向量索引。这些索引通常在银行创建时即刻生成空库上瞬间完成之后由 PostgreSQL 增量维护。但以下几种场景会让银行在创建路径之外被填充从而永远得不到这些索引逻辑恢复logical restore跨版本升级向量扩展切换vector-extension switch。缺失索引时银行的 recall 会静默回退到「全局索引 后过滤」既更慢又可能少返回结果近似最近邻搜索先从所有银行里取候选再过滤到你的银行。repair-bank用于校验并修复这种覆盖。它会检测缺失或失效的索引中断构建残留的INVALID索引、后端切换后类型漂移的索引均视为缺失并用CREATE INDEX CONCURRENTLY重建——因此不会阻塞正在进行的 retain / recall / consolidation。命令是幂等的可安全重复执行也可在 API 服务运行期间执行。hindsight-admin repair-bank (--bank BANK_ID | --all) [OPTIONS]参数选项说明默认--bank,-b要修复的银行 id与--all互斥—--all修复 base schema 与全部已发现租户 schema 中的每个银行—--schema,-s限定单个 schema全部 schema--dry-run只报告将要修复的内容不创建/删除任何索引关闭--bank与--all必须且只能传一个对使用单一全局向量索引的后端AlloyDB ScaNN、Oracle是无操作。实现上命令使用单条 autocommit 连接因为CREATE INDEX CONCURRENTLY不能在事务块内执行cli.py--all模式下还会顺手清理已删除银行遗留的孤儿索引。示例# 只查看哪些银行缺覆盖不做任何改动 hindsight-admin repair-bank --all --dry-run # 恢复/升级后执行一次修复所有 schema 的全部银行 hindsight-admin repair-bank --all # 修复单个银行 hindsight-admin repair-bank --bank acme-prod关于阈值的细节当HINDSIGHT_API_VECTOR_INDEX_MIN_ROWS保持默认 0 时银行一存在就应拥有全部三个索引本命令只补建缺失/失效项、不删除任何索引设置阈值后(bank, fact_type) 在行数达标时才获得索引低于阈值时查询由(bank_id, fact_type)B-tree 加 top-N 排序回答同样精确且更快此时本命令也会删除不再达标的索引。相关行为在 test_repair_bank_vector_indexes.py 中有大量测试覆盖例如「低于阈值不建索引」test_bank_below_the_threshold_gets_nothing、「dry-run 不改变任何东西」test_dry_run_changes_nothing、「重复执行幂等」test_rerun_is_idempotent等。四、backup事务一致的全库快照backup把 Hindsight 的全部数据打包为一个 zip 文件。文件内是每个表的 PostgreSQL 二进制 COPY 流table.bin加一个manifest.json记录版本、创建时间、schema、每张表的行数/字节数/列定义见 cli.py。hindsight-admin backup OUTPUT [OPTIONS]参数参数说明OUTPUT输出文件路径缺少.zip后缀时自动补上选项选项说明默认--schema,-s要备份的数据库 schemapublic示例hindsight-admin backup /backups/hindsight-2024-01-15.zip # 备份指定租户 schema hindsight-admin backup /backups/tenant-acme.zip --schema tenant_acme备份内容覆盖Memory banks 及其配置Documents 与 chunksEntities 及其关系Memory unitsfacts、experiences、observationsEntity cooccurrences 与 memory linksMental models 与 directivesWebhooks 与 file storage内部运维表async operations、audit log、graph-maintenance queue 等簿记表保证恢复后得到忠实完整的数据快照。BACKUP_TABLES清单按外键依赖顺序排列父表在前见 cli.py。清单必须覆盖 schema 中每一张持久表——否则恢复时TRUNCATE banks CASCADE会级联清掉未备份的mental_models等子表造成数据丢失。为此 test_admin_backup_restore.py 专门断言该清单与线上 schema 的表集合一致新增建表迁移若未同步更新清单会导致 CI 失败。租户扩展声明的 bank 级表会通过_effective_backup_tables()追加到核心清单之后cli.py。:::note 一致性保证 备份在REPEATABLE READ隔离级别的事务内完成cli.py所有表取自同一一致快照避免出现「entity_cooccurrences引用了entities备份之后才创建的行」之类的竞态。 :::五、restore全库恢复会清空目标 schemarestore从备份文件恢复数据。警告恢复前会删除目标 schema 中的全部现有数据。hindsight-admin restore INPUT [OPTIONS]参数参数说明INPUT输入备份文件.zip选项选项说明默认--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:::warning 数据丢失 恢复会先删除目标 schema 中的全部现有数据再导入备份。执行恢复前务必确认手头有最新的备份。 :::从源码看恢复流程cli.py分四步全部在单个事务内完成要么全部成功、要么全部回滚杜绝半恢复状态破坏性操作前先校验_validate_restore_schema把 manifest 中每张表的列清单与目标 schema 逐列比对——目标已删除的列不算错误否则历史备份会永久无法恢复而是从 COPY 流中剥掉对应字段并提示操作员类型不一致则直接报错拒绝恢复cli.py。字段剥离由_strip_binary_copy_fields在字节层完成cli.py因为二进制 COPY 是按位置匹配列的不重写流会导致错位写入。反向 TRUNCATE按BACKUP_TABLES逆序TRUNCATE ... CASCADE满足外键约束正向 COPY 导入按清单顺序回放各表二进制流收尾REFRESH MATERIALIZED VIEW memory_units_bm25并调用_sync_owned_sequences把非循环 identity 序列推进到恢复数据之上cli.py保证后续插入不会主键冲突。相关测试包括全量往返一致性test_backup_restore_roundtrip、列类型精确保留UUID/text/jsonb/timestamp 逐一比对见 test_backup_restore_preserves_all_column_types、目标已删除列的忽略test_restore_ignores_backup_columns_the_target_dropped以及截断前的类型不兼容拒绝test_restore_rejects_incompatible_column_type_before_truncating。六、decommission-worker / decommission-workers释放 Worker 任务Hindsight 的异步操作retain、consolidation 等由后台 worker 认领执行状态记录在async_operations表。当 worker 崩溃或未优雅退出时其「processing」任务会永久滞留需要管理命令把状态重置回「pending」让其他 worker 接管。decommission-worker释放指定 worker 拥有的全部任务将其从processing重置为pending。hindsight-admin decommission-worker WORKER_ID [OPTIONS]参数参数说明WORKER_ID要下线的 worker 的 ID选项选项说明默认--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 无响应时。:::tip 如何找到 Worker ID Worker ID 默认取主机名。Kubernetes StatefulSet 中即 Pod 名如hindsight-worker-0。也可通过HINDSIGHT_API_WORKER_ID环境变量或--worker-id参数自定义参见 worker/main.py 与socket.gethostname()兜底逻辑 L233-L234。 :::decommission-workers释放所有 worker当前处理中的任务统一重置为pending。当有一个或多个 worker 崩溃/被移除且未优雅关闭、你又不知道具体 worker ID 时使用。hindsight-admin decommission-workers [OPTIONS]选项选项说明默认--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 清理过重时快速清空整个队列。:::warning 有干扰性 该命令会释放每一个处理中的任务包括健康 worker 持有的任务。知道需要清理哪些 worker 时请优先使用decommission-worker WORKER_ID。 :::两条命令的底层都是一条 UPDATE把statusprocessing的行置为pending、清空worker_id/claimed_at、刷新updated_at见 cli.py 与 L1044-L1063。七、worker-status定位卡死与僵尸任务worker-status按 worker 分组展示所有处理中的任务包括操作类型、所属银行、任务已运行时长、最后更新时间——是 decommission 之前识别孤儿任务的首选工具。hindsight-admin worker-status [OPTIONS]选项选项说明默认--schema,-s数据库 schemapublic示例# 查看所有 worker 的处理中任务 hindsight-admin worker-status # 查看指定租户 schema 的处理中任务 hindsight-admin worker-status --schema tenant_acme适用场景decommission 之前检查哪些 worker 有陈旧任务、卡了多久吞吐问题诊断队列迟迟不排空是不是任务卡在 processingWorker 健康检查last_update_ago持续增长说明该 worker 已死或无响应。查询逻辑在 cli.py对async_operations按worker_id, claimed_at排序计算now() - claimed_at AS running_for与now() - updated_at AS last_update_ago随后按 worker 分组格式化输出L1137-L1177。八、export-bank / import-bank跨实例迁移银行这两个命令构成跨实例迁移的「源头」与「目标」两半用于把单个银行迁移到配置了不同 embedding 模型 / 向量扩展 / 全文检索后端的全新实例。export-bank把整个银行导出为可移植的 ZIP 归档——documents、facts、observations、银行配置、mental models、directives、webhooks。embedding 永不包含导入时重新生成。仅限 PostgreSQL。hindsight-admin export-bank --bank BANK_ID --output FILE.zip [OPTIONS]选项选项说明默认--bank,-b要导出的银行 id必填--output,-o写入.zip归档的路径必填--schema,-s银行所在的 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导出是只读的可安全地针对运行中的实例执行。实现上它会设置_current_schemacontextvar 让原始连接指向正确 schema再从配置解析 memories 存储并调用engine.transfer.export_bankcli.py——这样做可以避免「记忆存于 SQL 之外导致导出为空」的坑。import-bank把export-bank产生的整库归档恢复到本实例。facts 会用本实例配置的 embedding 模型重新嵌入链接与索引重建银行配置、mental models、directives、webhooks 原样恢复。不会运行 LLM fact 提取因为是迁移恢复状态也不会触发 webhooks 或重跑 consolidation。仅限 PostgreSQL。hindsight-admin import-bank --archive FILE.zip [OPTIONS]选项选项说明默认--archive,-aexport-bank产生的.zip路径必填--schema,-s目标 schemabase schema--target-bank覆盖银行 id默认沿用归档的源银行 id源银行--include-history归档中含历史时也一并恢复false示例hindsight-admin import-bank --archive my-bank.zip请对配置了目标 embedding 模型 / 向量扩展 / 全文检索后端的实例执行——重新嵌入使用的正是这些配置。实现上它会启动一个完整的MemoryEnginerun_migrationsTrue先按本实例的维度/后端完成 schema 初始化再调用import_bank_asynccli.py并在结束时汇总打印导入的 doc/fact/observation/mental model/知识页/directive/webhook/历史行数量L972-L981。:::warning 目标银行必须不存在 导入恢复的是整个银行配置、facts、mental models……不是合并。若目标 id 的银行已存在命令会失败。请先删除该银行或用--target-bank换一个新 id 恢复。 :::Blue-Green 迁移 runbook更换银行的embedding 模型如 384 维编码器 → 1024 维、向量扩展pgvector / vchord / pgvectorscale或全文检索后端无法在已填充数据的银行上原地完成——存量向量与索引与这些设置绑定。由于每个 embedding 与索引都是磁盘上文本的确定性函数受支持的做法是把银行搬到配置了新设置的全新实例在那里重新推导一切且无需 LLM 重新提取。export-bank/import-bank携带文档、facts、observations、银行配置、mental models、directives 与 webhooks但永不携带 embeddings——由目标实例用自己的模型重新生成。操作步骤在新数据库上搭建全新实例配置新的 embedding 模型 / 向量扩展 / 全文检索后端暂停源银行的写入维护窗口并先执行hindsight-admin backup兜底从源导出、向目标导入# 在源实例上 hindsight-admin export-bank --bank my-bank --output my-bank.zip # 在目标实例上已配置新设置 hindsight-admin import-bank --archive my-bank.zip在目标实例上验证跑有代表性的 recall 查询并与原结果对比把流量切到新实例。旧实例保留作为即时回滚点直到你确信无误。:::note 为什么必须换新实例而非原地迁移 embedding 模型是服务级的且银行memory_units.embedding列在 schema 内共享单一维度因此不同维度/不同后端的银行需要自己的实例/数据库。旧向量永不被动用回滚也因此变得极其简单。 :::九、恢复卡死的僵尸操作「僵尸操作」指因认领它的 worker 消失而永远卡在processing的操作。最常见的成因是HINDSIGHT_API_WORKER_ID不稳定当它默认取容器主机名时Docker 重启会生成新容器 ID新 worker 不认为旧 worker 的认领是自己的于是任务被搁浅。如何发现# 按 worker 列出处理中任务 —— last_update_ago 持续增长的 worker 已死 hindsight-admin worker-status # 银行级计数器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或设置环境变量。可进一步参考 Installation - Docker 与 Configuration - Distributed Workers。十、环境变量Admin CLI 与 API 服务使用同一套环境变量。最关键的一个变量说明默认HINDSIGHT_API_DATABASE_URLPostgreSQL 连接串pg0嵌入式示例# 使用指定数据库 export HINDSIGHT_API_DATABASE_URLpostgresql://user:passlocalhost:5432/hindsight hindsight-admin backup /backups/mybackup.zip其余常用相关变量定义见 config.pyHINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPL847默认true、HINDSIGHT_API_WORKER_IDL873默认取主机名、HINDSIGHT_API_VECTOR_EXTENSIONL626可选pgvector/vchord/pgvectorscale/scann默认pgvector与HINDSIGHT_API_TEXT_SEARCH_EXTENSIONL629可选native/vchord/pg_textsearch/pgroonga/pg_search默认native。小结hindsight-admin把 Hindsight 的数据库运维收敛为一组幂等、可脚本化的命令run-db-migration让迁移脱离 API 启动流程独立执行backup/restore借助 PostgreSQL 二进制 COPY 与单事务语义提供一致快照与原子恢复repair-bank修复银行级向量索引覆盖decommission-worker(s)与worker-status组合治理僵尸任务export-bank/import-bank则打通了跨实例的蓝绿迁移路径。所有命令直连 PostgreSQL、复用 API 配置适合直接嵌入 Kubernetes Job、CI/CD 流水线或运维剧本中。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight Admin CLI 运维实战：数据库迁移、备份恢复与 Worker 治理
Hindsight Admin CLI 运维实战数据库迁移、备份恢复与 Worker 治理【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsighthindsight-admin是 Hindsight 部署自带的命令行管理工具覆盖数据库迁移、全库备份/恢复、按银行bank粒度导出导入、以及后台 Worker 任务治理等日常运维操作。本指南以 Admin CLI 官方文档 为主线结合仓库内 CLI 实现 与测试用例逐条讲解命令的用途、参数、适用场景与底层原理读完后你可以独立完成生产环境的迁移升级、灾难恢复与僵尸任务排查。一、认识 Admin CLI直连数据库的运维通道hindsight-admin是一组 PostgreSQL 专属的管理命令与 HTTP API 不同它不经过 API 服务而是通过asyncpg直接连接 PostgreSQL二进制COPY、TRUNCATE CASCADE、REFRESH MATERIALIZED VIEW等底层操作天然依赖 PG 特性因此不支持 Oracle 后端。这一点在源码模块 docstring 中有明确说明见 cli.py。它读取与 API 服务完全相同的配置——环境变量以及当前工作目录下的.env文件——所以它操作的就是HINDSIGHT_API_DATABASE_URL指向的那个数据库默认值pg0即 Hindsight 内置的嵌入式开发数据库必须在持有 pg0 数据的主机上运行生产环境设置HINDSIGHT_API_DATABASE_URLpostgresql://user:passhost:5432/hindsight。连接逻辑见 cli.py_admin_connect会先解析pg0://URL必要时启动嵌入式 PG再注册json/jsonb类型编解码器保证导出行数据能正确解码为 Python 对象。安装与入口Admin CLI 随hindsight-api包一起分发安装后hindsight-admin可执行文件即进入PATHpip install hindsight-api # 或 uv add hindsight-api其入口在 pyproject.toml 中注册hindsight-admin hindsight_api.admin.cli:main而main()首先调用load_dotenv_for_entrypoint()加载.env再启动 typer 应用见 cli.py。在裸机、Docker 与 Kubernetes 中运行由于命令直连数据库务必在与 API 部署相同的主机/容器上运行以继承正确配置并保证网络可达# 裸机 / virtualenv复用 API 的环境变量或在工作目录放 .env hindsight-admin worker-status # Docker —— exec 进 API 容器 docker exec -it hindsight-api hindsight-admin backup /data/backup.zip # Kubernetes —— exec 进 API Pod kubectl exec deploy/hindsight-api -- hindsight-admin run-db-migration命令默认操作配置的 base schema多租户部署下可用--schema指定某个租户 schema详见下文环境变量一节。二、run-db-migration把迁移从启动流程中拆出来run-db-migration将数据库迁移到最新版本。默认迁移 base schema加上租户扩展发现的所有租户 schema传--schema则只迁移指定 schema。适合在 CI/CD 流水线中、或部署新版本前作为独立步骤执行。hindsight-admin run-db-migration [OPTIONS]参数选项说明默认--schema,-s要迁移的数据库 schema省略则迁移 base schema 及全部已发现的租户 schema全部 schema--embedding-dimension迁移后要强制的预期 embedding 维度省略则跳过迁移后的维度同步跳过--skip-extension-reconcile跳过迁移后的向量 / 全文检索索引 reconcile仅在HINDSIGHT_API_VECTOR_EXTENSION/HINDSIGHT_API_TEXT_SEARCH_EXTENSION与 schema 现有索引不一致时才需要做事。后端未变更时可显著加速跨大量租户 schema 的无变更重迁移正常执行 reconcile示例# 迁移 base schema 全部已发现租户 schema hindsight-admin run-db-migration # 迁移指定租户 schema hindsight-admin run-db-migration --schema tenant_acme从源码看cli.py_run_migration先通过租户扩展的list_tenants()收集 schema 列表并去重保序再以migration_concurrency为并发度每个 schema 一个进程、schema 内部串行调用run_migrations_for_schemas核心迁移完成后还会对每个 schema 执行租户扩展声明的 bank 级扩展表的 provisioner_provision_extra_bank_tables让扩展 schema 与核心 schema 遵循同一生命周期演进cli.py。:::tip 关闭启动时自动迁移 若希望把迁移作为部署流水线中的独立步骤可设置HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPfalse默认开启见 config.py 与DEFAULT_RUN_MIGRATIONS_ON_STARTUP避免 API 启动时重复执行迁移。 :::三、repair-bank修复银行级向量索引覆盖Hindsight 会为每个(bank, fact_type)组合创建部分向量索引。这些索引通常在银行创建时即刻生成空库上瞬间完成之后由 PostgreSQL 增量维护。但以下几种场景会让银行在创建路径之外被填充从而永远得不到这些索引逻辑恢复logical restore跨版本升级向量扩展切换vector-extension switch。缺失索引时银行的 recall 会静默回退到「全局索引 后过滤」既更慢又可能少返回结果近似最近邻搜索先从所有银行里取候选再过滤到你的银行。repair-bank用于校验并修复这种覆盖。它会检测缺失或失效的索引中断构建残留的INVALID索引、后端切换后类型漂移的索引均视为缺失并用CREATE INDEX CONCURRENTLY重建——因此不会阻塞正在进行的 retain / recall / consolidation。命令是幂等的可安全重复执行也可在 API 服务运行期间执行。hindsight-admin repair-bank (--bank BANK_ID | --all) [OPTIONS]参数选项说明默认--bank,-b要修复的银行 id与--all互斥—--all修复 base schema 与全部已发现租户 schema 中的每个银行—--schema,-s限定单个 schema全部 schema--dry-run只报告将要修复的内容不创建/删除任何索引关闭--bank与--all必须且只能传一个对使用单一全局向量索引的后端AlloyDB ScaNN、Oracle是无操作。实现上命令使用单条 autocommit 连接因为CREATE INDEX CONCURRENTLY不能在事务块内执行cli.py--all模式下还会顺手清理已删除银行遗留的孤儿索引。示例# 只查看哪些银行缺覆盖不做任何改动 hindsight-admin repair-bank --all --dry-run # 恢复/升级后执行一次修复所有 schema 的全部银行 hindsight-admin repair-bank --all # 修复单个银行 hindsight-admin repair-bank --bank acme-prod关于阈值的细节当HINDSIGHT_API_VECTOR_INDEX_MIN_ROWS保持默认 0 时银行一存在就应拥有全部三个索引本命令只补建缺失/失效项、不删除任何索引设置阈值后(bank, fact_type) 在行数达标时才获得索引低于阈值时查询由(bank_id, fact_type)B-tree 加 top-N 排序回答同样精确且更快此时本命令也会删除不再达标的索引。相关行为在 test_repair_bank_vector_indexes.py 中有大量测试覆盖例如「低于阈值不建索引」test_bank_below_the_threshold_gets_nothing、「dry-run 不改变任何东西」test_dry_run_changes_nothing、「重复执行幂等」test_rerun_is_idempotent等。四、backup事务一致的全库快照backup把 Hindsight 的全部数据打包为一个 zip 文件。文件内是每个表的 PostgreSQL 二进制 COPY 流table.bin加一个manifest.json记录版本、创建时间、schema、每张表的行数/字节数/列定义见 cli.py。hindsight-admin backup OUTPUT [OPTIONS]参数参数说明OUTPUT输出文件路径缺少.zip后缀时自动补上选项选项说明默认--schema,-s要备份的数据库 schemapublic示例hindsight-admin backup /backups/hindsight-2024-01-15.zip # 备份指定租户 schema hindsight-admin backup /backups/tenant-acme.zip --schema tenant_acme备份内容覆盖Memory banks 及其配置Documents 与 chunksEntities 及其关系Memory unitsfacts、experiences、observationsEntity cooccurrences 与 memory linksMental models 与 directivesWebhooks 与 file storage内部运维表async operations、audit log、graph-maintenance queue 等簿记表保证恢复后得到忠实完整的数据快照。BACKUP_TABLES清单按外键依赖顺序排列父表在前见 cli.py。清单必须覆盖 schema 中每一张持久表——否则恢复时TRUNCATE banks CASCADE会级联清掉未备份的mental_models等子表造成数据丢失。为此 test_admin_backup_restore.py 专门断言该清单与线上 schema 的表集合一致新增建表迁移若未同步更新清单会导致 CI 失败。租户扩展声明的 bank 级表会通过_effective_backup_tables()追加到核心清单之后cli.py。:::note 一致性保证 备份在REPEATABLE READ隔离级别的事务内完成cli.py所有表取自同一一致快照避免出现「entity_cooccurrences引用了entities备份之后才创建的行」之类的竞态。 :::五、restore全库恢复会清空目标 schemarestore从备份文件恢复数据。警告恢复前会删除目标 schema 中的全部现有数据。hindsight-admin restore INPUT [OPTIONS]参数参数说明INPUT输入备份文件.zip选项选项说明默认--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:::warning 数据丢失 恢复会先删除目标 schema 中的全部现有数据再导入备份。执行恢复前务必确认手头有最新的备份。 :::从源码看恢复流程cli.py分四步全部在单个事务内完成要么全部成功、要么全部回滚杜绝半恢复状态破坏性操作前先校验_validate_restore_schema把 manifest 中每张表的列清单与目标 schema 逐列比对——目标已删除的列不算错误否则历史备份会永久无法恢复而是从 COPY 流中剥掉对应字段并提示操作员类型不一致则直接报错拒绝恢复cli.py。字段剥离由_strip_binary_copy_fields在字节层完成cli.py因为二进制 COPY 是按位置匹配列的不重写流会导致错位写入。反向 TRUNCATE按BACKUP_TABLES逆序TRUNCATE ... CASCADE满足外键约束正向 COPY 导入按清单顺序回放各表二进制流收尾REFRESH MATERIALIZED VIEW memory_units_bm25并调用_sync_owned_sequences把非循环 identity 序列推进到恢复数据之上cli.py保证后续插入不会主键冲突。相关测试包括全量往返一致性test_backup_restore_roundtrip、列类型精确保留UUID/text/jsonb/timestamp 逐一比对见 test_backup_restore_preserves_all_column_types、目标已删除列的忽略test_restore_ignores_backup_columns_the_target_dropped以及截断前的类型不兼容拒绝test_restore_rejects_incompatible_column_type_before_truncating。六、decommission-worker / decommission-workers释放 Worker 任务Hindsight 的异步操作retain、consolidation 等由后台 worker 认领执行状态记录在async_operations表。当 worker 崩溃或未优雅退出时其「processing」任务会永久滞留需要管理命令把状态重置回「pending」让其他 worker 接管。decommission-worker释放指定 worker 拥有的全部任务将其从processing重置为pending。hindsight-admin decommission-worker WORKER_ID [OPTIONS]参数参数说明WORKER_ID要下线的 worker 的 ID选项选项说明默认--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 无响应时。:::tip 如何找到 Worker ID Worker ID 默认取主机名。Kubernetes StatefulSet 中即 Pod 名如hindsight-worker-0。也可通过HINDSIGHT_API_WORKER_ID环境变量或--worker-id参数自定义参见 worker/main.py 与socket.gethostname()兜底逻辑 L233-L234。 :::decommission-workers释放所有 worker当前处理中的任务统一重置为pending。当有一个或多个 worker 崩溃/被移除且未优雅关闭、你又不知道具体 worker ID 时使用。hindsight-admin decommission-workers [OPTIONS]选项选项说明默认--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 清理过重时快速清空整个队列。:::warning 有干扰性 该命令会释放每一个处理中的任务包括健康 worker 持有的任务。知道需要清理哪些 worker 时请优先使用decommission-worker WORKER_ID。 :::两条命令的底层都是一条 UPDATE把statusprocessing的行置为pending、清空worker_id/claimed_at、刷新updated_at见 cli.py 与 L1044-L1063。七、worker-status定位卡死与僵尸任务worker-status按 worker 分组展示所有处理中的任务包括操作类型、所属银行、任务已运行时长、最后更新时间——是 decommission 之前识别孤儿任务的首选工具。hindsight-admin worker-status [OPTIONS]选项选项说明默认--schema,-s数据库 schemapublic示例# 查看所有 worker 的处理中任务 hindsight-admin worker-status # 查看指定租户 schema 的处理中任务 hindsight-admin worker-status --schema tenant_acme适用场景decommission 之前检查哪些 worker 有陈旧任务、卡了多久吞吐问题诊断队列迟迟不排空是不是任务卡在 processingWorker 健康检查last_update_ago持续增长说明该 worker 已死或无响应。查询逻辑在 cli.py对async_operations按worker_id, claimed_at排序计算now() - claimed_at AS running_for与now() - updated_at AS last_update_ago随后按 worker 分组格式化输出L1137-L1177。八、export-bank / import-bank跨实例迁移银行这两个命令构成跨实例迁移的「源头」与「目标」两半用于把单个银行迁移到配置了不同 embedding 模型 / 向量扩展 / 全文检索后端的全新实例。export-bank把整个银行导出为可移植的 ZIP 归档——documents、facts、observations、银行配置、mental models、directives、webhooks。embedding 永不包含导入时重新生成。仅限 PostgreSQL。hindsight-admin export-bank --bank BANK_ID --output FILE.zip [OPTIONS]选项选项说明默认--bank,-b要导出的银行 id必填--output,-o写入.zip归档的路径必填--schema,-s银行所在的 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导出是只读的可安全地针对运行中的实例执行。实现上它会设置_current_schemacontextvar 让原始连接指向正确 schema再从配置解析 memories 存储并调用engine.transfer.export_bankcli.py——这样做可以避免「记忆存于 SQL 之外导致导出为空」的坑。import-bank把export-bank产生的整库归档恢复到本实例。facts 会用本实例配置的 embedding 模型重新嵌入链接与索引重建银行配置、mental models、directives、webhooks 原样恢复。不会运行 LLM fact 提取因为是迁移恢复状态也不会触发 webhooks 或重跑 consolidation。仅限 PostgreSQL。hindsight-admin import-bank --archive FILE.zip [OPTIONS]选项选项说明默认--archive,-aexport-bank产生的.zip路径必填--schema,-s目标 schemabase schema--target-bank覆盖银行 id默认沿用归档的源银行 id源银行--include-history归档中含历史时也一并恢复false示例hindsight-admin import-bank --archive my-bank.zip请对配置了目标 embedding 模型 / 向量扩展 / 全文检索后端的实例执行——重新嵌入使用的正是这些配置。实现上它会启动一个完整的MemoryEnginerun_migrationsTrue先按本实例的维度/后端完成 schema 初始化再调用import_bank_asynccli.py并在结束时汇总打印导入的 doc/fact/observation/mental model/知识页/directive/webhook/历史行数量L972-L981。:::warning 目标银行必须不存在 导入恢复的是整个银行配置、facts、mental models……不是合并。若目标 id 的银行已存在命令会失败。请先删除该银行或用--target-bank换一个新 id 恢复。 :::Blue-Green 迁移 runbook更换银行的embedding 模型如 384 维编码器 → 1024 维、向量扩展pgvector / vchord / pgvectorscale或全文检索后端无法在已填充数据的银行上原地完成——存量向量与索引与这些设置绑定。由于每个 embedding 与索引都是磁盘上文本的确定性函数受支持的做法是把银行搬到配置了新设置的全新实例在那里重新推导一切且无需 LLM 重新提取。export-bank/import-bank携带文档、facts、observations、银行配置、mental models、directives 与 webhooks但永不携带 embeddings——由目标实例用自己的模型重新生成。操作步骤在新数据库上搭建全新实例配置新的 embedding 模型 / 向量扩展 / 全文检索后端暂停源银行的写入维护窗口并先执行hindsight-admin backup兜底从源导出、向目标导入# 在源实例上 hindsight-admin export-bank --bank my-bank --output my-bank.zip # 在目标实例上已配置新设置 hindsight-admin import-bank --archive my-bank.zip在目标实例上验证跑有代表性的 recall 查询并与原结果对比把流量切到新实例。旧实例保留作为即时回滚点直到你确信无误。:::note 为什么必须换新实例而非原地迁移 embedding 模型是服务级的且银行memory_units.embedding列在 schema 内共享单一维度因此不同维度/不同后端的银行需要自己的实例/数据库。旧向量永不被动用回滚也因此变得极其简单。 :::九、恢复卡死的僵尸操作「僵尸操作」指因认领它的 worker 消失而永远卡在processing的操作。最常见的成因是HINDSIGHT_API_WORKER_ID不稳定当它默认取容器主机名时Docker 重启会生成新容器 ID新 worker 不认为旧 worker 的认领是自己的于是任务被搁浅。如何发现# 按 worker 列出处理中任务 —— last_update_ago 持续增长的 worker 已死 hindsight-admin worker-status # 银行级计数器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或设置环境变量。可进一步参考 Installation - Docker 与 Configuration - Distributed Workers。十、环境变量Admin CLI 与 API 服务使用同一套环境变量。最关键的一个变量说明默认HINDSIGHT_API_DATABASE_URLPostgreSQL 连接串pg0嵌入式示例# 使用指定数据库 export HINDSIGHT_API_DATABASE_URLpostgresql://user:passlocalhost:5432/hindsight hindsight-admin backup /backups/mybackup.zip其余常用相关变量定义见 config.pyHINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUPL847默认true、HINDSIGHT_API_WORKER_IDL873默认取主机名、HINDSIGHT_API_VECTOR_EXTENSIONL626可选pgvector/vchord/pgvectorscale/scann默认pgvector与HINDSIGHT_API_TEXT_SEARCH_EXTENSIONL629可选native/vchord/pg_textsearch/pgroonga/pg_search默认native。小结hindsight-admin把 Hindsight 的数据库运维收敛为一组幂等、可脚本化的命令run-db-migration让迁移脱离 API 启动流程独立执行backup/restore借助 PostgreSQL 二进制 COPY 与单事务语义提供一致快照与原子恢复repair-bank修复银行级向量索引覆盖decommission-worker(s)与worker-status组合治理僵尸任务export-bank/import-bank则打通了跨实例的蓝绿迁移路径。所有命令直连 PostgreSQL、复用 API 配置适合直接嵌入 Kubernetes Job、CI/CD 流水线或运维剧本中。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考