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 /home/ht/hindsight-072-prod-venv；回退时优先删除 drop-in 回到旧服务入口，DB 回退只走 pre-cutover dump 的 restore-to-new-db + swap。
证据摘要
- 上游 issue
#1902已由 PR#1904修复并发布到v0.7.2；本机 fresh rehearsal 证明官方0.7.2能从 live0.6.2PostgreSQL dump 原样迁移；生产切换后/healthhealthy、/version返回0.7.2、日志无ActiveSqlTransaction/ModuleNotFoundError/ traceback。
行动清单
/home/ht/hindsight-072-prod-venv 作为 Hindsight 生产 venv canonical 路径。/version 必须返回 0.7.2 或后续明确升级版本，不能只看 /health。边界 / 风险
删除 drop-in 可以让服务入口回到旧 venv，但数据库 schema 已经升级到 c1d2e3f4a5b6。如果旧服务与新 schema 不兼容，仅回退 venv 不够，需要走 DB dump restore-to-new-db + swap。
当前 Hindsight API 不再由 Hermes 主 venv 承载，而是独立 venv /home/ht/hindsight-072-prod-venv。后续任何 Hindsight 依赖排障、升级、pip check 都应以这个 venv 为主，不要误查 Hermes 主 venv。
切换后日志显示 Hindsight API 会启动 embedded PostgreSQL hindsight-hermes。健康判断应看 API /health、DB pool、Alembic 和 worker stats，不要只看 systemd active。
完整记录
Hindsight 0.6.2 → 0.7.2 生产升级复盘
1. 背景
本机 Hindsight 是 Hermes 长期记忆层的主路径，生产 HTTP API 入口为：
升级前生产版本为 0.6.2，数据库为本地 pg0 / PostgreSQL 18.1：
升级动因来自 0.7.x 的数据模型调整，尤其是降低旧 memory_links.link_type='entity' 相关膨胀风险。但 0.7.1 在本机生产同构 rehearsal 中暴露了两个硬阻塞：
- fresh install 下 SQLAlchemy 2.1 会默认选择
psycopgv3，而官方包只带psycopg2-binary，导致缺psycopg。 - 多个 Alembic migration 在 transaction block 内执行
DROP/CREATE INDEX CONCURRENTLY，PostgreSQL 拒绝执行。
这些问题已提交给上游：
上游通过 PR #1904 修复，并发布 v0.7.2。
2. 上游修复确认
上游 PR：
修复点：
- 将 SQLAlchemy 约束到
<2.1，避免 fresh install 误走psycopgv3 默认驱动。 - 将涉及
CONCURRENTLY的 migration 改为 Alembic 官方autocommit_block()。 - 增加 migration shape guard，避免手写
op.execute("COMMIT")和 transaction-blockCONCURRENTLY问题回归。
本机对官方 0.7.2 migration 文件的形状检查结果：
3. 升级策略
本次没有直接原地修改 Hermes 主 venv，而采用独立 production venv：
这么做的好处：
- Hermes 主 venv 不被 Hindsight 依赖升级污染。
- 回退服务入口只需移除 systemd drop-in。
- 生产服务、依赖、证据目录边界清晰。
4. Rehearsal 验证
生产切换前先做了 fresh rehearsal：
rehearsal 使用从 live 0.6.2 dump restore 出来的 PostgreSQL 数据库，升级前 Alembic 为：
升级后 Alembic 为：
rehearsal 验证项：
/healthhealthy/version返回0.7.2banks可读出hermesbankstats正常retain成功recall能召回 smoke memoryconsolidate成功返回 operation id- 最终
pending_operations=0、failed_operations=0、pending_consolidation=0、failed_consolidation=0
5. 生产切换步骤
5.1 生产切换前备份
生产 cutover 证据目录：
关键备份文件：
DB dump 大小：
5.2 production venv 版本
最终生产 venv：
包版本：
5.3 systemd drop-in
drop-in 内容：
随后执行：
6. 生产验证结果
6.1 服务状态
6.2 HTTP API
/health：
/version：
6.3 Migration
生产库 Alembic：
日志关键线：
DB 状态：
6.4 数据面 smoke test
retain 成功写入 production cutover smoke memory。
recall 成功召回：
consolidate 返回 operation id：
最终 stats：
最终 bank 数据：
6.5 日志错误扫描
切换后日志扫描关键词：
结果：
7. 当前生产拓扑
这已经是当前 canonical 运行态。后续排障或巡检时不要再默认认为生产 Hindsight 是 0.6.2。
8. 回退路径
回退优先级：先回退服务入口，再考虑数据库。
8.1 回退服务入口
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 /home/ht/hindsight-072-prod-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. 后续建议
- 将
/home/ht/hindsight-072-prod-venv作为 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 为基准。