Hindsight 0.6.2 到 0.7.2 生产升级复盘

HTML: https://decision.ht1072.top/2026-06-02-hindsight-062-to-072-production-cutover.html
Local HTML: [已移除本地路径]
Generated: 2026-06-02T23:13:21+08:00

Hindsight 0.6.2 → 0.7.2 生产升级复盘

页面摘要区

核心结论：Hindsight 生产 API 已从 0.6.2 成功切到 0.7.2，当前 http://127.0.0.1:8889 运行健康，PostgreSQL migration 已升级到 Alembic head c1d2e3f4a5b6，retain / recall / consolidate 全链路验收通过。

推荐路径：本次采用“production-like rehearsal 先验 → 生产备份 → 独立 production venv → systemd drop-in 切换 ExecStart → 重启观察 migration → 数据面 smoke test”的受控升级路径，后续 Hindsight 小版本升级应继续沿用这条链路。

关键依据：上游 issue #1902 已由 PR #1904 修复并发布到 v0.7.2；本机 fresh rehearsal 证明官方 0.7.2 能从 live 0.6.2 PostgreSQL dump 原样迁移；生产切换后 /health healthy、/version 返回 0.7.2、日志无 ActiveSqlTransaction / ModuleNotFoundError / traceback。

落地方式：没有污染 Hermes 主 venv，而是将 hindsight-api.service 通过 drop-in 指向独立 venv [已移除本地路径]；回退时优先删除 drop-in 回到旧服务入口，DB 回退只走 pre-cutover dump 的 restore-to-new-db + swap。

风险边界：本次升级已经完成并通过验收，但 schema 已前进到 c1d2e3f4a5b6，若未来回退，不应直接破坏性覆盖 live DB；必须先恢复到新库验证，再做受控切换。

1. 背景

本机 Hindsight 是 Hermes 长期记忆层的主路径，生产 HTTP API 入口为：

http://127.0.0.1:8889

升级前生产版本为 0.6.2，数据库为本地 pg0 / PostgreSQL 18.1：

DB: pg0://hindsight-hermes
PostgreSQL port: 5432
database: hindsight

升级动因来自 0.7.x 的数据模型调整，尤其是降低旧 memory_links.link_type='entity' 相关膨胀风险。但 0.7.1 在本机生产同构 rehearsal 中暴露了两个硬阻塞：

fresh install 下 SQLAlchemy 2.1 会默认选择 psycopg v3，而官方包只带 psycopg2-binary，导致缺 psycopg。
多个 Alembic migration 在 transaction block 内执行 DROP/CREATE INDEX CONCURRENTLY，PostgreSQL 拒绝执行。

这些问题已提交给上游：

https://github.com/vectorize-io/hindsight/issues/1902

上游通过 PR #1904 修复，并发布 v0.7.2。

2. 上游修复确认

上游 PR：

https://github.com/vectorize-io/hindsight/pull/1904

修复点：

将 SQLAlchemy 约束到 <2.1，避免 fresh install 误走 psycopg v3 默认驱动。
将涉及 CONCURRENTLY 的 migration 改为 Alembic 官方 autocommit_block()。
增加 migration shape guard，避免手写 op.execute("COMMIT") 和 transaction-block CONCURRENTLY 问题回归。

本机对官方 0.7.2 migration 文件的形状检查结果：

manual COMMIT count: 0
autocommit_block count: 22

3. 升级策略

本次没有直接原地修改 Hermes 主 venv，而采用独立 production venv：

旧 ExecStart: [已移除本地路径] --host 127.0.0.1 --port 8889 --no-access-log
新 ExecStart: [已移除本地路径] --host 127.0.0.1 --port 8889 --no-access-log
Drop-in: [已移除本地路径]

这么做的好处：

Hermes 主 venv 不被 Hindsight 依赖升级污染。
回退服务入口只需移除 systemd drop-in。
生产服务、依赖、证据目录边界清晰。

4. Rehearsal 验证

生产切换前先做了 fresh rehearsal：

Audit dir: [已移除本地路径]
Rehearsal DB: hindsight_072_rehearsal_20260602_221017
Isolated API: http://127.0.0.1:18892

rehearsal 使用从 live 0.6.2 dump restore 出来的 PostgreSQL 数据库，升级前 Alembic 为：

86f7a033d372

升级后 Alembic 为：

c1d2e3f4a5b6

rehearsal 验证项：

/health healthy
/version 返回 0.7.2
banks 可读出 hermes bank
stats 正常
retain 成功
recall 能召回 smoke memory
consolidate 成功返回 operation id
最终 pending_operations=0、failed_operations=0、pending_consolidation=0、failed_consolidation=0

5. 生产切换步骤

5.1 生产切换前备份

生产 cutover 证据目录：

[已移除本地路径]

关键备份文件：

hindsight-live-before-072.dump
hindsight-live-before-072.dump.sha256
hindsight-api.service.before.txt
hindsight-api.status.before.txt
embed.before
hermes-main-venv-freeze.before.txt
live-health.before.json
live-version.before.json
live-stats.before.json
live-alembic.before.txt

DB dump 大小：

16M

5.2 production venv 版本

最终生产 venv：

[已移除本地路径]

包版本：

hindsight-api-slim 0.7.2
hindsight-embed    0.7.2
sqlalchemy         2.0.50
psycopg2-binary    2.9.12
psycopg            3.3.4
alembic            1.18.4

5.3 systemd drop-in

drop-in 内容：

[Service]
ExecStart=
ExecStart=[已移除本地路径] --host 127.0.0.1 --port 8889 --no-access-log

随后执行：

systemctl --user daemon-reload
systemctl --user restart hindsight-api.service

6. 生产验证结果

6.1 服务状态

Service: hindsight-api.service
Status: active
MainPID: 2513043
ExecStart: [已移除本地路径] --host 127.0.0.1 --port 8889 --no-access-log

6.2 HTTP API

/health：

{"status":"healthy","database":"connected"}

/version：

{"api_version":"0.7.2","features":{"observations":true,"mcp":true,"worker":true,"bank_config_api":true,"file_upload_api":true}}

6.3 Migration

生产库 Alembic：

c1d2e3f4a5b6

日志关键线：

Database migrations completed successfully for schema 'public'
Memory system initialized
Application startup complete

DB 状态：

DB tables: 16
DB size: 115 MB

6.4 数据面 smoke test

retain 成功写入 production cutover smoke memory。

recall 成功召回：

Hindsight production API was cut over to v0.7.2 on June 2, 2026, using an isolated production venv and systemd drop-in

consolidate 返回 operation id：

33da2320-62dd-4a49-b518-62ee5f9e9584

最终 stats：

pending_operations      0
failed_operations       0
pending_consolidation   0
failed_consolidation    0

最终 bank 数据：

total_nodes         5574
total_links         145613
total_documents     311
total_observations  2782

6.5 日志错误扫描

切换后日志扫描关键词：

traceback
exception
error
failed
ActiveSqlTransaction
ModuleNotFoundError

结果：

0 matching lines

7. 当前生产拓扑

Hermes memory provider / Hindsight API
        ↓
http://127.0.0.1:8889
        ↓
hindsight-api.service
        ↓
[已移除本地路径]
        ↓
pg0 / PostgreSQL 18.1 / hindsight database

这已经是当前 canonical 运行态。后续排障或巡检时不要再默认认为生产 Hindsight 是 0.6.2。

8. 回退路径

回退优先级：先回退服务入口，再考虑数据库。

8.1 回退服务入口

systemctl --user stop hindsight-api.service
rm -f [已移除本地路径]
systemctl --user daemon-reload
systemctl --user start hindsight-api.service
curl -sS http://127.0.0.1:8889/health
curl -sS http://127.0.0.1:8889/version

8.2 回退数据库

如果必须回退 schema/data，使用 pre-cutover dump：

[已移除本地路径]

原则：优先 restore 到新库并做 swap，不直接破坏性覆盖 live DB，除非明确批准。

9. 风险与边界

风险 1：schema 已前进，不能把服务入口回退等同于完整回退

删除 drop-in 可以让服务入口回到旧 venv，但数据库 schema 已经升级到 c1d2e3f4a5b6。如果旧服务与新 schema 不兼容，仅回退 venv 不够，需要走 DB dump restore-to-new-db + swap。

风险 2：生产 venv 与 Hermes 主 venv 分离后，后续升级要明确目标

当前 Hindsight API 不再由 Hermes 主 venv 承载，而是独立 venv [已移除本地路径]。后续任何 Hindsight 依赖排障、升级、pip check 都应以这个 venv 为主，不要误查 Hermes 主 venv。

风险 3：pg0 仍由 Hindsight 启动链管理，不能只看 systemd active

切换后日志显示 Hindsight API 会启动 embedded PostgreSQL hindsight-hermes。健康判断应看 API /health、DB pool、Alembic 和 worker stats，不要只看 systemd active。

10. 后续建议

将 [已移除本地路径] 作为 Hindsight 生产 venv canonical 路径。
保留 cutover 目录至少到下一次稳定升级之后。
后续小版本升级沿用：upstream issue / release 检查 → fresh dump rehearsal → 生产备份 → drop-in / venv 切换 → API + 数据面验收。
巡检中加入版本口径：/version 必须返回 0.7.2 或后续明确升级版本，不能只看 /health。

11. 关联文件

生产 cutover：

[已移除本地路径]
[已移除本地路径]

rehearsal audit：

[已移除本地路径]

systemd drop-in：

[已移除本地路径]

production venv：

[已移除本地路径]

12. 结论

0.7.2 已经从“可升级候选”变成当前生产事实。后续 Hindsight 相关判断应以 0.7.2 + 独立 production venv + systemd drop-in + PostgreSQL Alembic c1d2e3f4a5b6 为基准。