🚀 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，重新保存后覆盖上传。
| 
