chore: add env.cfg.example templates and clean up config files

2026-08-13 17:59:23 +08:00
parent c75c9884c8
commit c6eccd687b
88 changed files with 4264 additions and 88 deletions
@@ -0,0 +1,29 @@
+#!/bin/bash
+# ============================================================
+# Hindsight 备份任务（每日 02:30 跑，cron 部署参考 crontab/）
+#   - 热备份：docker exec pg_dump 落盘到 bind 挂载的 backups/
+#   - 保留 7 天的 .sql.gz
+# ============================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/env.cfg"
+
+BACKUP_DIR="${Volumes_Path}/backups"
+KEEP_DAYS=7
+TS=$(date +%Y%m%d_%H%M%S)
+FNAME="hindsight_db_${TS}.sql.gz"
+
+mkdir -p "${BACKUP_DIR}"
+
+docker exec hindsight-db pg_dump \
+    -U hindsight_user \
+    -d hindsight_db \
+    --no-owner --no-privileges \
+    | gzip > "${BACKUP_DIR}/${FNAME}"
+
+# 清理超过 KEEP_DAYS 天的旧备份
+find "${BACKUP_DIR}" -name "hindsight_db_*.sql.gz" -mtime +${KEEP_DAYS} -delete
+
+echo "[backup] ok: ${FNAME} ($(du -h "${BACKUP_DIR}/${FNAME}" | cut -f1))"
@@ -0,0 +1,43 @@
+# ============================================================
+# Hindsight 部署 — 公共环境变量（不含敏感信息）
+# 复制为 env.cfg 后填入真实值，env.cfg 已被 .gitignore 忽略
+# ============================================================
+
+# 镜像版本
+HINDSIGHT_VERSION=latest
+HINDSIGHT_DB_VERSION=18
+
+# 镜像源
+HINDSIGHT_DB_IMAGE=pgvector/pgvector
+HINDSIGHT_APP_IMAGE=ghcr.nju.edu.cn/vectorize-io/hindsight
+
+# 数据库账号/库名
+HINDSIGHT_DB_USER=hindsight_user
+HINDSIGHT_DB_NAME=hindsight_db
+POSTGRES_HOST_AUTH_METHOD=scram-sha-256
+
+# 宿主机数据卷路径（**必须 WSL/Linux ext4 原生 fs**，不能放 /mnt/9P）
+# bind 挂载 PostgreSQL 数据；放在 ~/hindsight/pgdata 而非 /mnt/d/mydata/，
+# 因为 9P drvfs 的 fsync 不可靠，会导致 PG 数据损坏。
+Volumes_Path=/data/Volumes/hindsight
+
+# 服务端口（宿主机:容器）
+HINDSIGHT_DB_PORT=5432
+HINDSIGHT_API_PORT=8888
+HINDSIGHT_ADMIN_PORT=9999
+HINDSIGHT_CP_DATAPLANE_API_URL=http://0.0.0.0:8888
+
+# LLM（MiniMax OpenAI-compatible 协议）
+HINDSIGHT_API_LLM_PROVIDER=minimax
+HINDSIGHT_API_LLM_MODEL=MiniMax-M3
+HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.com/v1
+
+# 日志
+HINDSIGHT_API_LOG_LEVEL=info
+
+# ============================================================
+# 敏感值（必填，env.cfg 不提交）— 在 .gitignore 已忽略
+# PostgreSQL 密码 最好不要带特殊字符
+# ============================================================
+# HINDSIGHT_DB_PASSWORD=<强密码>
+# HINDSIGHT_API_LLM_API_KEY=<你的 MiniMax key>
@@ -0,0 +1,210 @@
+# Hindsight 部署栈
+
+[vectorize-io/hindsight](https://github.com/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 |
+
+## 部署步骤
+
+### 首次部署
+
+```bash
+# 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
+```
+
+### 验证
+
+```bash
+# 容器状态
+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
+```
+
+### 停止/重启
+
+```bash
+# 停止（保留数据）
+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：
+
+```bash
+# /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`）。
+
+### 手动备份
+
+```bash
+# 热备份（推荐）
+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
+```
+
+### 恢复
+
+```bash
+# 从 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`：
+
+```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/` — 定时任务集成参考
@@ -0,0 +1,77 @@
+# Hindsight 部署栈
+# ============================================================
+# 部署前准备（仅首次）：
+#   mkdir -pv ${Volumes_Path}/{pgdata,backups,huggingface}
+#   sudo chown -R 999:999 ${Volumes_Path}/pgdata
+#   cp env.cfg.example env.cfg && $EDITOR env.cfg   # 填入密码/API Key
+#
+# pull:: docker compose --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml pull
+# RUN:: docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.yml up -d
+# disc::
+#   - DB 数据 bind 挂到 /home/geng/hindsight/pgdata（WSL 原生 fs,避 9P fsync 风险）
+#   - 复用宿主 HF 缓存（bge + ms-marco 不重下）
+#   - 镜像走南京大学 ghcr 镜像，国内拉得快
+#   - 端口 8888=API, 9999=Admin UI, 5432=PostgreSQL,绑定 0.0.0.0 供 LAN VM 访问
+# ============================================================
+
+services:
+  db:
+    image: ${HINDSIGHT_DB_IMAGE}:pg${HINDSIGHT_DB_VERSION:-18}
+    container_name: hindsight-db
+    restart: unless-stopped
+    environment:
+      - TZ=Asia/Shanghai
+      - POSTGRES_USER=${HINDSIGHT_DB_USER:-hindsight_user}
+      - POSTGRES_PASSWORD=${HINDSIGHT_DB_PASSWORD:?set HINDSIGHT_DB_PASSWORD}
+      - POSTGRES_DB=${HINDSIGHT_DB_NAME:-hindsight_db}
+      - POSTGRES_HOST_AUTH_METHOD=${POSTGRES_HOST_AUTH_METHOD}
+      - POSTGRES_INITDB_ARGS=--encoding=UTF8 --locale=C --auth-host=${POSTGRES_HOST_AUTH_METHOD}
+    volumes:
+      - /etc/timezone:/etc/timezone:ro
+      - /etc/localtime:/etc/localtime:ro
+      - ${Volumes_Path}/pgdata:/var/lib/postgresql/${HINDSIGHT_DB_VERSION:-18}/docker
+    ports:
+      - "${HINDSIGHT_DB_PORT:-5432}:5432"
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${HINDSIGHT_DB_USER:-hindsight_user} -d ${HINDSIGHT_DB_NAME:-hindsight_db}",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    networks:
+      - hindsight-net
+
+  hindsight:
+    image: ${HINDSIGHT_APP_IMAGE}:${HINDSIGHT_VERSION:-latest}
+    container_name: hindsight-app
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "${HINDSIGHT_API_PORT:-8888}:8888"
+      - "${HINDSIGHT_ADMIN_PORT:-9999}:9999"
+    environment:
+      - TZ=Asia/Shanghai
+      - HINDSIGHT_API_LLM_PROVIDER=${HINDSIGHT_API_LLM_PROVIDER}
+      - HINDSIGHT_API_LLM_API_KEY=${HINDSIGHT_API_LLM_API_KEY:?set HINDSIGHT_API_LLM_API_KEY}
+      - HINDSIGHT_API_LLM_MODEL=${HINDSIGHT_API_LLM_MODEL}
+      - HINDSIGHT_API_LLM_BASE_URL=${HINDSIGHT_API_LLM_BASE_URL}
+      - HINDSIGHT_API_DATABASE_URL=postgresql://${HINDSIGHT_DB_USER}:${HINDSIGHT_DB_PASSWORD}@db:5432/${HINDSIGHT_DB_NAME}
+      - HINDSIGHT_API_LOG_LEVEL=${HINDSIGHT_API_LOG_LEVEL:-info}
+      - HINDSIGHT_CP_DATAPLANE_API_URL=${HINDSIGHT_CP_DATAPLANE_API_URL}
+      - HF_HUB_OFFLINE=1
+      - TRANSFORMERS_OFFLINE=1
+    volumes:
+      - /etc/timezone:/etc/timezone:ro
+      - /etc/localtime:/etc/localtime:ro
+      - ${Volumes_Path}/backups:/home/hindsight/backups
+    networks:
+      - hindsight-net
+
+networks:
+  hindsight-net:
+    driver: bridge