Hermes Agent Docker 部署完整指南

Hermes Agent Docker 部署完整指南

最后更新：2026-05-29  适用版本：v2026.5.16（推荐）  NAS 环境：绿联 UGOS / 群晖 / 威联通

---

目录

• 1. 快速开始
• 2. 环境准备
• 3. 完整配置详解
• 4. 版本对比
• 5. 常见问题排查
• 6. 进阶配置
• 7. 附录
  
  

---

1. 快速开始

1.1 为什么推荐 v2026.5.16

从 v14 升级到最新版（s6-overlay）后，用户普遍遇到以下问题：

[td]

问题	v14	v2026.5.16	latest (s6-overlay)
容器启动	✅	✅	❌ (权限问题)
Gateway 自动启动	✅	✅	❌ (状态管理)
WebSocket 连接	✅	✅	❌ (403 Forbidden)
配置复杂度	简单	简单	复杂

结论：v2026.5.16 使用 tini init，兼容性最好，无需复杂的权限修复和状态管理。

1.2 最简配置

services:
  hermes:
    image: nousresearch/hermes-agent:2026.5.16
    restart: always
    ports:
      - "8642:8642"
      - "9119:9119"
    volumes:
      - /volume1/docker/hermes_agent/data:/opt/data
      - "/volume1/STM共享文件/Agent Share Space:/mnt/Agent Share Space"
    environment:
      TZ: Asia/Shanghai
      HERMES_DASHBOARD: 1
      HERMES_DASHBOARD_TUI: 1
    shm_size: 1g
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"1.3 从 v14 升级步骤

# 1. 停止当前容器
docker compose down
​
# 2. 修改 docker-compose.yml 中的镜像版本
# image: nousresearch/hermes-agent:latest
# 改为
image: nousresearch/hermes-agent:2026.5.16
​
# 3. 重启容器
docker compose up -d
​
# 4. 查看日志确认启动成功
docker compose logs -f

注意：数据目录 /opt/data 保持不变，所有配置、会话、记忆、技能都会保留。

---

2. 环境准备

2.1 绿联 NAS 特殊说明

绿联 UGOS 使用 ACL（访问控制列表） 管理权限，这会导致：

• 传统权限位显示为 000：
  $ ls -l /volume1/docker/hermes_agent/data
  d---------+  2 1001  10  4096 May 29 10:32 cache
  -rw-r-----   1 1001  10  14483 May 29 10:33 config.yaml
  
  • ----------+ 表示有 ACL，但传统权限位为 000
  • + 号表示有扩展 ACL 条目
    
    
• Docker 不识别 ACL：
  
  
  • 容器内只能看到传统权限位（000）
  • 即使你有读写权限，容器内也无法访问
    
    
• 解决方案：
  # 修复目录权限
  sudo find /volume1/docker/hermes_agent/data -type d -exec chmod 755 {} \;
  ​
  # 修复文件权限
  sudo find /volume1/docker/hermes_agent/data -type f -exec chmod 644 {} \;
  ​
  # 确保所有权正确
  sudo chown -R 1001:10 /volume1/docker/hermes_agent/data
  

2.2 权限检查命令

# 检查传统权限位
ls -ln /volume1/docker/hermes_agent/data
​
# 检查 ACL
getfacl /volume1/docker/hermes_agent/data
​
# 快速判断（输出 755/644 表示正常，000 表示需要修复）
stat -c '%a' /volume1/docker/hermes_agent/data2.3 Docker 环境验证

# 检查 Docker 是否正常
docker info
​
# 检查 Docker Compose
docker compose version
​
# 检查端口占用
netstat -tlnp | grep -E "8642|9119"

---

3. 完整配置详解

3.1 Docker Compose 完整示例

services:
  hermes:
    image: nousresearch/hermes-agent:2026.5.16
    restart: always
    container_name: hermes
    ports:
      - "8642:8642"    # Gateway API
      - "9119:9119"    # Dashboard Web UI
    volumes:
      - /volume1/docker/hermes_agent/data:/opt/data
      - "/volume1/STM共享文件/Agent Share Space:/mnt/Agent Share Space"
    environment:
      TZ: Asia/Shanghai
      HERMES_DASHBOARD: 1
      HERMES_DASHBOARD_TUI: 1
    shm_size: 1g
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"3.2 环境变量说明

[td]

环境变量	说明	默认值	是否必需
TZ	时区设置	UTC	否
HERMES_DASHBOARD	启用 Dashboard	0	否
HERMES_DASHBOARD_TUI	启用浏览器内 Chat 标签页	0	否

注意：v2026.5.16 版本使用 tini init，无需以下环境变量：

• HERMES_UID / HERMES_GID
• HERMES_DASHBOARD_HOST
• HERMES_DASHBOARD_INSECURE
  
  

3.3 卷挂载说明

[td]

宿主机路径	容器路径	说明
/volume1/docker/hermes_agent/data	/opt/data	核心数据目录（必须）
/volume1/STM共享文件/Agent Share Space	/mnt/Agent Share Space	共享文件目录（可选）

/opt/data 目录结构：

/opt/data/
├── .env              # API 密钥
├── config.yaml       # 配置文件
├── SOUL.md           # Agent 人格
├── sessions/         # 会话历史
├── memories/         # 记忆存储
├── skills/           # 已安装技能
├── cron/             # 定时任务
├── logs/             # 运行日志
└── home/             # 工具子进程 HOME

---

4. 版本对比

4.1 版本特性对比

[td]

特性	v14	v2026.5.16	latest (s6-overlay)
Init 系统	tini	tini	s6-overlay
Gateway 启动方式	CMD 直接启动	CMD 直接启动	s6 supervised
状态管理	无	无	gateway_state.json
权限管理	简单	简单	复杂 (UID remap)
Dashboard	✅	✅	✅
WebSocket	✅	✅	❌ (403)
配置复杂度	⭐	⭐	⭐⭐⭐⭐

4.2 兼容性对比

[td]

NAS 品牌	v14	v2026.5.16	latest (s6-overlay)
群晖	✅	✅	⚠️ (需 chmod)
威联通	✅	✅	⚠️ (需 chmod)
绿联	✅	✅	❌ (ACL 问题)
极空间	✅	✅	✅
铁威马	✅	✅	✅

4.3 推荐版本选择

[td]

场景	推荐版本	理由
从 v14 升级	v2026.5.16	兼容性最好，零配置
全新安装	v2026.5.16	稳定可靠
追新测试	latest	了解新特性（有风险）
生产环境	v2026.5.16	避免已知问题

---

5. 常见问题排查

5.1 问题 1：容器无法启动

现象：

PermissionError: [Errno 13] Permission denied: '/opt/data/.managed'

原因：

• 绿联 NAS 的 ACL 导致传统权限位为 000
• Docker 容器无法读写
  
  

解决：

# 在 NAS SSH 中执行
sudo find /volume1/docker/hermes_agent/data -type d -exec chmod 755 {} \;
sudo find /volume1/docker/hermes_agent/data -type f -exec chmod 644 {} \;
sudo chown -R 1001:10 /volume1/docker/hermes_agent/data5.2 问题 2：Gateway 不自动启动

现象：

• 容器重启后，dashboard 正常运行
• 但 gateway 服务没有启动
  
  

原因：

• s6-overlay 的状态管理机制
• gateway_state.json 状态不是 running
  
  

解决：

# 进入容器手动启动
docker exec hermes-1 hermes gateway start
​
# 或直接修改状态文件
echo '{"state": "running"}' | sudo tee /volume1/docker/hermes_agent/data/gateway_state.json

注意：v2026.5.16 版本不会遇到此问题，因为使用 CMD 直接启动。

5.3 问题 3：WebSocket 403

现象：

WebSocket connection to 'ws://192.168.31.93:9119/api/ws?token=...' failed
WebSocket connection to 'http://192.168.31.93:9119/api/events?token=...' failed

原因：

• s6-overlay 的 WebSocket 端点有独立的 token 验证
• --insecure 模式不影响 WebSocket
  
  

解决：

• SSH 端口转发（推荐）：
  ssh -L 9119:127.0.0.1:9119 [email protected]
  然后访问 http://localhost:9119
• 使用 OAuth 认证：
  docker exec -it hermes-1 hermes setup --portal
• 接受现状：WebSocket 只影响 Chat 标签页，其他功能正常
  
  

注意：v2026.5.16 版本不会遇到此问题。

5.4 问题 4：Dashboard 访问异常

现象：

• 页面无法加载
• API 返回 403
  
  

排查步骤：

# 检查容器是否运行
docker ps | grep hermes
​
# 检查端口监听
docker exec hermes-1 ss -tlnp | grep 9119
​
# 检查日志
docker logs hermes-1 | grep -i "dashboard\|error"

---

6. 进阶配置

6.1 OAuth 认证

适用场景：需要远程访问 Dashboard 且希望有认证保护

步骤：

• 注册 Nous Portal 账号：https://portal.nousresearch.com
• 在容器中运行：
  docker exec -it hermes-1 hermes setup --portal
• 按提示完成 OAuth 流程
  
  

配置：

environment:
  # 去掉 HERMES_DASHBOARD_INSECURE
  # HERMES_DASHBOARD_OAUTH_CLIENT_ID 会自动设置6.2 WebSocket 绕过（SSH 端口转发）

适用场景：不想配置 OAuth，但需要 WebSocket 功能

步骤：

# Windows PowerShell
ssh -L 9119:127.0.0.1:9119 [email protected]

然后访问 http://localhost:9119，Dashboard 认为是 loopback 访问，WebSocket 正常工作。

6.3 自定义 entrypoint（仅限 s6-overlay）

适用场景：必须使用 latest 版本

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    restart: always
    user: root
    entrypoint: |
      bash -c "
      chmod -R u+rwX,g+rX,o+rX /opt/data
      exec /init
      "
    command: gateway run
    environment:
      HERMES_DASHBOARD: 1
      HERMES_DASHBOARD_TUI: 1
      HERMES_DASHBOARD_HOST: "0.0.0.0"
      HERMES_DASHBOARD_INSECURE: 1
      HERMES_UID: "1001"
      HERMES_GID: "10"

---

7. 附录

7.1 GitHub Issues

[td]

Issue	标题	状态
#9153	Docker image missing 'dashboard' command	Closed
#XXXX	Gateway not auto-starting after upgrade	Open
#XXXX	Dashboard WebSocket 403 with --insecure	Open

7.2 命令速查

[td]

命令	说明
docker compose up -d	启动容器
docker compose down	停止容器
docker compose logs -f	查看日志
docker exec hermes-1 hermes status	查看状态
docker exec hermes-1 hermes gateway start	启动 gateway
docker exec hermes-1 hermes setup --portal	配置 OAuth

7.3 环境变量参考

[td]

变量	v2026.5.16	latest (s6-overlay)
TZ	✅	✅
HERMES_DASHBOARD	✅	✅
HERMES_DASHBOARD_TUI	✅	✅
HERMES_UID	❌	✅
HERMES_GID	❌	✅
HERMES_DASHBOARD_HOST	❌	✅
HERMES_DASHBOARD_INSECURE	❌	✅

---

参考链接

• Hermes Agent Docker 文档
• Hermes Agent Web Dashboard
• Nous Portal 集成
• GitHub Issues
• v2026.5.16 Release
  
  

6666呀

学到了

现在加载有时间  的版本无法安装，怎么回事？请帮忙看看，谢谢

O8n273 发表于 2026-6-13 10:00
现在加载有时间  的版本无法安装，怎么回事？请帮忙看看，谢谢

不太明白你的问题