Docker Compose部署Hermes Agent + 飞书 + Hermes DashBoard——最详细傻瓜式步骤

关于Hermes Agent的介绍见百度百科，这里不介绍了：https://baike.baidu.com/item/Hermes%20Agent/67487182

这里说一下爱马仕的优点，相比较claude code等无状态的agent，爱马仕是有“记忆的”，是“capture a trajectory“，是“Next time：faster，cleaner，smarter”的。

所有操作均参照Hermes Agent官网，https://hermes-agent.nousresearch.com/docs/zh-Hans/

所有操作均在Ubuntu服务器 `11.22.33.66` 上执行，工作目录为 abc。

---

### 第一步：SSH 登录服务器

```bash
ssh abc@11.22.33.66
cd /home/abc
```

---

### 第二步：确认 Docker 和 Docker Compose 已安装

> 📎 参考：https://docs.docker.com/engine/install/ubuntu/

```bash
docker --version
docker compose version
```

如果未安装：
```bash
# 安装 Docker
sudo apt update
sudo apt install -y docker.io docker-compose-plugin

# 启动 Docker 并设置开机自启
sudo systemctl enable docker && sudo systemctl start docker

# 让当前用户免 sudo 使用 docker
sudo usermod -aG docker abc

# 退出重新登录使权限生效
exit
```

重新登录：
```bash
ssh abc@11.22.33.66
cd /home/abc
```

---

### 第三步：创建 Hermes 数据目录

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/docker#持久化卷

```bash
mkdir -p /home/abc/.hermes
```

这个目录将存放所有 Hermes 数据（配置、API Key、会话、记忆、技能等），映射到容器内的 `/opt/data`。

---

### 第四步：运行设置向导（首次配置 LLM 提供商）

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/docker#快速开始

```bash
docker run -it --rm \
-v /home/abc/.hermes:/opt/data \
nousresearch/hermes-agent setup
```

**向导会依次提示你：**

1. 选择 LLM 提供商（推荐选 `OpenRouter` 或 `Nous Portal`）
2. 输入对应的 API Key
3. 选择默认模型

> 📎 Nous Portal 一站式方案参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/getting-started/installation#快速安装
>
> 如果选 Nous Portal，向导中会执行等效于 `hermes setup --portal` 的流程

完成后配置写入 `/home/abc/.hermes/.env`，只需执行一次。

---

### 第五步：在飞书开发者控制台创建机器人应用

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/messaging/feishu#第一步创建飞书--lark-应用

#### 5.1 打开飞书开发者控制台

浏览器打开：**https://open.feishu.cn/**

用你的飞书账号登录。

#### 5.2 创建应用

1. 点击页面上的 **「创建企业自建应用」**
2. 应用名称填：`Hermes Agent`（或你喜欢的名字）
3. 应用描述随便写
4. 点击 **「确定」**

#### 5.3 开启机器人能力

1. 左侧菜单 → **「应用能力」** → **「机器人」**
2. 点击 **「启用」**

#### 5.4 记录凭证

1. 左侧菜单 → **「凭证与基础信息」**
2. 复制记录以下两个值（后面要用）：
- **App ID**：格式类似 `cli_a5xxxxxxxxxxxxx`
- **App Secret**：一串字母数字

#### 5.5 配置权限

> 📎 参考：https://hermes-agent.nousresearch.com/docs/user-guide/messaging/feishu#configure-permissions

左侧菜单 → **「权限管理」**，搜索并添加以下权限：

| 权限标识 | 说明 |
|---------|------|
| `im:message` | 接收和读取消息 |
| `im:message:send_as_bot` | 以机器人身份发消息 |
| `im:resource` | 访问图片/文件/音频 |
| `im:chat` | 访问群聊元数据 |
| `im:chat:readonly` | 读取群聊列表和成员 |

可选（推荐也加上）：

| 权限标识 | 说明 |
|---------|------|
| `im:message.reactions:readonly` | 接收表情回应事件 |
| `contact:user.id:readonly` | 解析用户 ID |

#### 5.6 配置事件订阅

> 📎 参考：https://hermes-agent.nousresearch.com/docs/user-guide/messaging/feishu#configure-events

1. 左侧菜单 → **「事件与回调」**（有些版本叫「事件订阅」）
2. 连接方式选择：**「长连接（WebSocket）」** ← 这很重要！
3. 在「事件配置」中，点击添加事件，搜索并订阅：
- **`im.message.receive_v1`** — 接收消息（必选）

#### 5.7 发布应用版本

> 📎 参考：https://hermes-agent.nousresearch.com/docs/user-guide/messaging/feishu#publish-the-app

1. 左侧菜单 → **「版本管理与发布」**
2. 点击 **「创建版本」**
3. 填写版本号（如 `1.0.0`）和更新说明
4. 点击 **「发布」**
5. **等待企业管理员审批通过**（权限在审批通过前不生效）

---

### 第六步：配置 Hermes 对接飞书（交互式）

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/messaging/feishu#第三步配置-hermes

```bash
docker run -it --rm \
-v /home/abc/.hermes:/opt/data \
nousresearch/hermes-agent gateway setup
```

在菜单中：
1. 选择 **「飞书 / Lark」**（或 `Feishu / Lark`）
2. 输入你在 5.4 中记录的 **App ID**
3. 输入你在 5.4 中记录的 **App Secret**
4. 域名选 **`feishu`**（中国版飞书）
5. 连接模式选 **`websocket`**（推荐，无需公网 IP）

配置完成后会自动写入 `/home/abc/.hermes/.env`。

---

### 第六步（备选）：手动写入飞书配置

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/messaging/feishu#方式-b手动配置

如果交互式向导有问题，手动编辑：

```bash
nano /home/abc/.hermes/.env
```

在文件末尾追加以下内容（替换实际值）：

```
FEISHU_APP_ID=cli_你的实际AppID
FEISHU_APP_SECRET=你的实际AppSecret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
```

保存：`Ctrl+X` → `Y` → `Enter`

---

### 第七步：创建 docker-compose.yaml 文件

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/docker#docker-compose-示例

```bash
nano /home/abc/docker-compose.yaml
```

粘贴以下内容：

```yaml
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
ports:
- "26429:26429"
volumes:
- /home/abc/.hermes:/opt/data
deploy:
resources:
limits:
memory: 4G
cpus: "2.0"
```

保存：`Ctrl+X` → `Y` → `Enter`

**文件路径汇总：**

| 文件 | 路径 | 用途 |
|------|------|------|
| docker-compose.yaml | `/home/abc/docker-compose.yaml` | Docker Compose 编排文件 |
| .env (Hermes) | `/home/abc/.hermes/.env` | API Key + 飞书凭证 |
| config.yaml | `/home/abc/.hermes/config.yaml` | Hermes 配置（自动生成） |
| sessions/ | `/home/abc/.hermes/sessions/` | 对话历史 |
| memories/ | `/home/abc/.hermes/memories/` | 持久记忆 |
| skills/ | `/home/abc/.hermes/skills/` | 已安装技能 |
| logs/ | `/home/abc/.hermes/logs/` | 运行日志 |

---

### 第八步：启动 Hermes Agent

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/docker#以-gateway-模式运行

```bash
cd /home/abc
docker compose up -d
```

输出类似：
```
[+] Running 1/1
✔ Container hermes Started
```

---

### 第九步：验证容器运行状态

```bash
# 确认容器在运行
docker ps | grep hermes

# 查看实时日志（确认飞书 WebSocket 连接成功）
docker compose logs -f
```

你应该在日志中看到类似以下内容：
```
Feishu WebSocket connected
Gateway started successfully
```

按 `Ctrl+C` 退出日志查看（容器继续运行）。

---

### 第十步：在飞书中测试机器人

1. 打开飞书客户端（手机或电脑）
2. 搜索你在第五步创建的机器人名字（如 `Hermes Agent`）
3. 点击进入私聊
4. 发送：`你好`
5. **机器人回复** → 部署成功！

---

## 日常运维命令速查

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/docker#升级

| 操作 | 命令 | 执行目录 |
|------|------|---------|
| 启动 | `docker compose up -d` | abc |
| 停止 | `docker compose down` | abc |
| 重启 | `docker compose restart` | abc |
| 查看日志 | `docker compose logs -f` | abc |
| 查看最近50行日志 | `docker logs --tail 50 hermes` | 任意 |
| 升级到最新版 | `docker compose pull && docker compose up -d` | abc |
| 进入容器交互聊天 | `docker run -it --rm -v /home/abc/.hermes:/opt/data nousresearch/hermes-agent` | 任意 |
| 重新配置飞书 | `docker run -it --rm -v /home/abc/.hermes:/opt/data nousresearch/hermes-agent gateway setup` | 任意 |
| 查看资源占用 | `docker stats hermes` | 任意 |
| 检查版本 | `docker run -it --rm nousresearch/hermes-agent:latest version` | 任意 |

---

## 故障排查

> 📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/docker#故障排查
> 📎 飞书故障排查：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/messaging/feishu#故障排查

| 问题 | 解决方案 |
|------|---------|
| 容器立即退出 | `docker logs hermes` 查原因；通常是 `.env` 未正确配置 |
| Permission denied | `chmod -R 755 /home/abc/.hermes` |
| 飞书机器人不响应 | 1) 确认应用已发布且审批通过 2) 确认 App ID/Secret 正确 3) 确认订阅了 `im.message.receive_v1` 事件 |
| 群聊中不响应 | 飞书群聊中必须 @机器人才触发回复（[文档](https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/messaging/feishu#hermes-的行为方式)） |
| WebSocket 连不上 | 确认服务器能访问外网 `curl -I https://open.feishu.cn` |
| `lark-oapi not installed` | 不应出现在官方 Docker 镜像中；确认用的是 `nousresearch/hermes-agent` 镜像 |
| 端口冲突 | 修改 `docker-compose.yaml` 中的 `"8642:8642"` 为其他端口如 `"9642:8642"` |

---

## 完整文件清单

执行完以上步骤后，你的目录结构为：

```
/home/abc/
├── docker-compose.yaml ← 你手动创建的
└── .hermes/ ← Hermes 数据目录
├── .env ← API Key + 飞书凭证（setup 向导自动写入）
├── config.yaml ← Hermes 配置（自动生成）
├── SOUL.md ← Agent 个性定义（自动生成）
├── sessions/ ← 对话历史
├── memories/ ← 持久记忆
├── skills/ ← 技能
├── logs/ ← 日志
└── cron/ ← 定时任务
```

上面做完，Hermes Agent应该是完成了

下面开始部署Hermes Dashboard 的完整步骤。📎 参考：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/docker#运行-dashboard

1、修改docker-compose.yaml，替换为如下字段

新增内容说明：

配置项	作用
`26430:6430` 我把上面的29119:9119换掉了	将容器内 6430端口映射到宿主机 26430（通过浏览器访问）
`HERMES_DASHBOARD=1`	启用 Dashboard 服务
`HERMES_DASHBOARD_HOST=0.0.0.0`	Dashboard 绑定所有网卡（否则只能容器内访问）
`HERMES_DASHBOARD_PORT=6430`	Dashboard 监听端口
`HERMES_DASHBOARD_INSECURE=1`	跳过 OAuth 认证（内网使用可以这样设，外网不建议）

HERMES_DASHBOARD_INSECURE=1 会暴露 API Key 和会话数据。仅适合内网/VPN 环境。如果服务器暴露在公网，应配置用户名密码认证（见下方可选步骤5）。

2、重启容器

cd /home/abc
docker compose down
docker compose up -d

3、确认dashboard启动成功 docker compose logs --tail 30 | grep -i dashboard 应看到类似Hermes Web UI → http://0.0.0.0:6430

4、浏览器访问dashboard http://10.99.33.60:26430 你应该能看到 Hermes Dashboard 的 Web 界面，可以查看会话、任务、指标等。

5、（可选）配置用户名密码认证📎 参考：https://hermes-agent.nousresearch.com/docs/user-guide/docker#运行-dashboard

如果担心安全问题，可以用 Basic Auth 替代 INSECURE 模式。修改 docker-compose.yaml 的 environment 部分：
把 HERMES_DASHBOARD_INSECURE=1 那行删掉，换成下面三行。

- HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin

- HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=你设置的密码

- HERMES_DASHBOARD_BASIC_AUTH_SECRET=随机字符串用于session加密（可以使用openssl rand -hex 32获取）

然后重启 docker compose down && docker compose up -d，访问 Dashboard 时会弹出登录框，输入你设置的用户名密码即可。

故障排查

问题	解决方案
浏览器打不开	确认防火墙放行了 29119 端口：`sudo ufw allow 29119` 或检查安全组
Dashboard 没启动	`docker compose logs` 查看是否有报错
端口冲突	把 `29119` 改成其他未被占用的端口

=============================================================================================================

Q&A：

上述步骤完成后，运行docker compose报Permission denied，sudo 755 .hermes只能临时解决，重启后.hermes文件夹权限又变回无权限且所属变回10000了？

这是因为容器每次启动时，入口脚本会自动将 /opt/data 的所有权修改为容器内 hermes 用户（UID 10000）。这是官方镜像的设计行为。
在 docker-compose.yaml 中设置 HERMES_UID 和 HERMES_GID 为你宿主机用户的 UID/GID：id -u # 应该输出 1000 之类的数字 id -g
然后修改docker-compose.yaml，添加
environment:
- HERMES_UID=1000
- HERMES_GID=1000
把 1000 替换为你实际的 id -u 和 id -g 输出值。然后重启，
sudo chown -R $(id -u):$(id -g) /home/abc/.hermes
docker compose down
docker compose up -d
------------------------------------------------------------------------------------------------------------------------------------------------------------------

由于前面配置时，设置的是Use DM pairing approval，即第一次有人私信hermes飞书机器人时，需要手动批准才能对话，所以当在飞书给机器人发消息时，会报错，怎么解决？

有两种方法，分别是修改.hermes/.env，将log（docker compose logs -f）中显示的id号加到FEISHU_ALLOWED_USERS字段中，保存后重启docker compose restart；另外直接执行飞书机器人报的命令

这里需要注意，由于这是通过docker compose方式运行的hermes agent，所以服务器上是没有安装hermes的，所以如果在服务器pc上执行hermes，是会报错的。该命令应当在容器内执行，并且要修改一下为：
/opt/hermes/.venv/bin/hermes pairing approve feishu 2T99xxxxx。它的作用是将你的飞书id标记为"已批准"，写入配对记录中。之后你再给机器人发消息就不会被拒绝了。本质上等同于在白名单中添加了你的用户，但是走的是 pairing 审批机制而非 FEISHU_ALLOWED_USERS 环境变量。两种方式二选一都可以。所以如果你查看.hermes/.env的FEISHU_ALLOWED_USERS字段，是没有值的。

----------------------------------------------------------------------------------------------------------------------------------------------------------------------

上面提到的飞书id，为什么和我通过飞书官方API获取的open_id不一样？

这是因为飞书的 open_id 是与应用绑定的——同一个用户在不同应用中会有不同的 open_id。你手动获取的 open_id 可能是通过另一个应用或 API 调试工具得到的，和 Hermes 这个应用看到的不一样。使用上述日志打印的即可。

后面我会在工作中实际应用该hermes agent飞书机器人，会记录在新开的文档中。

posted @ 2026-06-08 14:51 中登不太冷2 阅读(306) 评论(0) 收藏举报

刷新页面返回顶部

snbtl

Docker Compose部署Hermes Agent + 飞书 + Hermes DashBoard——最详细傻瓜式步骤

故障排查

公告