让你的agent永不失忆！ Hermes + Hindsight 飞牛NAS 纯图形界面部署指南

学区房

🚀 Hermes + Hindsight 记忆系统
[size=1.2]飞牛NAS 纯图形界面部署指南（小白专用）📖 目录

• [color=var(--accent)]系统简介
• [color=var(--accent)]前期准备
• [color=var(--accent)]文件目录搭建
• [color=var(--accent)]本地创建必要文件并上传
• [color=var(--accent)]设置目录权限
• [color=var(--accent)]在 Docker 中部署应用
• [color=var(--accent)]启动与验证
• [color=var(--accent)]日常维护（图形化）
• [color=var(--accent)]备份与恢复
• [color=var(--accent)]升级指南
• [color=var(--accent)]常见问题排查
  

1. 系统简介

一键部署 AI 助手 + 长期记忆大脑，对接微信/QQ 等消息平台。

• [color=var(--accent)][size=0.8em]Hermes Agent AI 助手核心，调用 DeepSeek 大模型对话，并自动记忆你的偏好。
• [color=var(--accent)][size=0.8em]Hindsight 记忆引擎，自动提取、整理对话记忆，支持语义搜索。
  

架构很简单：微信/QQ → Hermes ↔ Hindsight 记忆库

Hindsight 的长期记忆功能必须使用 Chat 模型（如 deepseek-v4-pro），绝对不能填纯 Embedding 模型。

2. 前期准备

项目	说明
飞牛NAS	确保已安装 Docker 应用（系统自带或应用商店安装）
可用空间	建议至少剩余 20 GB
内存	至少 4 GB（推荐 8 GB 以上）
DeepSeek API Key	点击注册，在“API Keys”页面创建并复制密钥
一台电脑	用于创建配置文件并上传到 NAS

3. 文件目录搭建（纯鼠标操作）

打开飞牛NAS的“文件管理”，进入你的 Docker 工作目录（例如 /vol1/1000/Docker），新建文件夹并命名为 hermes-hindsight。然后进入该文件夹，再新建以下四个子文件夹：

datahindsight_datapostgres_databackups

最终结构如下（你只需确保这几个文件夹存在即可）：

/vol1/1000/Docker/hermes-hindsight/**── data/**── hindsight_data/**── postgres_data/**── backups/💡 路径可以自定义，但后续所有操作都要使用你设定的路径，本指南以 /vol1/1000/Docker/hermes-hindsight 为例。

4. 本地创建必要文件并上传⚠️ 重要说明：飞牛NAS 文件管理器无法直接新建 .sh、.yml 等格式的脚本文件，**所有配置文件必须在你的电脑上创建，再通过文件管理上传到 NAS 的对应目录**。同时，请务必使用专业文本编辑器（如 VS Code、Notepad++）并保存为 UTF-8 无 BOM 编码，否则可能导致脚本执行失败或中文乱码。
4.1 创建启动脚本 start-hermes.sh

第一步：在你的电脑上新建一个文本文档，重命名为 start-hermes.sh（注意扩展名是 .sh，不是 .txt）。

第二步：用编辑器打开，粘贴以下内容，并确保编码为 UTF-8 无 BOM：

#!/bin/bash# Hermes 启动后自动维护脚本set -eecho ">>> 正在执行启动后维护..."# 修复可能被 root 占用的技能文件find /opt/data/skills -user root -exec chown hermes:hermes {} \; 2>/dev/null || true# 安装记忆客户端依赖PACKAGES_DIR="/opt/data/.python_packages"mkdir -p "$PACKAGES_DIR"if [ ! -d "$PACKAGES_DIR/hindsight_client" ]; then    echo ">>> 安装 hindsight-client..."    pip install --target="$PACKAGES_DIR" hindsight-clientelse    echo ">>> 客户端已存在，跳过安装。"fiecho ">>> 维护完成。"

第三步：上传文件。打开飞牛文件管理，进入 /vol1/1000/Docker/hermes-hindsight/，点击上传，选择刚保存的 start-hermes.sh。

第四步：设置执行权限。文件上传后，右键该文件 → 属性 → 权限，勾选“执行”复选框，或者将权限数值设为 755。

4.2 创建 Docker Compose 配置文件

第一步：在电脑上新建文本文档，重命名为 docker-compose.yml（注意扩展名是 .yml，不是 .txt）。

第二步：用编辑器打开，粘贴以下完整内容，并确保编码为 UTF-8 无 BOM：

services:  # ========== Hermes AI 核心 ==========  hermes:    image: hermes-agent-custom:latest    container_name: hermes    restart: unless-stopped    network_mode: host    dns:      - 114.114.114.114      - 223.5.5.5    stdin_open: true    tty: true    user: "1000:1000"    volumes:      - ./data:/opt/data      - ./start-hermes.sh:/opt/hermes/start-hermes.sh:ro    environment:      - TZ=Asia/Shanghai      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}      - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1      - DEEPSEEK_MODEL=deepseek-v4-pro      - PYTHONPATH=/opt/data/.python_packages      - HERMES_POST_START=/bin/bash /opt/hermes/start-hermes.sh    deploy:      resources:        limits:          memory: 4G          cpus: "2.0"  # ========== 管理面板 ==========  hermes-dashboard:    image: hermes-agent-custom:latest    container_name: hermes-dashboard    restart: unless-stopped    command: dashboard --host 0.0.0.0 --insecure    network_mode: host    user: "1000:1000"    volumes:      - ./data:/opt/data    environment:      - GATEWAY_HEALTH_URL=http://127.0.0.1:8642      - TZ=Asia/Shanghai      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}      - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1      - DEEPSEEK_MODEL=deepseek-v4-pro    depends_on:      - hermes  # ========== 记忆大脑 ==========  hindsight:    image: ghcr.io/vectorize-io/hindsight:latest    container_name: hindsight    restart: unless-stopped    networks:      - internal    ports:      - "127.0.0.1:8888:8888"      - "127.0.0.1:9999:9999"    environment:      HINDSIGHT_DB_HOST: hindsight-postgres      HINDSIGHT_DB_PORT: "5432"      HINDSIGHT_DB_NAME: hindsight      HINDSIGHT_DB_USER: hindsight      HINDSIGHT_DB_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}      HINDSIGHT_DB_BACKEND: external      HINDSIGHT_API_LLM_PROVIDER: openai      HINDSIGHT_API_LLM_API_KEY: ${DEEPSEEK_API_KEY}      HINDSIGHT_API_LLM_MODEL: deepseek-v4-pro      HINDSIGHT_API_LLM_BASE_URL: https://api.deepseek.com/v1      API_BASE_URL: http://127.0.0.1:8888      HINDSIGHT_CORS_ORIGINS: "http://localhost:9999,http://127.0.0.1:9999"      HINDSIGHT_API_LISTEN_HOST: 0.0.0.0      HF_ENDPOINT: https://hf-mirror.com    volumes:      - ./hindsight_data:/home/hindsight/.pg0    depends_on:      - hindsight-postgres  # ========== 数据库 ==========  hindsight-postgres:    image: pgvector/pgvector:pg16    container_name: hindsight-postgres    restart: unless-stopped    networks:      - internal    environment:      POSTGRES_USER: hindsight      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}      POSTGRES_DB: hindsight    volumes:      - ./postgres_data:/var/lib/postgresql/datanetworks:  internal:    driver: bridge

第三步：上传文件。将 docker-compose.yml 上传到 NAS 的 /vol1/1000/Docker/hermes-hindsight/ 目录下。

⚠️ 关于镜像标签：我们使用了 :latest 标签，这能让你随时获得最新版，但也可能包含未充分测试的变更。如果你追求绝对稳定，可将 latest 手动改为具体版本号（例如 :v0.13.0 和 :0.6）。后续升级章节会教你如何安全切换。

5. 设置目录权限

容器内的 AI 用户 UID 是 1000，因此必须将 data 文件夹的拥有者改为 1000。在飞牛文件管理器中，右键点击 data 文件夹 → 属性 → 权限，将“所有者”和“组”都改为 1000，并勾选“应用到子文件夹及文件”。

如果文件管理器无法直接修改数字 UID，可以打开飞牛的“终端”应用，执行下面这一条命令（复制粘贴回车即可）：

sudo chown -R 1000:1000 /vol1/1000/Docker/hermes-hindsight/data⚠️ 千万不要修改 hindsight_data 和 postgres_data 的权限！

6. 在 Docker 中部署应用

• 打开飞牛NAS的 Docker 管理界面，找到“堆栈”或“应用”菜单，点击“添加堆栈”。
• 命名堆栈为 hermes-hindsight，然后在配置框中将刚才创建的 docker-compose.yml 内容全选复制进去。
• 设置环境变量（密钥填在这里最安全）。在“环境变量”区域添加两行：
  DEEPSEEK_API_KEY=你的DeepSeek密钥
  HINDSIGHT_DB_PASSWORD=数据库密码，可自定，默认ChangeMe123!
• 存储卷映射部分检查是否已自动识别当前目录下的 data、hindsight_data、postgres_data 以及 start-hermes.sh，如没有自动识别，手动添加上面 compose 中对应的映射关系。
• 点击部署，系统将自动拉取镜像并创建所有容器。等待 2~3 分钟即可。
  

7. 启动与验证

部署成功后，在 Docker 容器列表中应看到四个容器均显示“运行中”。然后进行简单验证：

• 记忆引擎健康检查：浏览器访问 http://你的NAS-IP:8888/health，看到 {"status":"healthy"} 即正常。
• AI 面板：访问 http://你的NAS-IP:9119，如果出现管理界面，说明 Hermes 已启动。
• 日志检查：在 Docker 界面点击 hermes 容器，查看日志，没有报错即可。
  

8. 日常维护（图形化）

• 查看运行状态：在 Docker 界面直接观察容器状态。
• 重启服务：选中容器，点击“重启”。
• 查看日志：点击容器名，切换到“日志”标签页。
• 清理无用镜像：Docker 设置里通常有“清理”功能，可释放空间。
• 手动整理记忆：如果感觉记忆积压，可用浏览器访问以下地址触发合并：
  http://你的NAS-IP:8888/v1/default/banks/hermes/consolidate （会返回 JSON 结果）
  

9. 备份与恢复

备份：在文件管理器中，直接将 /vol1/1000/Docker/hermes-hindsight 整个文件夹复制到另一块硬盘或 NAS 其他目录即可。建议先停止所有容器再复制。

恢复：将备份的文件夹放回原路径，进入 Docker 堆栈页面，重新部署同一份 compose 文件（或直接启动已有容器），系统会自动识别原有数据。

💡 更优雅的自动备份：你可以将整个项目文件夹设置为飞牛自带的“备份任务”源目录，定时备份到远程或外接硬盘。

10. 升级指南

因为使用了 :latest 标签，升级变得异常简单：

• 在 Docker 界面选中你的堆栈，点击“重新创建”。
• 勾选“拉取最新镜像”或“强制拉取”。
• 点击执行，系统会自动下载新版镜像并重建容器。
  

如果你之前锁定了版本号，只需在 compose 中修改标签为 :latest 后再执行上述操作。

回退旧版：如果新版出现异常，把 compose 中的标签改回上一个稳定版本（如 :v0.13.0 和 :0.6），然后“重新创建”即可。记得先把数据备份一下。

11. 常见问题排查❶ 记忆引擎报“LLM API key required”

原因：部署时环境变量 DEEPSEEK_API_KEY 未正确填写。
解决：在 Docker 堆栈编辑页面，检查环境变量键名是否完全一致，密钥是否正确。

❷ Hermes 无法启动，日志提示“unable to open database file”

原因：data 文件夹权限不是 1000:1000。
解决：按第 5 节重新设置权限，然后重启容器。

❸ 记忆提取报 422 错误或超时

原因：你填写的模型是纯 Embedding 模型，不支持对话。
解决：确保环境变量 HINDSIGHT_API_LLM_MODEL 为 deepseek-v4-pro 或其他 Chat 模型。

❹ 镜像拉取总是超时

原因：国内访问 ghcr.io 不稳定。
解决：在 Docker 设置中配置国内镜像加速器，或请朋友下载离线镜像包（.tar）后，在飞牛 Docker 界面中“导入”。

❺ 升级后容器启动异常

原因：最新版可能有兼容问题。
解决：临时回退：将 compose 中的 :latest 改成之前的版本号，然后“重新创建”。确定稳定后再考虑是否追新。

❻ 脚本上传后无法执行或中文乱码

原因：文件编码不正确（如使用了系统默认的 GBK 编码），或者文件格式不是 Unix 换行。
解决：在电脑上使用 VS Code / Notepad++ 打开文件，将编码改为 UTF-8 无 BOM，换行符选择 LF，重新保存后覆盖上传。

lixilu

这是直接哪里复制来的

学区房

lixilu 发表于 2026-5-13 11:34
这是直接哪里复制来的

1. #!/bin/bash
   
2. # 一键生成 Hermes + Hindsight 部署压缩包
   
3. # 执行后将在当前目录生成 hermes-hindsight-deploy.tar.gz
   
4. 
   
5. set -euo pipefail
   
6. 
   
7. PACKAGE_DIR="hermes-hindsight-deploy"
   
8. rm -rf "$PACKAGE_DIR"
   
9. mkdir -p "$PACKAGE_DIR"
   
10. 
    
11. cd "$PACKAGE_DIR"
    
12. 
    
13. # ==========================
    
14. # 1. 环境变量 .env
    
15. # ==========================
    
16. cat > .env <<'ENVEOF'
    
17. # DeepSeek API Key（同时用于 Hermes 与 Hindsight）
    
18. DEEPSEEK_API_KEY=你的DeepSeek-API-Key
    
19. 
    
20. # PostgreSQL 数据库密码（可自定义）
    
21. HINDSIGHT_DB_PASSWORD=ChangeMe123!
    
22. ENVEOF
    
23. chmod 600 .env
    
24. 
    
25. # ==========================
    
26. # 2. 启动后脚本 start-hermes.sh
    
27. # ==========================
    
28. cat > start-hermes.sh <<'STARTEOF'
    
29. #!/bin/bash
    
30. # Hermes 启动后自动执行的维护脚本
    
31. set -e
    
32. echo ">>> [start-hermes] 开始执行启动后维护..."
    
33. 
    
34. # 修复技能文件权限（可能被 root 创建）
    
35. find /opt/data/skills -user root -exec chown hermes:hermes {} \; 2>/dev/null || true
    
36. 
    
37. # 安装 hindsight_client 到用户包目录
    
38. PACKAGES_DIR="/opt/data/.python_packages"
    
39. mkdir -p "$PACKAGES_DIR"
    
40. if [ ! -d "$PACKAGES_DIR/hindsight_client" ]; then
    
41.     echo ">>> 安装 hindsight-client..."
    
42.     pip install --target="$PACKAGES_DIR" hindsight-client
    
43. else
    
44.     echo ">>> hindsight-client 已存在，跳过安装。"
    
45. fi
    
46. echo ">>> [start-hermes] 维护任务完成。"
    
47. STARTEOF
    
48. chmod +x start-hermes.sh
    
49. 
    
50. # ==========================
    
51. # 3. 自动备份脚本 backup.sh
    
52. # ==========================
    
53. cat > backup.sh <<'BACKEOF'
    
54. #!/bin/bash
    
55. # 自动备份脚本（建议配合 cron 定时执行）
    
56. set -euo pipefail
    
57. 
    
58. PROJECT_DIR="/opt/docker/hermes-hindsight"
    
59. BACKUP_DIR="$PROJECT_DIR/backups"
    
60. RETENTION_DAYS=30
    
61. DATE_TAG=$(date +%Y%m%d-%H%M)
    
62. BACKUP_FILE="hermes-hindsight-backup-${DATE_TAG}.tar.gz"
    
63. 
    
64. log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"; }
    
65. 
    
66. mkdir -p "$BACKUP_DIR"
    
67. log "停止服务以保证数据一致性..."
    
68. cd "$PROJECT_DIR"
    
69. docker compose down || log "警告：停止服务失败，继续备份..."
    
70. 
    
71. log "正在打包备份..."
    
72. tar -czf "$BACKUP_DIR/$BACKUP_FILE" -C "$(dirname "$PROJECT_DIR")" "$(basename "$PROJECT_DIR")"
    
73. if [ $? -eq 0 ]; then
    
74.     log "备份成功：$BACKUP_DIR/$BACKUP_FILE"
    
75. else
    
76.     log "备份失败！"
    
77.     exit 1
    
78. fi
    
79. 
    
80. log "重新启动服务..."
    
81. docker compose up -d
    
82. 
    
83. log "清理 ${RETENTION_DAYS} 天前的旧备份..."
    
84. find "$BACKUP_DIR" -name "*.tar.gz" -mtime +$RETENTION_DAYS -delete
    
85. log "备份流程完成。"
    
86. BACKEOF
    
87. chmod +x backup.sh
    
88. 
    
89. # ==========================
    
90. # 4. 升级脚本 upgrade_v2.sh
    
91. # ==========================
    
92. cat > upgrade_v2.sh <<'UPGEOF'
    
93. #!/bin/bash
    
94. # 升级脚本 v2.0 — 支持 :latest 自动拉取 + 指定版本回退
    
95. set -euo pipefail
    
96. 
    
97. PROJECT_DIR="/opt/docker/hermes-hindsight"
    
98. BACKUP_DIR="$PROJECT_DIR/backups"
    
99. COMPOSE_FILE="$PROJECT_DIR/docker-compose.yml"
    
100. 
     
101. # 国内加速镜像（优先级从高到低）
     
102. GHCR_MIRRORS=("ghcr.nju.edu.cn")
     
103. MAX_RETRIES=3
     
104. RETRY_DELAY=5
     
105. 
     
106. log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"; }
     
107. 
     
108. NEW_HERMES_VERSION="${1:-}"
     
109. NEW_HINDSIGHT_VERSION="${2:-}"
     
110. 
     
111. # 前置备份
     
112. log "升级前自动备份..."
     
113. mkdir -p "$BACKUP_DIR"
     
114. tar -czf "$BACKUP_DIR/pre-upgrade-$(date +%Y%m%d-%H%M).tar.gz" -C "$(dirname "$PROJECT_DIR")" "$(basename "$PROJECT_DIR")"
     
115. 
     
116. # 如果传入了版本号，则临时修改 compose 中的镜像标签
     
117. cd "$PROJECT_DIR"
     
118. if [ -n "$NEW_HERMES_VERSION" ]; then
     
119.     log "临时指定 Hermes 版本为 $NEW_HERMES_VERSION"
     
120.     sed -i "s|\(hermes-agent-custom:\)[^ ]*|\1$NEW_HERMES_VERSION|g" "$COMPOSE_FILE"
     
121. fi
     
122. if [ -n "$NEW_HINDSIGHT_VERSION" ]; then
     
123.     log "临时指定 Hindsight 版本为 $NEW_HINDSIGHT_VERSION"
     
124.     sed -i "s|\(ghcr.io/vectorize-io/hindsight:\)[^ ]*|\1$NEW_HINDSIGHT_VERSION|g" "$COMPOSE_FILE"
     
125. fi
     
126. 
     
127. # 增强拉取函数
     
128. pull_image() {
     
129.     local img="$1"
     
130.     if docker pull "$img" 2>/dev/null; then return 0; fi
     
131.     if [[ "$img" == ghcr.io/* ]]; then
     
132.         local path="${img#ghcr.io/}"
     
133.         local tag="latest"
     
134.         [[ "$path" == *:* ]] && { tag="${path##*:}"; path="${path%:*}"; }
     
135.         for mirror in "${GHCR_MIRRORS[@]}"; do
     
136.             local mirror_img="${mirror}/${path}:${tag}"
     
137.             if docker pull "$mirror_img" 2>/dev/null; then
     
138.                 docker tag "$mirror_img" "$img"
     
139.                 return 0
     
140.             fi
     
141.         done
     
142.     fi
     
143.     return 1
     
144. }
     
145. 
     
146. log "拉取镜像（将根据 compose 中的标签拉取）..."
     
147. docker compose pull || {
     
148.     # 如果 compose pull 失败，则尝试逐个镜像手动拉取
     
149.     IMAGES=$(grep 'image:' "$COMPOSE_FILE" | awk '{print $2}' | sort -u)
     
150.     for img in $IMAGES; do
     
151.         [[ "$img" == *\$\{* ]] && continue
     
152.         for ((i=0; i<MAX_RETRIES; i++)); do
     
153.             if pull_image "$img"; then break; fi
     
154.             log "重试 $((i+1))/$MAX_RETRIES ..."
     
155.             sleep $RETRY_DELAY
     
156.         done
     
157.     done
     
158. }
     
159. 
     
160. log "重建容器..."
     
161. docker compose down
     
162. docker compose up -d --force-recreate
     
163. 
     
164. sleep 15
     
165. # 健康检查
     
166. curl -s http://127.0.0.1:8888/health | grep -q "healthy" && echo "✅ Hindsight OK" || echo "❌ Hindsight 异常"
     
167. docker ps | grep -q hermes && echo "✅ Hermes 运行中" || echo "❌ Hermes 未运行"
     
168. log "升级完成。"
     
169. echo "提示：如果刚才传入了临时版本号，请更新 compose 文件中的标签以保持与当前运行版本一致。"
     
170. UPGEOF
     
171. chmod +x upgrade_v2.sh
     
172. 
     
173. # ==========================
     
174. # 5. docker-compose.yml
     
175. # ==========================
     
176. cat > docker-compose.yml <<'COMPEOF'
     
177. # Hermes Agent + Hindsight 部署配置（修复版，已适配 DeepSeek）
     
178. services:
     
179.   # =================== Hermes Agent ===================
     
180.   hermes:
     
181.     image: hermes-agent-custom:latest    # 最新版（如要锁定版本，替换为 :v0.13.0 等）
     
182.     container_name: hermes               # 可改为你喜欢的名称
     
183.     restart: unless-stopped
     
184.     network_mode: host
     
185.     dns:
     
186.       - 114.114.114.114
     
187.       - 223.5.5.5
     
188.     stdin_open: true
     
189.     tty: true
     
190.     user: "1000:1000"                    # 必须与宿主机数据目录属主一致
     
191.     volumes:
     
192.       - ./data:/opt/data
     
193.       - ./start-hermes.sh:/opt/hermes/start-hermes.sh:ro
     
194.     environment:
     
195.       - TZ=Asia/Shanghai
     
196.       - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
     
197.       - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
     
198.       - DEEPSEEK_MODEL=deepseek-v4-pro
     
199.       - PYTHONPATH=/opt/data/.python_packages
     
200.       - HERMES_POST_START=/bin/bash /opt/hermes/start-hermes.sh
     
201.     deploy:
     
202.       resources:
     
203.         limits:
     
204.           memory: 4G
     
205.           cpus: "2.0"
     
206. 
     
207.   # =================== Hermes Dashboard ===================
     
208.   hermes-dashboard:
     
209.     image: hermes-agent-custom:latest    # 与 hermes 镜像保持一致
     
210.     container_name: hermes-dashboard     # 可改为你喜欢的名称
     
211.     restart: unless-stopped
     
212.     command: dashboard --host 0.0.0.0 --insecure
     
213.     network_mode: host
     
214.     user: "1000:1000"
     
215.     volumes:
     
216.       - ./data:/opt/data
     
217.     environment:
     
218.       - GATEWAY_HEALTH_URL=http://127.0.0.1:8642
     
219.       - TZ=Asia/Shanghai
     
220.       - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
     
221.       - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
     
222.       - DEEPSEEK_MODEL=deepseek-v4-pro
     
223.     depends_on:
     
224.       - hermes
     
225.     deploy:
     
226.       resources:
     
227.         limits:
     
228.           memory: 512M
     
229.           cpus: "0.5"
     
230. 
     
231.   # =================== Hindsight 记忆大脑 ===================
     
232.   hindsight:
     
233.     image: ghcr.io/vectorize-io/hindsight:latest   # 最新版（如要锁定版本，替换为 :0.6 等）
     
234.     container_name: hindsight                       # 可改为你喜欢的名称
     
235.     restart: unless-stopped
     
236.     networks:
     
237.       - internal
     
238.     ports:
     
239.       - "127.0.0.1:8888:8888"
     
240.       - "127.0.0.1:9999:9999"
     
241.     environment:
     
242.       # 数据库（外部 PostgreSQL）
     
243.       HINDSIGHT_DB_HOST: hindsight-postgres
     
244.       HINDSIGHT_DB_PORT: "5432"
     
245.       HINDSIGHT_DB_NAME: hindsight
     
246.       HINDSIGHT_DB_USER: hindsight
     
247.       HINDSIGHT_DB_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}
     
248.       HINDSIGHT_DB_BACKEND: external
     
249.       # LLM 配置（使用 DeepSeek）
     
250.       HINDSIGHT_API_LLM_PROVIDER: openai
     
251.       HINDSIGHT_API_LLM_API_KEY: ${DEEPSEEK_API_KEY}
     
252.       HINDSIGHT_API_LLM_MODEL: deepseek-v4-pro
     
253.       HINDSIGHT_API_LLM_BASE_URL: https://api.deepseek.com/v1
     
254.       # Web 界面
     
255.       API_BASE_URL: http://127.0.0.1:8888
     
256.       HINDSIGHT_CORS_ORIGINS: "http://localhost:9999,http://127.0.0.1:9999"
     
257.       HINDSIGHT_API_LISTEN_HOST: 0.0.0.0
     
258.       # 模型下载加速
     
259.       HF_ENDPOINT: https://hf-mirror.com
     
260.     volumes:
     
261.       - ./hindsight_data:/home/hindsight/.pg0
     
262.     depends_on:
     
263.       - hindsight-postgres
     
264. 
     
265.   # =================== PostgreSQL 数据库 ===================
     
266.   hindsight-postgres:
     
267.     image: pgvector/pgvector:pg16
     
268.     container_name: hindsight-postgres    # 可改为你喜欢的名称
     
269.     restart: unless-stopped
     
270.     networks:
     
271.       - internal
     
272.     environment:
     
273.       POSTGRES_USER: hindsight
     
274.       POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}
     
275.       POSTGRES_DB: hindsight
     
276.     volumes:
     
277.       - ./postgres_data:/var/lib/postgresql/data
     
278. 
     
279. networks:
     
280.   internal:
     
281.     driver: bridge
     
282. COMPEOF
     
283. 
     
284. # ==========================
     
285. # 6. README.html（完整指南）
     
286. # ==========================
     
287. cat > README.html <<'HTMLEOF'
     
288. <!DOCTYPE html>
     
289. <html lang="zh-CN">
     
290. <head>
     
291. <meta charset="UTF-8">
     
292. <meta name="viewport" content="width=device-width, initial-scale=1.0">
     
293. <title>Hermes + Hindsight 完全部署与维护指南 · 飞牛NAS版</title>
     
294. <style>
     
295.   :root {
     
296.     --bg: #f9fafb; --card: #ffffff; --text: #1e293b; --code-bg: #1e293b; --code-text: #e2e8f0;
     
297.     --accent: #2563eb; --accent-light: #dbeafe; --warn: #f59e0b; --warn-light: #fef3c7;
     
298.     --error: #ef4444; --error-light: #fee2e2; --border: #e2e8f0;
     
299.     --radius: 12px;
     
300.   }
     
301.   * { box-sizing: border-box; margin: 0; padding: 0; }
     
302.   body {
     
303.     font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
     
304.     background: var(--bg); color: var(--text); line-height: 1.7; padding: 2rem;
     
305.   }
     
306.   .container { max-width: 1000px; margin: 0 auto; }
     
307.   h1 { font-size: 2.5rem; margin-bottom: 0.5rem; color: #0f172a; }
     
308.   h2 { font-size: 1.8rem; margin-top: 2.5rem; padding-bottom: 0.3rem; border-bottom: 2px solid var(--accent); color: #0f172a; }
     
309.   h3 { font-size: 1.3rem; margin-top: 1.8rem; color: #334155; }
     
310.   p { margin: 1rem 0; }
     
311.   .card {
     
312.     background: var(--card); border: 1px solid var(--border); border-radius: var(--radius);
     
313.     padding: 1.5rem; margin: 1.5rem 0; box-shadow: 0 1px 3px rgba(0,0,0,0.04);
     
314.   }
     
315.   code {
     
316.     background: #f1f5f9; padding: 0.2em 0.5em; border-radius: 4px; font-size: 0.9em;
     
317.     font-family: 'JetBrains Mono', 'Fira Code', monospace;
     
318.   }
     
319.   pre {
     
320.     background: var(--code-bg); color: var(--code-text); border-radius: var(--radius);
     
321.     padding: 1.2rem; overflow-x: auto; margin: 1rem 0; font-size: 0.85em; line-height: 1.5;
     
322.   }
     
323.   pre code { background: none; padding: 0; color: inherit; }
     
324.   .badge {
     
325.     display: inline-block; padding: 0.1em 0.7em; border-radius: 20px; font-size: 0.8em;
     
326.     font-weight: 600; margin-right: 0.5rem;
     
327.   }
     
328.   .badge-info { background: var(--accent-light); color: var(--accent); }
     
329.   .badge-warn { background: var(--warn-light); color: #92400e; }
     
330.   .badge-error { background: var(--error-light); color: #b91c1c; }
     
331.   .step-list { counter-reset: step; list-style: none; padding-left: 0; }
     
332.   .step-list li { counter-increment: step; margin-bottom: 1.5rem; position: relative; padding-left: 2.5rem; }
     
333.   .step-list li::before {
     
334.     content: counter(step); background: var(--accent); color: white; font-weight: bold;
     
335.     border-radius: 50%; width: 1.8rem; height: 1.8rem; display: inline-flex; align-items: center;
     
336.     justify-content: center; position: absolute; left: 0; top: 0;
     
337.   }
     
338.   .toc { background: var(--card); border-radius: var(--radius); padding: 1.5rem; margin: 2rem 0; }
     
339.   .toc a { text-decoration: none; color: var(--accent); }
     
340.   .toc ol { padding-left: 1.5rem; }
     
341.   .table-wrap { overflow-x: auto; }
     
342.   table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
     
343.   th, td { border: 1px solid var(--border); padding: 0.7rem; text-align: left; }
     
344.   th { background: #f8fafc; }
     
345.   .warning { background: var(--warn-light); border-left: 4px solid var(--warn); padding: 1rem; border-radius: 0 8px 8px 0; margin: 1rem 0; }
     
346.   .danger { background: var(--error-light); border-left: 4px solid var(--error); padding: 1rem; border-radius: 0 8px 8px 0; margin: 1rem 0; }
     
347. </style>
     
348. </head>
     
349. <body>
     
350. <div class="container">
     
351. 
     
352. <h1>🚀 Hermes Agent + Hindsight 记忆系统<br><span style="font-size:1.2rem; font-weight:400;">飞牛NAS Docker 完全部署与维护指南</span></h1>
     
353. 
     
354. <div class="toc">
     
355.   <strong>📖 目录</strong>
     
356.   <ol>
     
357.     <li><a href="#intro">系统简介</a></li>
     
358.     <li><a href="#requirements">环境要求</a></li>
     
359.     <li><a href="#structure">目录结构与文件清单</a></li>
     
360.     <li><a href="#prep">部署前准备</a></li>
     
361.     <li><a href="#config">编写配置文件（全部修复版）</a></li>
     
362.     <li><a href="#startup">启动与验证</a></li>
     
363.     <li><a href="#maintain">日常维护</a></li>
     
364.     <li><a href="#backup">备份与恢复</a></li>
     
365.     <li><a href="#upgrade">升级指南</a></li>
     
366.     <li><a href="#troubleshoot">常见问题排查</a></li>
     
367.     <li><a href="#history">附录：历史故障修复记录</a></li>
     
368.   </ol>
     
369. </div>
     
370. 
     
371. <!-- 1. 系统简介 -->
     
372. <h2 id="intro">1. 系统简介</h2>
     
373. <div class="card">
     
374.   <p>本系统由两个核心服务组成：</p>
     
375.   <ul>
     
376.     <li><span class="badge badge-info">Hermes Agent</span> AI 助手大脑，对接微信/QQ 等消息平台，调用大模型推理，同时与 Hindsight 交互实现长期记忆。</li>
     
377.     <li><span class="badge badge-info">Hindsight</span> 记忆引擎，自动从对话中提取、存储、检索记忆，支持语义搜索和图谱检索。</li>
     
378.   </ul>
     
379.   <p>整体架构：<code>微信/QQ → Hermes Agent ↔ Hindsight API ↔ PostgreSQL (pgvector)</code></p>
     
380.   <p>关键知识点：Hindsight 的 <code>reflect</code> 和 <code>retain</code> 功能需要 <strong>Chat 模型</strong>（如 <code>deepseek-v4-pro</code>），不能使用纯 Embedding 模型。</p>
     
381. </div>
     
382. 
     
383. <!-- 2. 环境要求 -->
     
384. <h2 id="requirements">2. 环境要求</h2>
     
385. <div class="card">
     
386.   <div class="table-wrap">
     
387.     <table>
     
388.       <tr><th>项目</th><th>要求</th></tr>
     
389.       <tr><td>操作系统</td><td>飞牛NAS (fnOS)、Ubuntu 20.04+、Debian 11+</td></tr>
     
390.       <tr><td>Docker</td><td>≥ 20.10（推荐 24+）</td></tr>
     
391.       <tr><td>Docker Compose</td><td>插件形式或独立二进制均可</td></tr>
     
392.       <tr><td>磁盘可用空间</td><td>≥ 20 GB（镜像约6GB + 数据增长）</td></tr>
     
393.       <tr><td>内存</td><td>≥ 4 GB（推荐 8 GB，本地 Embedding 需内存）</td></tr>
     
394.       <tr><td>网络</td><td>容器需访问外网拉取镜像并调用 LLM API</td></tr>
     
395.       <tr><td>API 密钥</td><td>DeepSeek（或其他兼容 OpenAI 接口的服务）API Key</td></tr>
     
396.     </table>
     
397.   </div>
     
398. </div>
     
399. 
     
400. <!-- 3. 目录结构 -->
     
401. <h2 id="structure">3. 目录结构与文件清单</h2>
     
402. <div class="card">
     
403.   <p>所有文件统一放在项目目录下，本指南以 <code>/opt/docker/hermes-hindsight</code> 为例（你可以自定义路径，但后续所有操作需保持一致）。最终结构：</p>
     
404. <pre><code>/opt/docker/hermes-hindsight/
     
405. **── docker-compose.yml          # 服务编排文件（必须）
     
406. **── .env                        # 密钥等敏感信息（必须，权限 600）
     
407. **── start-hermes.sh             # Hermes 启动后自动执行脚本（必须，权限 755）
     
408. **── backup.sh                   # 自动备份脚本（建议）
     
409. **── upgrade_v2.sh               # 升级脚本（国内网络优化版）
     
410. **── data/                       # Hermes 持久化数据（属主 1000:1000）
     
411. **── hindsight_data/             # Hindsight 内嵌数据库文件
     
412. **── postgres_data/              # PostgreSQL 数据库文件
     
413. **── backups/                    # 备份存放目录（自动创建）
     
414. </code></pre>
     
415.   <div class="danger"><strong>注意：</strong>删除容器不会丢失数据，数据都在以上目录中。请勿手动修改 <code>postgres_data</code> 权限。</div>
     
416. </div>
     
417. 
     
418. <!-- 4. 部署前准备 -->
     
419. <h2 id="prep">4. 部署前准备</h2>
     
420. 
     
421. <h3>4.1 安装 Docker 环境</h3>
     
422. <div class="card">
     
423. <pre><code># 飞牛NAS / Debian 系列
     
424. curl -fsSL https://get.docker.com | bash
     
425. sudo usermod -aG docker $USER
     
426. newgrp docker
     
427. # 检查版本
     
428. docker --version
     
429. docker compose version</code></pre>
     
430. <p>若 <code>docker compose</code> 命令不存在，安装插件：<code>sudo apt install docker-compose-plugin</code></p>
     
431. </div>
     
432. 
     
433. <h3>4.2 创建项目目录</h3>
     
434. <div class="card">
     
435.   <p>在开始编写配置文件之前，先建立项目目录并进入：</p>
     
436. <pre><code>sudo mkdir -p /opt/docker/hermes-hindsight
     
437. cd /opt/docker/hermes-hindsight</code></pre>
     
438.   <p>（若使用其他路径，请自行替换，并确保后续所有脚本中的路径与之匹配。）</p>
     
439. </div>
     
440. 
     
441. <h3>4.3 获取 API 密钥</h3>
     
442. <div class="card">
     
443.   <ul>
     
444.     <li><strong>DeepSeek</strong>：<a href="https://platform.deepseek.com" target="_blank">注册</a> → API Keys。推荐模型 <code>deepseek-v4-pro</code>（支持 Chat），也可使用 <code>deepseek-r1</code> 作为备用。</li>
     
445.   </ul>
     
446.   <div class="warning">绝不能使用 <strong>纯 Embedding 模型</strong> 作为 LLM，否则 reflect/retain 会报 422 错误或超时！</div>
     
447. </div>
     
448. 
     
449. <!-- 5. 编写配置文件 -->
     
450. <h2 id="config">5. 编写配置文件（全部修复版）</h2>
     
451. 
     
452. <div class="warning">
     
453.   <strong>⚠️ 关于镜像标签：</strong>以下配置中使用了 <code>:latest</code> 标签，意味着始终拉取最新版本。这可以让你快速获得新功能，但也可能引入未充分测试的变更，存在稳定性风险。如果你用于生产环境或希望长期稳定运行，建议将 <code>latest</code> 替换为具体版本号（如 <code>:v0.13.0</code>），并参考后续升级章节按需更新。
     
454. </div>
     
455. 
     
456. <h3>5.1 环境变量 <code>.env</code></h3>
     
457. <div class="card">
     
458.   <p>在项目目录下创建 <code>.env</code>，替换为你的真实密钥：</p>
     
459. <pre><code># DeepSeek API Key（同时用于 Hermes 与 Hindsight）
     
460. DEEPSEEK_API_KEY=你的DeepSeek-API-Key
     
461. 
     
462. # PostgreSQL 数据库密码（可自定义）
     
463. HINDSIGHT_DB_PASSWORD=ChangeMe123!</code></pre>
     
464.   <p>设置权限：<code>chmod 600 .env</code></p>
     
465. </div>
     
466. 
     
467. <h3>5.2 Docker Compose <code>docker-compose.yml</code></h3>
     
468. <div class="card">
     
469.   <p><strong>容器名称自定义说明：</strong>以下配置中使用了固定容器名（如 <code>hermes</code>、<code>hindsight</code> 等）。你可以按需修改每个服务的 <code>container_name</code> 字段，只需保证后续引用的名称一致即可。例如将 <code>hermes</code> 改为 <code>my-hermes</code>，则后续查看日志、进入容器的命令也要使用新名称。</p>
     
470. <pre><code># Hermes Agent + Hindsight 部署配置（修复版，已适配 DeepSeek）
     
471. services:
     
472.   # =================== Hermes Agent ===================
     
473.   hermes:
     
474.     image: hermes-agent-custom:latest    # 最新版（如要锁定版本，替换为 :v0.13.0 等）
     
475.     container_name: hermes               # 可改为你喜欢的名称
     
476.     restart: unless-stopped
     
477.     network_mode: host
     
478.     dns:
     
479.       - 114.114.114.114
     
480.       - 223.5.5.5
     
481.     stdin_open: true
     
482.     tty: true
     
483.     user: "1000:1000"                    # 必须与宿主机数据目录属主一致
     
484.     volumes:
     
485.       - ./data:/opt/data
     
486.       - ./start-hermes.sh:/opt/hermes/start-hermes.sh:ro
     
487.     environment:
     
488.       - TZ=Asia/Shanghai
     
489.       - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
     
490.       - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
     
491.       - DEEPSEEK_MODEL=deepseek-v4-pro
     
492.       - PYTHONPATH=/opt/data/.python_packages
     
493.       - HERMES_POST_START=/bin/bash /opt/hermes/start-hermes.sh
     
494.     deploy:
     
495.       resources:
     
496.         limits:
     
497.           memory: 4G
     
498.           cpus: "2.0"
     
499. 
     
500.   # =================== Hermes Dashboard ===================
     
501.   hermes-dashboard:
     
502.     image: hermes-agent-custom:latest    # 与 hermes 镜像保持一致
     
503.     container_name: hermes-dashboard     # 可改为你喜欢的名称
     
504.     restart: unless-stopped
     
505.     command: dashboard --host 0.0.0.0 --insecure
     
506.     network_mode: host
     
507.     user: "1000:1000"
     
508.     volumes:
     
509.       - ./data:/opt/data
     
510.     environment:
     
511.       - GATEWAY_HEALTH_URL=http://127.0.0.1:8642
     
512.       - TZ=Asia/Shanghai
     
513.       - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
     
514.       - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
     
515.       - DEEPSEEK_MODEL=deepseek-v4-pro
     
516.     depends_on:
     
517.       - hermes
     
518.     deploy:
     
519.       resources:
     
520.         limits:
     
521.           memory: 512M
     
522.           cpus: "0.5"
     
523. 
     
524.   # =================== Hindsight 记忆大脑 ===================
     
525.   hindsight:
     
526.     image: ghcr.io/vectorize-io/hindsight:latest   # 最新版（如要锁定版本，替换为 :0.6 等）
     
527.     container_name: hindsight                       # 可改为你喜欢的名称
     
528.     restart: unless-stopped
     
529.     networks:
     
530.       - internal
     
531.     ports:
     
532.       - "127.0.0.1:8888:8888"
     
533.       - "127.0.0.1:9999:9999"
     
534.     environment:
     
535.       # 数据库（外部 PostgreSQL）
     
536.       HINDSIGHT_DB_HOST: hindsight-postgres
     
537.       HINDSIGHT_DB_PORT: "5432"
     
538.       HINDSIGHT_DB_NAME: hindsight
     
539.       HINDSIGHT_DB_USER: hindsight
     
540.       HINDSIGHT_DB_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}
     
541.       HINDSIGHT_DB_BACKEND: external
     
542.       # LLM 配置（使用 DeepSeek）
     
543.       HINDSIGHT_API_LLM_PROVIDER: openai
     
544.       HINDSIGHT_API_LLM_API_KEY: ${DEEPSEEK_API_KEY}
     
545.       HINDSIGHT_API_LLM_MODEL: deepseek-v4-pro
     
546.       HINDSIGHT_API_LLM_BASE_URL: https://api.deepseek.com/v1
     
547.       # Web 界面
     
548.       API_BASE_URL: http://127.0.0.1:8888
     
549.       HINDSIGHT_CORS_ORIGINS: "http://localhost:9999,http://127.0.0.1:9999"
     
550.       HINDSIGHT_API_LISTEN_HOST: 0.0.0.0
     
551.       # 模型下载加速
     
552.       HF_ENDPOINT: https://hf-mirror.com
     
553.     volumes:
     
554.       - ./hindsight_data:/home/hindsight/.pg0
     
555.     depends_on:
     
556.       - hindsight-postgres
     
557. 
     
558.   # =================== PostgreSQL 数据库 ===================
     
559.   hindsight-postgres:
     
560.     image: pgvector/pgvector:pg16
     
561.     container_name: hindsight-postgres    # 可改为你喜欢的名称
     
562.     restart: unless-stopped
     
563.     networks:
     
564.       - internal
     
565.     environment:
     
566.       POSTGRES_USER: hindsight
     
567.       POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}
     
568.       POSTGRES_DB: hindsight
     
569.     volumes:
     
570.       - ./postgres_data:/var/lib/postgresql/data
     
571. 
     
572. networks:
     
573.   internal:
     
574.     driver: bridge</code></pre>
     
575. </div>
     
576. 
     
577. <h3>5.3 启动后脚本 <code>start-hermes.sh</code></h3>
     
578. <div class="card">
     
579. <pre><code>#!/bin/bash
     
580. # Hermes 启动后自动执行的维护脚本
     
581. set -e
     
582. echo ">>> [start-hermes] 开始执行启动后维护..."
     
583. 
     
584. # 修复技能文件权限（可能被 root 创建）
     
585. find /opt/data/skills -user root -exec chown hermes:hermes {} \; 2>/dev/null || true
     
586. 
     
587. # 安装 hindsight_client 到用户包目录
     
588. PACKAGES_DIR="/opt/data/.python_packages"
     
589. mkdir -p "$PACKAGES_DIR"
     
590. if [ ! -d "$PACKAGES_DIR/hindsight_client" ]; then
     
591.     echo ">>> 安装 hindsight-client..."
     
592.     pip install --target="$PACKAGES_DIR" hindsight-client
     
593. else
     
594.     echo ">>> hindsight-client 已存在，跳过安装。"
     
595. fi
     
596. echo ">>> [start-hermes] 维护任务完成。"</code></pre>
     
597.   <p>赋予执行权限：<code>chmod +x start-hermes.sh</code></p>
     
598. </div>
     
599. 
     
600. <h3>5.4 设置权限（关键）</h3>
     
601. <div class="danger">
     
602.   <p>容器内 <code>hermes</code> 用户 UID 已统一为 <strong>1000</strong>，宿主机数据目录必须与此一致：</p>
     
603.   <pre><code>cd /opt/docker/hermes-hindsight
     
604. sudo chown -R 1000:1000 ./data</code></pre>
     
605.   <p><strong>不要</strong>修改 <code>hindsight_data</code> 和 <code>postgres_data</code> 的权限！</p>
     
606. </div>
     
607. 
     
608. <!-- 6. 启动与验证 -->
     
609. <h2 id="startup">6. 启动服务与验证</h2>
     
610. <ol class="step-list">
     
611.   <li>
     
612.     <strong>启动所有容器</strong>
     
613.     <pre><code>cd /opt/docker/hermes-hindsight
     
614. docker compose up -d</code></pre>
     
615.   </li>
     
616.   <li>
     
617.     <strong>检查容器状态</strong><br>
     
618.     <code>docker ps</code> 应看到四个容器均为 <code>Up</code>。
     
619.   </li>
     
620.   <li>
     
621.     <strong>验证 Hindsight API</strong>
     
622.     <pre><code>curl http://127.0.0.1:8888/health</code></pre>
     
623.     返回 <code>{"status":"healthy","database":"connected"}</code> 即正常。
     
624.   </li>
     
625.   <li>
     
626.     <strong>验证 Hermes 能否调用 Hindsight</strong>
     
627.     <pre><code>docker exec -it hermes python3 -c "from hindsight_client import Hindsight; print('OK')"</code></pre>
     
628.     <p>（若修改了容器名，请替换 <code>hermes</code> 为你的自定义名称。）</p>
     
629.   </li>
     
630.   <li>
     
631.     <strong>访问 Web 面板</strong><br>
     
632.     浏览器打开 <code>http://你的NAS-IP:9119</code>（确保防火墙放行端口）。
     
633.   </li>
     
634. </ol>
     
635. 
     
636. <!-- 7. 日常维护 -->
     
637. <h2 id="maintain">7. 日常维护</h2>
     
638. <div class="card">
     
639.   <ul>
     
640.     <li><strong>查看日志</strong>：<code>docker logs -f hermes</code> / <code>docker logs -f hindsight</code>（根据实际容器名调整）</li>
     
641.     <li><strong>进入容器</strong>：<code>docker exec -it hermes bash</code></li>
     
642.     <li><strong>重启单个服务</strong>：<code>docker restart hermes</code></li>
     
643.     <li><strong>清理 Docker 日志</strong>：<code>docker system prune -f</code></li>
     
644.     <li><strong>查看记忆状态</strong>：<code>curl http://127.0.0.1:8888/v1/default/banks/hermes/stats</code></li>
     
645.     <li><strong>手动触发记忆合并</strong>（若积压）：
     
646.       <pre><code>curl -X POST http://127.0.0.1:8888/v1/default/banks/hermes/consolidate \
     
647.   -H "Content-Type: application/json" \
     
648.   -d '{"force": true}'</code></pre>
     
649.     </li>
     
650.   </ul>
     
651. </div>
     
652. 
     
653. <!-- 8. 备份与恢复 -->
     
654. <h2 id="backup">8. 备份与恢复</h2>
     
655. 
     
656. <h3>8.1 自动备份脚本 <code>backup.sh</code></h3>
     
657. <div class="card">
     
658.   <p>请确保脚本中的 <code>PROJECT_DIR</code> 与实际项目目录一致。</p>
     
659. <pre><code>#!/bin/bash
     
660. # 自动备份脚本（建议配合 cron 定时执行）
     
661. set -euo pipefail
     
662. 
     
663. PROJECT_DIR="/opt/docker/hermes-hindsight"
     
664. BACKUP_DIR="$PROJECT_DIR/backups"
     
665. RETENTION_DAYS=30
     
666. DATE_TAG=$(date +%Y%m%d-%H%M)
     
667. BACKUP_FILE="hermes-hindsight-backup-${DATE_TAG}.tar.gz"
     
668. 
     
669. log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"; }
     
670. 
     
671. mkdir -p "$BACKUP_DIR"
     
672. log "停止服务以保证数据一致性..."
     
673. cd "$PROJECT_DIR"
     
674. docker compose down || log "警告：停止服务失败，继续备份..."
     
675. 
     
676. log "正在打包备份..."
     
677. tar -czf "$BACKUP_DIR/$BACKUP_FILE" -C "$(dirname "$PROJECT_DIR")" "$(basename "$PROJECT_DIR")"
     
678. if [ $? -eq 0 ]; then
     
679.     log "备份成功：$BACKUP_DIR/$BACKUP_FILE"
     
680. else
     
681.     log "备份失败！"
     
682.     exit 1
     
683. fi
     
684. 
     
685. log "重新启动服务..."
     
686. docker compose up -d
     
687. 
     
688. log "清理 ${RETENTION_DAYS} 天前的旧备份..."
     
689. find "$BACKUP_DIR" -name "*.tar.gz" -mtime +$RETENTION_DAYS -delete
     
690. log "备份流程完成。"</code></pre>
     
691.   <p><code>chmod +x backup.sh</code></p>
     
692.   <p>定时任务（每天凌晨3点，同样注意路径）：<code>crontab -e</code> 添加：</p>
     
693.   <pre><code>0 3 * * * /opt/docker/hermes-hindsight/backup.sh >> /opt/docker/hermes-hindsight/backup.log 2>&1</code></pre>
     
694. </div>
     
695. 
     
696. <h3>8.2 恢复数据</h3>
     
697. <div class="card">
     
698. <pre><code># 假设备份文件为 hermes-hindsight-backup-20260513-0300.tar.gz
     
699. tar -xzf hermes-hindsight-backup-20260513-0300.tar.gz -C /opt/docker/
     
700. cd /opt/docker/hermes-hindsight
     
701. sudo chown -R 1000:1000 ./data
     
702. docker compose up -d</code></pre>
     
703. </div>
     
704. 
     
705. <!-- 9. 升级指南 -->
     
706. <h2 id="upgrade">9. 升级指南（国内网络优化版）</h2>
     
707. <div class="card">
     
708.   <p>由于 compose 文件中使用了 <code>:latest</code> 标签，<strong>最简单的升级方式</strong>是直接拉取最新镜像并重建容器：</p>
     
709.   <pre><code>cd /opt/docker/hermes-hindsight
     
710. docker compose pull
     
711. docker compose up -d --force-recreate</code></pre>
     
712.   <p>若你锁定到了具体版本（例如 <code>:v0.13.0</code>），需要更新版本号后再执行上述命令。下面的升级脚本提供了更灵活的方式：<strong>不传参数时自动拉取当前标签指定的镜像并重建；传版本参数时可临时覆盖为指定版本进行升级（可用于回退或测试）</strong>。</p>
     
713. </div>
     
714. 
     
715. <h3>9.1 升级脚本 <code>upgrade_v2.sh</code></h3>
     
716. <div class="card">
     
717.   <p>请确认脚本中的 <code>PROJECT_DIR</code> 路径正确。</p>
     
718. <pre><code>#!/bin/bash
     
719. # 升级脚本 v2.0 — 支持 :latest 自动拉取 + 指定版本回退
     
720. set -euo pipefail
     
721. 
     
722. PROJECT_DIR="/opt/docker/hermes-hindsight"
     
723. BACKUP_DIR="$PROJECT_DIR/backups"
     
724. COMPOSE_FILE="$PROJECT_DIR/docker-compose.yml"
     
725. 
     
726. # 国内加速镜像（优先级从高到低）
     
727. GHCR_MIRRORS=("ghcr.nju.edu.cn")
     
728. MAX_RETRIES=3
     
729. RETRY_DELAY=5
     
730. 
     
731. log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"; }
     
732. 
     
733. NEW_HERMES_VERSION="${1:-}"
     
734. NEW_HINDSIGHT_VERSION="${2:-}"
     
735. 
     
736. # 前置备份
     
737. log "升级前自动备份..."
     
738. mkdir -p "$BACKUP_DIR"
     
739. tar -czf "$BACKUP_DIR/pre-upgrade-$(date +%Y%m%d-%H%M).tar.gz" -C "$(dirname "$PROJECT_DIR")" "$(basename "$PROJECT_DIR")"
     
740. 
     
741. # 如果传入了版本号，则临时修改 compose 中的镜像标签
     
742. cd "$PROJECT_DIR"
     
743. if [ -n "$NEW_HERMES_VERSION" ]; then
     
744.     log "临时指定 Hermes 版本为 $NEW_HERMES_VERSION"
     
745.     sed -i "s|\(hermes-agent-custom:\)[^ ]*|\1$NEW_HERMES_VERSION|g" "$COMPOSE_FILE"
     
746. fi
     
747. if [ -n "$NEW_HINDSIGHT_VERSION" ]; then
     
748.     log "临时指定 Hindsight 版本为 $NEW_HINDSIGHT_VERSION"
     
749.     sed -i "s|\(ghcr.io/vectorize-io/hindsight:\)[^ ]*|\1$NEW_HINDSIGHT_VERSION|g" "$COMPOSE_FILE"
     
750. fi
     
751. 
     
752. # 增强拉取函数
     
753. pull_image() {
     
754.     local img="$1"
     
755.     if docker pull "$img" 2>/dev/null; then return 0; fi
     
756.     if [[ "$img" == ghcr.io/* ]]; then
     
757.         local path="${img#ghcr.io/}"
     
758.         local tag="latest"
     
759.         [[ "$path" == *:* ]] && { tag="${path##*:}"; path="${path%:*}"; }
     
760.         for mirror in "${GHCR_MIRRORS[@]}"; do
     
761.             local mirror_img="${mirror}/${path}:${tag}"
     
762.             if docker pull "$mirror_img" 2>/dev/null; then
     
763.                 docker tag "$mirror_img" "$img"
     
764.                 return 0
     
765.             fi
     
766.         done
     
767.     fi
     
768.     return 1
     
769. }
     
770. 
     
771. log "拉取镜像（将根据 compose 中的标签拉取）..."
     
772. docker compose pull || {
     
773.     # 如果 compose pull 失败，则尝试逐个镜像手动拉取
     
774.     IMAGES=$(grep 'image:' "$COMPOSE_FILE" | awk '{print $2}' | sort -u)
     
775.     for img in $IMAGES; do
     
776.         [[ "$img" == *\$\{* ]] && continue
     
777.         for ((i=0; i<MAX_RETRIES; i++)); do
     
778.             if pull_image "$img"; then break; fi
     
779.             log "重试 $((i+1))/$MAX_RETRIES ..."
     
780.             sleep $RETRY_DELAY
     
781.         done
     
782.     done
     
783. }
     
784. 
     
785. log "重建容器..."
     
786. docker compose down
     
787. docker compose up -d --force-recreate
     
788. 
     
789. sleep 15
     
790. # 健康检查
     
791. curl -s http://127.0.0.1:8888/health | grep -q "healthy" && echo "✅ Hindsight OK" || echo "❌ Hindsight 异常"
     
792. docker ps | grep -q hermes && echo "✅ Hermes 运行中" || echo "❌ Hermes 未运行"
     
793. log "升级完成。"
     
794. echo "提示：如果刚才传入了临时版本号，请更新 compose 文件中的标签以保持与当前运行版本一致。"</code></pre>
     
795.   <p><code>chmod +x upgrade_v2.sh</code></p>
     
796. </div>
     
797. 
     
798. <h3>9.2 使用示例</h3>
     
799. <div class="card">
     
800.   <pre><code># 不传版本号：拉取 compose 中当前标签对应的最新镜像并升级（对 :latest 就是拉最新版）
     
801. ./upgrade_v2.sh
     
802. 
     
803. # 临时使用指定版本升级（可用于测试或回退）
     
804. ./upgrade_v2.sh v0.14.0 0.7
     
805. 
     
806. # 仅升级 Hermes 到指定版本
     
807. ./upgrade_v2.sh v0.14.0 ""
     
808. 
     
809. # 仅升级 Hindsight 到指定版本
     
810. ./upgrade_v2.sh "" 0.7</code></pre>
     
811.   <p><strong>注意：</strong>如果传入了版本号，脚本会临时修改 compose 文件，升级完成后建议你手动改回原来的标签（如 <code>:latest</code>）或锁定为新版本，避免下次误拉取。</p>
     
812. </div>
     
813. 
     
814. <div class="warning">
     
815.   <strong>离线备份方案：</strong>如果所有在线源失败，可在网络通畅的电脑上拉取镜像并保存为 tar，再导入 NAS：
     
816.   <pre><code># 在可上网电脑上
     
817. docker pull ghcr.io/vectorize-io/hindsight:latest
     
818. docker save -o hindsight-latest.tar ghcr.io/vectorize-io/hindsight:latest
     
819. # 传输到 NAS 后执行
     
820. docker load -i hindsight-latest.tar</code></pre>
     
821. </div>
     
822. 
     
823. <!-- 10. 常见问题排查 -->
     
824. <h2 id="troubleshoot">10. 常见问题排查</h2>
     
825. 
     
826. <div class="card">
     
827.   <h3>10.1 Hindsight 启动失败：<code>LLM API key is required</code></h3>
     
828.   <p><strong>原因</strong>：环境变量 <code>DEEPSEEK_API_KEY</code> 未正确传递。<br>
     
829.   <strong>解决</strong>：检查 <code>docker-compose.yml</code> 和 <code>.env</code> 文件，确保变量名完全一致（大小写敏感），并且 <code>DEEPSEEK_API_KEY</code> 同时提供给 Hermes 与 Hindsight。</p>
     
830. </div>
     
831. 
     
832. <div class="card">
     
833.   <h3>10.2 Hindsight <code>APIConnecti*</code></h3>
     
834.   <p><strong>原因</strong>：容器无法连接 LLM 服务器（DNS 或网络问题）。<br>
     
835.   <strong>解决</strong>：为 Hindsight 指定 DNS 或更换网络模式。检查 API 密钥和 Base URL 是否正确（示例中使用 <code>https://api.deepseek.com/v1</code>）。</p>
     
836. </div>
     
837. 
     
838. <div class="card">
     
839.   <h3>10.3 Hermes 报 <code>unable to open database file</code></h3>
     
840.   <p><strong>原因</strong>：<code>./data</code> 目录权限不是 1000:1000。<br>
     
841.   <strong>解决</strong>：<code>sudo chown -R 1000:1000 ./data</code> 后重启 Hermes。</p>
     
842. </div>
     
843. 
     
844. <div class="card">
     
845.   <h3>10.4 <code>reflect</code> 422 或 <code>retain</code> 超时</h3>
     
846.   <p><strong>原因</strong>：LLM 模型是纯 Embedding 模型，不支持 Chat。<br>
     
847.   <strong>解决</strong>：将 <code>HINDSIGHT_API_LLM_MODEL</code> 改为支持对话的模型（如 <code>deepseek-v4-pro</code>）。</p>
     
848. </div>
     
849. 
     
850. <div class="card">
     
851.   <h3>10.5 技能注册表为空或部分技能缺失</h3>
     
852.   <p><strong>原因</strong>：技能文件权限为 root 或 600，hermes 用户无法读取。<br>
     
853.   <strong>解决</strong>：<code>sudo chown -R 1000:1000 ./data/skills</code>，然后在 Hermes 终端执行 <code>rebuild</code>。</p>
     
854. </div>
     
855. 
     
856. <div class="card">
     
857.   <h3>10.6 PostgreSQL 锁文件错误</h3>
     
858.   <p><strong>原因</strong>：残留锁文件或数据损坏。<br>
     
859.   <strong>解决</strong>：备份后删除 <code>postgres_data</code> 目录重新初始化。</p>
     
860. </div>
     
861. 
     
862. <div class="card">
     
863.   <h3>10.7 升级后容器异常（latest 导致）</h3>
     
864.   <p><strong>原因</strong>：最新镜像可能存在兼容性问题或 Bug。<br>
     
865.   <strong>解决</strong>：快速回退到上一个稳定版本。假设你之前使用的是 <code>v0.13.0</code>，执行以下命令：</p>
     
866.   <pre><code>cd /opt/docker/hermes-hindsight
     
867. # 修改 docker-compose.yml 中的 latest 为之前的稳定版本，或使用升级脚本指定版本：
     
868. ./upgrade_v2.sh v0.13.0 0.6
     
869. # 然后确认服务正常后，可考虑将 compose 文件中的标签也改回稳定版本</code></pre>
     
870. </div>
     
871. 
     
872. <!-- 11. 历史故障修复记录 -->
     
873. <h2 id="history">11. 附录：所有历史故障修复记录</h2>
     
874. <div class="table-wrap">
     
875.   <table>
     
876.     <tr><th>症状</th><th>根因</th><th>修复</th></tr>
     
877.     <tr><td>ModuleNotFoundError: hindsight_client</td><td>插件需要该包但未安装，venv 无写权限</td><td>start-hermes.sh 自动安装 + PYTHONPATH</td></tr>
     
878.     <tr><td>技能权限拒绝</td><td>文件 root:root 600</td><td>宿主机 chown 1000:1000</td></tr>
     
879.     <tr><td>Kanban 数据库无法打开</td><td>数据目录属主错误</td><td>chown 1000:1000</td></tr>
     
880.     <tr><td>reflect 422、retain 超时</td><td>LLM 误用 Embedding 模型</td><td>改用 chat 模型（如 deepseek-v4-pro）</td></tr>
     
881.     <tr><td>LLM API key required</td><td>环境变量名错误或缺失</td><td>统一使用 DEEPSEEK_API_KEY</td></tr>
     
882.     <tr><td>Invalid provider: openai_compatible</td><td>不支持该 provider 名</td><td>改用 openai，通过 base_url 适配</td></tr>
     
883.     <tr><td>镜像拉取超时</td><td>国内无法直接访问 ghcr.io/Docker Hub</td><td>国内镜像加速 / 离线导入</td></tr>
     
884.     <tr><td>PostgreSQL 锁文件</td><td>异常关闭残留</td><td>删除锁文件或数据目录重建</td></tr>
     
885.     <tr><td>CORS 错误</td><td>前端请求被拒</td><td>配置 HINDSIGHT_CORS_ORIGINS</td></tr>
     
886.     <tr><td>升级后配置丢失</td><td>未挂载卷或权限错乱</td><td>确保挂载并 chown 权限</td></tr>
     
887.     <tr><td>latest 版本启动异常</td><td>最新镜像存在回归问题</td><td>回退至上一稳定版本（见升级章节）</td></tr>
     
888.   </table>
     
889. </div>
     
890. 
     
891. <p style="text-align:center; margin-top:3rem; color:#64748b;">— 本指南已涵盖从初始部署到长期维护的全部经验，祝你使用愉快！ —</p>
     
892. </div>
     
893. </body>
     
894. </html>
     
895. HTMLEOF
     
896. 
     
897. # 返回上层目录并打包
     
898. cd ..
     
899. tar -czf hermes-hindsight-deploy.tar.gz "$PACKAGE_DIR"
     
900. rm -rf "$PACKAGE_DIR"
     
901. 
     
902. echo "✅ 压缩包已生成：hermes-hindsight-deploy.tar.gz"
     
903. echo "请将其下载后解压使用：tar -xzf hermes-hindsight-deploy.tar.gz"

复制代码

这是我自己写的，第一次用论坛的编辑器，不太会操作，我再搞个简单的。请看下文：

学区房

1、SSH连接。2、提权root。3、直接把代码复制粘贴到SSH对话框里面按回车就可以了。4、直接跳到原方案第4步

1. # Hermes Agent + Hindsight 部署配置（修复版，已适配 DeepSeek）
   
2. services:
   
3.   # =================== Hermes Agent ===================
   
4.   hermes:
   
5.     image: hermes-agent-custom:latest    # 最新版（如要锁定版本，替换为 :v0.13.0 等）
   
6.     container_name: hermes               # 可改为你喜欢的名称
   
7.     restart: unless-stopped
   
8.     network_mode: host
   
9.     dns:
   
10.       - 114.114.114.114
    
11.       - 223.5.5.5
    
12.     stdin_open: true
    
13.     tty: true
    
14.     user: "1000:1000"                    # 必须与宿主机数据目录属主一致
    
15.     volumes:
    
16.       - ./data:/opt/data
    
17.       - ./start-hermes.sh:/opt/hermes/start-hermes.sh:ro
    
18.     environment:
    
19.       - TZ=Asia/Shanghai
    
20.       - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
    
21.       - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
    
22.       - DEEPSEEK_MODEL=deepseek-v4-pro
    
23.       - PYTHONPATH=/opt/data/.python_packages
    
24.       - HERMES_POST_START=/bin/bash /opt/hermes/start-hermes.sh
    
25.     deploy:
    
26.       resources:
    
27.         limits:
    
28.           memory: 4G
    
29.           cpus: "2.0"
    
30. 
    
31.   # =================== Hermes Dashboard ===================
    
32.   hermes-dashboard:
    
33.     image: hermes-agent-custom:latest    # 与 hermes 镜像保持一致
    
34.     container_name: hermes-dashboard     # 可改为你喜欢的名称
    
35.     restart: unless-stopped
    
36.     command: dashboard --host 0.0.0.0 --insecure
    
37.     network_mode: host
    
38.     user: "1000:1000"
    
39.     volumes:
    
40.       - ./data:/opt/data
    
41.     environment:
    
42.       - GATEWAY_HEALTH_URL=http://127.0.0.1:8642
    
43.       - TZ=Asia/Shanghai
    
44.       - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
    
45.       - DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
    
46.       - DEEPSEEK_MODEL=deepseek-v4-pro
    
47.     depends_on:
    
48.       - hermes
    
49.     deploy:
    
50.       resources:
    
51.         limits:
    
52.           memory: 512M
    
53.           cpus: "0.5"
    
54. 
    
55.   # =================== Hindsight 记忆大脑 ===================
    
56.   hindsight:
    
57.     image: ghcr.io/vectorize-io/hindsight:latest   # 最新版（如要锁定版本，替换为 :0.6 等）
    
58.     container_name: hindsight                       # 可改为你喜欢的名称
    
59.     restart: unless-stopped
    
60.     networks:
    
61.       - internal
    
62.     ports:
    
63.       - "127.0.0.1:8888:8888"
    
64.       - "127.0.0.1:9999:9999"
    
65.     environment:
    
66.       # 数据库（外部 PostgreSQL）
    
67.       HINDSIGHT_DB_HOST: hindsight-postgres
    
68.       HINDSIGHT_DB_PORT: "5432"
    
69.       HINDSIGHT_DB_NAME: hindsight
    
70.       HINDSIGHT_DB_USER: hindsight
    
71.       HINDSIGHT_DB_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}
    
72.       HINDSIGHT_DB_BACKEND: external
    
73.       # LLM 配置（使用 DeepSeek）
    
74.       HINDSIGHT_API_LLM_PROVIDER: openai
    
75.       HINDSIGHT_API_LLM_API_KEY: ${DEEPSEEK_API_KEY}
    
76.       HINDSIGHT_API_LLM_MODEL: deepseek-v4-pro
    
77.       HINDSIGHT_API_LLM_BASE_URL: https://api.deepseek.com/v1
    
78.       # Web 界面
    
79.       API_BASE_URL: http://127.0.0.1:8888
    
80.       HINDSIGHT_CORS_ORIGINS: "http://localhost:9999,http://127.0.0.1:9999"
    
81.       HINDSIGHT_API_LISTEN_HOST: 0.0.0.0
    
82.       # 模型下载加速
    
83.       HF_ENDPOINT: https://hf-mirror.com
    
84.     volumes:
    
85.       - ./hindsight_data:/home/hindsight/.pg0
    
86.     depends_on:
    
87.       - hindsight-postgres
    
88. 
    
89.   # =================== PostgreSQL 数据库 ===================
    
90.   hindsight-postgres:
    
91.     image: pgvector/pgvector:pg16
    
92.     container_name: hindsight-postgres    # 可改为你喜欢的名称
    
93.     restart: unless-stopped
    
94.     networks:
    
95.       - internal
    
96.     environment:
    
97.       POSTGRES_USER: hindsight
    
98.       POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-ChangeMe123!}
    
99.       POSTGRES_DB: hindsight
    
100.     volumes:
     
101.       - ./postgres_data:/var/lib/postgresql/data
     
102. 
     
103. networks:
     
104.   internal:
     
105.     driver: bridge

复制代码

1. 
   

复制代码

lixilu

学区房 发表于 2026-5-13 14:03
1、SSH连接。2、提权root。3、直接把代码复制粘贴到SSH对话框里面按回车就可以了。4、直接跳到原方案第4步
...

** 啊~~~谢谢分享

hj4156

我让小龙虾帮我装了一个

世时依

作为深度参与 Hermes Agent 项目的玩家，看到这帖子必须冒个泡 👋

这个项目的设计理念很有趣，本地智能体操作系统的方向确实值得社区一起探索。有兴趣的朋友可以试试 Docker 部署，配置不算复杂，跑起来之后能感受到 AI Agent 在 NAS 场景下的潜力。

有什么坑或者心得欢迎一起交流～ 💪

学区房

世时依 发表于 2026-5-18 19:26
作为深度参与 Hermes Agent 项目的玩家，看到这帖子必须冒个泡 👋

这个项目的设计理念很有趣，本地智能体 ...

个人感觉楼主的帖子介绍的不是很清楚，对小白也不是很友好

学区房

hj4156 发表于 2026-5-17 21:43
我让小龙虾帮我装了一个

都这么过来的