diff --git a/hindsight/readme.md b/hindsight/readme.md
index 8dea044..970595e 100644
--- a/hindsight/readme.md
+++ b/hindsight/readme.md
@@ -2,7 +2,7 @@
 
 [vectorize-io/hindsight](https://github.com/vectorize-io/hindsight) 是一个面向 LLM Agent 的长期记忆后端，采用 PostgreSQL/pgvector 存储。Hermes Agent 用它做跨会话长期记忆。
 
-本目录是 **方案三：DB + Hindsight 分离部署**（`/home/geng/hindsight/` 下的 `docker-compose.yaml` + `.env` + `pgdata/`）迁移到 `deploy.stack` 仓库的版本。
+本目录是 **方案三：DB + Hindsight 分离部署** 迁移到 `deploy.stack` 仓库的版本。
 
 ## 目录结构
 
@@ -17,26 +17,68 @@
 ## 架构
 
 ```
-┌──────────────────────┐     5432      ┌──────────────────────┐
-│  hindsight-app 容器  │ ────────────► │  hindsight-db 容器   │
-│  (ghcr.nju.edu.cn/   │               │  (pgvector/pgvector  │
-│   vectorize-io/      │   :8888 API   │   :pg18)             │
-│   hindsight)         │   :9999 Admin │                      │
+┌──────────────────────┐               ┌──────────────────────┐
+│  hindsight-app 容器  │               │  hindsight-db 容器   │
+│  (ghcr.nju.edu.cn/   │   :5432 内网  │  (pgvector/pgvector  │
+│   vectorize-io/      │ ────────────► │   :pg18)             │
+│   hindsight)         │               │                      │
+│                      │   :8888 API   │  :5432 对外暴露      │
+│                      │   :9999 Admin │  (供外部工具连接)    │
 └──────────────────────┘               └──────────────────────┘
         │                                       │
         ▼ bind mount                            ▼ bind mount
-   ~/.cache/huggingface                   /home/geng/hindsight/pgdata
-   (BGE + ms-marco 复用)                  (PG 数据,WSL 原生 fs)
+   ${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. 准备数据目录（WSL/Linux 原生 fs，不能放 /mnt/9P）
-sudo mkdir -pv /home/geng/hindsight/pgdata /home/geng/hindsight/backups
-sudo chown -R 999:999 /home/geng/hindsight/pgdata
+# 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
@@ -56,11 +98,11 @@ docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.
 # 容器状态
 docker ps -f name=hindsight
 
-# DB 启动正常（首次启动会建表）
+# DB 连接与建表
 docker exec -it hindsight-db psql -U hindsight_user -d hindsight_db -c '\dt'
 
 # 端口监听
-ss -tlnp | grep -E '8888|9999'
+ss -tlnp | grep -E '5432|8888|9999'
 
 # API 健康检查
 curl -s http://localhost:8888/health
@@ -83,12 +125,11 @@ docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.
 
 | 决策点 | 决定 | 原因 |
 |--------|------|------|
-| 部署位置 | `/home/geng/hindsight/`（WSL 原生 fs） | `/mnt/d/mydata/` 是 9P drvfs，PG 在 9P 上 fsync 不可靠会损坏数据；Hindsight 跟随 Hermes 配置放 `~/` 下 |
-| 数据卷方案 | bind 挂载到 `~/hindsight/pgdata` | 直观、可直接 `rsync`/`pg_dump`、跨机迁移用 `tar` 整个目录即可（用户决策，覆盖默认命名卷） |
-| 端口绑定 | 0.0.0.0:8888 / 0.0.0.0:9999 | PVE LAN 上其他 VM 也可能访问（用户决策） |
-| 镜像源 | `ghcr.nju.edu.cn/vectorize-io/hindsight` | 南京大学 ghcr 镜像，国内拉得快（用户偏好） |
+| 数据卷方案 | 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 协议 |
-| 嵌入模型 | 容器内自带 BGE-small-en-v1.5 | 不需要额外配；HF 缓存 bind 复用免重下 |
+| PG 认证 | `scram-sha-256` | 比 md5 更安全，`POSTGRES_INITDB_ARGS` 同步设置 `--auth-host` |
 | 旧数据迁移 | 见 `docs-hermes-Hindsight-记忆系统部署指南.md` 决策表 | 走 A（zip 导入） 或 B（重置新 DB） 路径 |
 
 ## 备份与恢复
@@ -99,7 +140,7 @@ docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.
 
 ```bash
 # /etc/cron.d/hindsight-backup 或 crontab -e
-30 2 * * * /mnt/d/mydata/cnphpbb/deploy.stack/hindsight/backup.job >> /var/log/hindsight-backup.log 2>&1
+30 2 * * * /path/to/deploy.stack/hindsight/backup.job >> /var/log/hindsight-backup.log 2>&1
 ```
 
 或参考 `crontab/` 目录的统一任务管理方式（`shell/up.bash` 会处理 `chmod +x`）。
@@ -108,26 +149,26 @@ docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.
 
 ```bash
 # 热备份（推荐）
-docker exec hindsight-db pg_dump -U hindsight_user -d hindsight_db | gzip > ~/hindsight/backups/manual_$(date +%Y%m%d).sql.gz
+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 -f ./hindsight/stack.yml stop
-sudo rsync -a /home/geng/hindsight/pgdata/ /home/geng/hindsight/backups/pgdata-cold/
-docker compose -p hindsight -f ./hindsight/stack.yml start
+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 ~/hindsight/backups/hindsight_db_20260607_023000.sql.gz \
+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 -f ./hindsight/stack.yml down
-sudo rm -rf /home/geng/hindsight/pgdata/*
-sudo rsync -a /home/geng/hindsight/backups/pgdata-cold/ /home/geng/hindsight/pgdata/
-sudo chown -R 999:999 /home/geng/hindsight/pgdata
+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
 ```
 
@@ -136,11 +177,12 @@ docker compose -p hindsight --env-file ./hindsight/env.cfg -f ./hindsight/stack.
 | 症状 | 排查命令 |
 |------|----------|
 | 容器起不来 | `docker logs -f hindsight-app` / `docker logs -f hindsight-db` |
-| DB 连不上 | `docker exec -it hindsight-db psql -U hindsight_user -d 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 '8888\|9999'` |
+| 端口冲突 | `ss -tlnp \| grep -E '5432\|8888\|9999'` |
 | 端口未对外 | `ss -tlnp` 看是不是只监听 `127.0.0.1`，确认 `ports:` 没加 IP 前缀 |
-| BGE 模型重下 | 容器内是否有 `HF_HUB_OFFLINE=1` 和 bind 挂的 HF 缓存 |
+| 密码含特殊字符导致连接失败 | `HINDSIGHT_DB_PASSWORD` 最好不要带特殊字符，避免 URI 编码问题 |
 | glibc 错误 | 0.7.2 内嵌 pg0 需 glibc 2.38，方案三已用独立容器避开 |
 
 ## 与 Hermes 集成