服务器 Docker 部署 Hermes Agent → 飞书（零端口暴露）

一、环境准备：Docker 安装与镜像加速

如果你的服务器还没装 Docker，先安装。已装则跳过。

# Ubuntu/Debian 安装 Docker
sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker

# 验证
docker version

国内服务器必须配置镜像加速，否则拉取官方镜像极慢或失败：

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.run",
    "https://docker.m.daocloud.io"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

国内可用加速源：docker.1ms.run、docker.xuanyuan.run 等

---

二、拉取 Hermes Agent 镜像

# 通过国内加速源拉取（推荐）
docker pull docker.1ms.run/nousresearch/hermes-agent:latest

# 验证镜像
docker images | grep hermes-agent

如果加速源失效，可尝试其他镜像站：

docker pull docker.xuanyuan.run/nousresearch/hermes-agent:latest

---

三、创建数据目录并开放权限

这是最关键的一步，很多配置写不进去就是因为权限问题。

# 创建持久化目录
sudo mkdir -p /mnt/docker/hermes-agent

# 权限开到最大，确保容器内能读写配置
sudo chmod -R 777 /mnt/docker/hermes-agent

# 清理可能存在的旧容器
docker rm -f hermes-agent 2>/dev/null

---

四、进入容器进行交互式配置（不开放端口）

核心思路 ：用 --entrypoint /bin/bash 绕过默认 entrypoint，手动进入容器内部执行配置，避免 stdin 被错误解析为 chat 消息。

docker run -it --name hermes-agent \
  -v /mnt/docker/hermes-agent:/opt/data \
  --entrypoint /bin/bash \
  docker.1ms.run/nousresearch/hermes-agent:latest

进入容器后，依次执行：

# 1. 激活虚拟环境
source /opt/hermes/.venv/bin/activate

# 2. 运行配置向导（此时是标准 TUI 交互界面，不会再被当 chat 消息）
hermes setup

---

五、在配置向导中按顺序填写

5.1 模型配置（LLM Provider）

表格

选项	推荐值	说明
Select Provider	Ollama 或 OpenAI-Compatible	自己部署的模型或者第三方
Base URL	http://192.168.x.x:11434	你的 Ollama 服务内网地址
Model	如 hermes3:70b、qwen2.5:72b	根据你实际部署的模型填写

如果 Ollama 和 Docker 在同一台服务器，可用 http://host.docker.internal:11434（Docker Desktop）或宿主机实际内网 IP。

5.2 消息网关配置（Gateway）

配置完模型后，选择配置消息平台：

在 hermes setup 的完整流程中一并配置。

选项	推荐值
Select Platform	Feishu / Lark

配置完成后，文件会写入：

/opt/data/.hermes/.env

因为挂载了 -v /mnt/docker/hermes-agent:/opt/data，所以配置会持久化保存到宿主机，容器删了也不怕。

---

六、退出容器，转为后台守护运行

配置完成后，在容器内输入 exit 退出。

现在用后台模式 启动，注意：不映射任何端口。

# 先删除刚才的交互式容器
docker rm -f hermes-agent

# 后台守护运行，零端口暴露
docker run -d \
  --name hermes-agent \
  --restart always \
  -v /mnt/docker/hermes-agent:/opt/data \
  docker.1ms.run/nousresearch/hermes-agent:latest \
  gateway run

关键安全参数说明：

• ❌ 没有 -p 8000:8000 或任何端口映射

• ✅ 只有 -v 数据卷挂载

• ✅ --restart always 确保服务器重启后自动恢复

• ✅ gateway run 直接启动网关，不再进入交互模式

---

七、飞书侧配置（两种模式）

模式 A：扫码自动创建（最简单，推荐）

如果你选择了扫码方式，终端会显示一个二维码链接，用手机飞书 App 扫码即可自动创建应用并授权。这是官方推荐的一键方式。

模式 B：手动创建应用（企业环境）

1. 访问 飞书开放平台 → 开发者后台

2. 创建企业自建应用 → 输入名称

3. 添加应用能力 → 选择 机器人

4. 权限管理中必须添加以下权限：

   • im:message（接收和发送消息）

   • im:message:send_as_bot（以机器人身份发送）

   • contact:contact.base:readonly（读取用户基本信息，必需！）

   • im:resource（读取消息中的资源文件）

   • im:chat:readonly（读取群聊信息，可选但建议）

5. 事件与回调 → 订阅方式选 长连接（对应 WebSocket 模式）

   • 添加事件：im.message.receive_v1

6. 凭证与基础信息 → 复制 App ID 和 App Secret

7. 版本管理与发布 → 创建版本并申请发布（需要管理员审批）

---

八、首次对话配对授权

配置完成后，在飞书中搜索你的机器人，发送任意消息（如"你好"）。

如果是首次连接，可能会收到配对码（pairing code）（扫码连接自动配置不需要配对码），需要在服务器端授权：

# 查看容器日志，找到配对码
docker logs -f hermes-agent

# 或者在容器内执行授权
docker exec -it hermes-agent bash
source /opt/hermes/.venv/bin/activate
hermes pairing approve feishu <配对码>

---

九、验证与运维

查看运行状态

# 看日志
docker logs -f hermes-agent

# 成功标志
# [Gateway] feishu gateway connected

查看配置是否持久化

cat /mnt/docker/hermes-agent/.hermes/.env

重启/更新

# 重启容器
docker restart hermes-agent

# 更新镜像（保留配置）
docker pull docker.1ms.run/nousresearch/hermes-agent:latest
docker rm -f hermes-agent
# 然后用上面的 docker run -d ... 命令重新启动

---

十、安全加固清单（生产环境）

表格

项目	状态	说明
零端口暴露	✅	无 -p 参数，服务器不监听任何新端口
出站仅 443	✅	WebSocket 只走 HTTPS/WSS 443 出站
数据持久化	✅	配置保存在宿主机 /mnt/docker/hermes-agent
自动重启	✅	--restart always 保障高可用
权限最小化	⚠️	飞书应用权限按需授予，不要全开
白名单控制	可选	FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy 限制可用用户

---

完整命令速查表

# 1. 安装 Docker + 配置镜像加速（见上文）

# 2. 拉取镜像
docker pull docker.1ms.run/nousresearch/hermes-agent:latest

# 3. 准备目录
sudo mkdir -p /mnt/docker/hermes-agent
sudo chmod -R 777 /mnt/docker/hermes-agent

# 4. 交互式配置（进入容器）
docker run -it --name hermes-agent \
  -v /mnt/docker/hermes-agent:/opt/data \
  --entrypoint /bin/bash \
  docker.1ms.run/nousresearch/hermes-agent:latest

# 容器内执行：
source /opt/hermes/.venv/bin/activate
hermes setup
# 按向导配置 Ollama + Feishu WebSocket，保存退出
exit

# 5. 后台运行（零端口）
docker rm -f hermes-agent
docker run -d \
  --name hermes-agent \
  --restart always \
  -v /mnt/docker/hermes-agent:/opt/data \
  docker.1ms.run/nousresearch/hermes-agent:latest \
  gateway run

# 6. 查看日志
docker logs -f hermes-agent

---

这套流程的核心优势就是服务器侧零暴露 ：没有 -p、没有反向代理、没有防火墙入站规则，全靠 WebSocket 主动 outbound 连接飞书，配合你内网的 Ollama 服务，整个链路都在可控范围内。