第八章 网关运维

Gateway 是墨鱼的心脏——它持续运行，连接所有聊天平台，调度定时任务。本章教你如何让心脏稳定跳动，出了问题怎么急救。

Gateway 架构回顾

飞书 ──┐                    ┌──→ AI Agent 处理
Telegram ──┤                │
Discord ──┼──→ Gateway ─────┤──→ Cron 调度器（每60秒）
Slack ──┤     (单进程)       │
... ──┘                    └──→ 会话管理

Gateway 是单进程架构——一个后台进程处理所有平台的连接、消息路由、会话管理和定时任务调度。

---

安装与启动

首次安装

# 交互式配置向导
hermes gateway

# 安装为服务（开机自启）
hermes gateway install        # macOS: launchd 用户服务
hermes gateway install --system  # Linux: systemd 系统服务

避免冲突

不要同时安装用户服务和系统服务。Hermes 会检测到并警告，因为 start/stop/status 行为会变得模糊。

日常管理命令

# 启动
hermes gateway start

# 停止
hermes gateway stop

# 重启
hermes gateway restart

# 查看状态
hermes gateway status

# 查看日志
hermes gateway logs

---

macOS 服务管理

macOS 使用 launchd，生成的 plist 文件位于：

~/Library/LaunchAgents/ai.hermes.gateway.plist

plist 包含三个环境变量：

• PATH — 确保 hermes 命令可找到
• HOME — 用户目录
• HERMES_HOME — Hermes 数据目录（默认 ~/.hermes）

卸载服务

hermes gateway uninstall

Linux 服务管理

Linux 使用 systemd：

# 安装系统服务（开机自启，适合 VPS）
hermes gateway install --system

# 用户服务（适合开发机）
hermes gateway install

服务命名规则：

• 默认安装（~/.hermes）：hermes-gateway
• 多实例安装：hermes-gateway-<hash>

hermes gateway 命令会自动定位正确的服务。

---

多实例部署

如果你在同一台机器上运行多个 Hermes 实例（不同的 HERMES_HOME）：

# 实例 1（默认）
export HERMES_HOME=~/.hermes
hermes gateway start

# 实例 2
export HERMES_HOME=~/.hermes-work
hermes gateway start

每个实例有独立的：

• 配置文件（.env、config.yaml）
• 技能目录（skills/）
• Cron 任务（cron/）
• 会话存储（state.db）
• systemd 服务名

---

会话管理

会话持久化

Gateway 为每个聊天维护独立的会话。会话跨消息持久化——Agent 记得你的对话上下文。

重置策略

会话根据可配置的策略自动重置：

# ~/.hermes/gateway.json
{
  "session_reset_policy": {
    "telegram": "on_restart",
    "feishu": "on_idle_30m"
  }
}

手动重置

在聊天中发送：

/reset

后台会话

/background 帮我分析这个项目的代码结构

在独立的后台会话中运行，不阻塞主聊天。完成后自动将结果发回。

---

安全机制

用户允许列表（Allowlist）

默认情况下，Gateway 拒绝所有未授权用户。

方式一：允许所有用户（仅开发/测试）

# ~/.hermes/.env
GATEWAY_ALLOW_ALL_USERS=true

方式二：指定用户 ID（推荐生产环境）

GATEWAY_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy

方式三：DM 配对码（推荐）

不需要手动配置用户 ID。未授权用户首次 DM 机器人时，会收到一个一次性配对码：

用户：你好
Bot：🔒 你不在允许列表中。
     请在 Hermes CLI 中运行以下命令完成配对：
     hermes gateway pair <code>
     配对码 1 小时内有效。

# 在 Hermes CLI 中
hermes gateway pair <code>

配对码特性：

• 1 小时有效期
• 有速率限制
• 使用加密随机生成

生产环境必读

永远不要在生产环境使用 GATEWAY_ALLOW_ALL_USERS=true。你的 Agent 拥有终端访问权限，任何能联系到机器人的人都可以在你的机器上执行命令。

---

监控与排错

查看日志

# 实时日志
hermes gateway logs

# systemd 环境
journalctl -u hermes-gateway -f

# launchd 环境
tail -f ~/Library/LaunchAgents/ai.hermes.gateway.plist

健康检查

hermes gateway status

常见问题

问题	可能原因	排查方法
Gateway 启动失败	端口占用 / 配置错误	hermes doctor
飞书断连	WebSocket 超时	检查网络，查看日志
Cron 不执行	Gateway 未运行	hermes gateway status
消息不回复	用户不在 Allowlist	检查 GATEWAY_ALLOWED_USERS
双实例冲突	同时装了用户+系统服务	卸载一个：hermes gateway uninstall
macOS 重启后不自动启动	launchd 服务未安装	hermes gateway install

---

Home Chat

Home Chat 是一个特殊的聊天窗口，用于接收：

• Cron 任务结果
• 跨平台通知
• 系统提醒

设置方式：

# 在目标聊天中发送
/set-home

或预配置：

# ~/.hermes/.env
FEISHU_HOME_CHAT_ID=oc_xxxxxxxxxxxxx
TELEGRAM_HOME_CHAT_ID=-100xxxxxxxxxx

---

进度通知

控制 Agent 工作时的进度显示：

# ~/.hermes/config.yaml
display:
  tool_progress: true           # 显示工具执行进度
  background_process_notifications: true  # 后台任务通知

也可以通过环境变量：

HERMES_DISPLAY_BACKGROUND_PROCESS_NOTIFICATIONS=true

深入阅读

• 官方文档：Messaging Gateway
• Gateway 内部实现：Gateway Internals

---