deploy.stack/hindsight/readme.md

Hindsight 部署栈

vectorize-io/hindsight 是一个面向 LLM Agent 的长期记忆后端，采用 PostgreSQL/pgvector 存储。Hermes Agent 用它做跨会话长期记忆。

本目录是 方案三：DB + Hindsight 分离部署 迁移到 deploy.stack 仓库的版本。

目录结构

文件	说明
stack.yml	Docker Compose 主文件（2 服务：db + hindsight）
env.cfg.example	公共环境变量模板（不含敏感信息，可提交）
env.cfg	敏感配置（gitignore，不提交） — 实际部署时从 example 复制后填密码/API Key
backup.job	每日 pg_dump 热备份脚本，保留 7 天
readme.md	本文档

架构

┌──────────────────────┐               ┌──────────────────────┐
│  hindsight-app 容器  │               │  hindsight-db 容器   │
│  (ghcr.nju.edu.cn/   │   :5432 内网  │  (pgvector/pgvector  │
│   vectorize-io/      │ ────────────► │   :pg18)             │
│   hindsight)         │               │                      │
│                      │   :8888 API   │  :5432 对外暴露      │
│                      │   :9999 Admin │  (供外部工具连接)    │
└──────────────────────┘               └──────────────────────┘
        │                                       │
        ▼ bind mount                            ▼ bind mount
   ${Volumes_Path}/backups               ${Volumes_Path}/pgdata
   (pg_dump 落盘目录)                    (PG 数据,原生 ext4)

端口

端口	服务	用途
5432	db	PostgreSQL 对外访问（DBeaver、pgAdmin 等工具连接）
8888	hindsight	API 服务
9999	hindsight	Admin UI

宿主机端口可通过 env.cfg 中的 HINDSIGHT_DB_PORT、HINDSIGHT_API_PORT、HINDSIGHT_ADMIN_PORT 自定义。

环境变量

公共变量（env.cfg.example）

变量	默认值	说明
HINDSIGHT_VERSION	latest	Hindsight App 镜像标签
HINDSIGHT_DB_VERSION	18	PostgreSQL 大版本号
HINDSIGHT_DB_IMAGE	pgvector/pgvector	DB 镜像仓库
HINDSIGHT_APP_IMAGE	ghcr.nju.edu.cn/vectorize-io/hindsight	App 镜像仓库（南大 ghcr 镜像）
HINDSIGHT_DB_USER	hindsight_user	PostgreSQL 用户名
HINDSIGHT_DB_NAME	hindsight_db	PostgreSQL 数据库名
POSTGRES_HOST_AUTH_METHOD	scram-sha-256	PG 认证方式，同步用于 INITDB_ARGS --auth-host
Volumes_Path	/data/Volumes/hindsight	宿主机持久化数据根路径
HINDSIGHT_DB_PORT	5432	PostgreSQL 宿主机端口
HINDSIGHT_API_PORT	8888	API 宿主机端口
HINDSIGHT_ADMIN_PORT	9999	Admin UI 宿主机端口
HINDSIGHT_CP_DATAPLANE_API_URL	http://0.0.0.0:8888	数据面 API 地址
HINDSIGHT_API_LLM_PROVIDER	—	LLM 提供商
HINDSIGHT_API_LLM_MODEL	—	LLM 模型名
HINDSIGHT_API_LLM_BASE_URL	—	LLM API Base URL
HINDSIGHT_API_LOG_LEVEL	info	日志级别

敏感变量（env.cfg，不提交）

变量	说明
HINDSIGHT_DB_PASSWORD	PostgreSQL 密码（最好不要带特殊字符，避免 URI 解码问题）
HINDSIGHT_API_LLM_API_KEY	LLM API Key

部署步骤

首次部署

# 1. 准备数据目录（必须原生 ext4，不能放 9P drvfs）
sudo mkdir -pv /data/Volumes/hindsight/{pgdata,backups}
sudo chown -R 999:999 /data/Volumes/hindsight/pgdata

# 2. 复制 env 模板并填入真实值
cp env.cfg.example env.cfg
$EDITOR env.cfg
# 必填：HINDSIGHT_DB_PASSWORD, HINDSIGHT_API_LLM_API_KEY

# 3. 拉镜像
docker compose --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml pull

# 4. 启动
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml up -d

验证

# 容器状态
docker ps -f name=hindsight

# DB 连接与建表
docker exec -it hindsight-db psql -U hindsight_user -d hindsight_db -c '\dt'

# 端口监听
ss -tlnp | grep -E '5432|8888|9999'

# API 健康检查
curl -s http://localhost:8888/health

停止/重启

# 停止（保留数据）
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml stop

# 完全销毁（**数据不删**，bind 挂载保留在宿主机）
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml down

# 重启
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml restart

关键设计决策

决策点	决定	原因
数据卷方案	bind 挂载到 ${Volumes_Path}/pgdata	直观、可直接 rsync/pg_dump、跨机迁移用 tar 整个目录即可
端口绑定	0.0.0.0，含 DB 5432	PVE LAN 上其他 VM 也可访问；DB 端口暴露方便外部工具（DBeaver 等）连接
镜像源	ghcr.nju.edu.cn/vectorize-io/hindsight	南京大学 ghcr 镜像，国内拉得快
LLM	MiniMax-M3 via api.minimaxi.com	用 MiniMax 的 OpenAI-compatible 协议
PG 认证	scram-sha-256	比 md5 更安全，POSTGRES_INITDB_ARGS 同步设置 --auth-host
旧数据迁移	见 docs-hermes-Hindsight-记忆系统部署指南.md 决策表	走 A（zip 导入） 或 B（重置新 DB） 路径

备份与恢复

自动备份

backup.job 是 pg_dump 热备份脚本（不停服），落盘到 bind 挂载的 backups/。接入 cron：

# /etc/cron.d/hindsight-backup 或 crontab -e
30 2 * * * /path/to/deploy.stack/hindsight/backup.job >> /var/log/hindsight-backup.log 2>&1

或参考 crontab/ 目录的统一任务管理方式（shell/up.bash 会处理 chmod +x）。

手动备份

# 热备份（推荐）
docker exec hindsight-db pg_dump -U hindsight_user -d hindsight_db | gzip > /data/Volumes/hindsight/backups/manual_$(date +%Y%m%d).sql.gz

# 冷备份（停服时，更彻底）
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml stop
sudo rsync -a /data/Volumes/hindsight/pgdata/ /data/Volumes/hindsight/backups/pgdata-cold/
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml start

恢复

# 从 pg_dump 恢复
gunzip -c /data/Volumes/hindsight/backups/hindsight_db_20260607_023000.sql.gz \
  | docker exec -i hindsight-db psql -U hindsight_user -d hindsight_db

# 从冷备份恢复（停服 + 替换 bind 目录）
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml down
sudo rm -rf /data/Volumes/hindsight/pgdata/*
sudo rsync -a /data/Volumes/hindsight/backups/pgdata-cold/ /data/Volumes/hindsight/pgdata/
sudo chown -R 999:999 /data/Volumes/hindsight/pgdata
docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml up -d

故障排查

症状	排查命令
容器起不来	docker logs -f hindsight-app / docker logs -f hindsight-db
DB 连不上（容器内）	docker exec -it hindsight-db psql -U hindsight_user -d hindsight_db
DB 连不上（外部工具）	确认 HINDSIGHT_DB_PORT 已映射、ss -tlnp 检查 5432 监听
慢查询	在 psql 里 SELECT * FROM pg_stat_activity;
端口冲突	ss -tlnp | grep -E '5432|8888|9999'
端口未对外	ss -tlnp 看是不是只监听 127.0.0.1，确认 ports: 没加 IP 前缀
密码含特殊字符导致连接失败	HINDSIGHT_DB_PASSWORD 最好不要带特殊字符，避免 URI 编码问题
glibc 错误	0.7.2 内嵌 pg0 需 glibc 2.38，方案三已用独立容器避开

与 Hermes 集成

Hermes plugin 通过 HTTP 调用本服务的 API（localhost:8888），不直连 DB。配置在 ~/.hermes/config.yaml：

memory:
  provider: hindsight
  hindsight:
    api_url: http://localhost:8888
    bank_id: hermes
    memory_mode: hybrid
    auto_recall: true
    auto_retain: true
    retain_async: true

切换命令：hermes config set memory.provider hindsight

相关文档

• ~/Obsibian/MyNotes/DevOps/04-AI工具/docs-hermes-Hindsight-记忆系统部署指南.md — 完整部署指南（700+ 行，含方案对比、旧数据迁移决策表）
• 仓库根 AGENTS.md — deploy.stack 项目规范
• crontab/ — 定时任务集成参考