新成员加入 Hermes 指南

本文给两类人看：

• 同事自己：按 §1 准备好你侧的 3 样东西，一次性发给管理员。
• 管理员（Allen）：按 §2 在 ECS 上一条命令开通。

---

1. 同事自己要做的（10 分钟）

Step 1. 注册 Multica 账号

1. 浏览器打开 https://multica.86lux.net
2. 用你的常用邮箱注册（推荐用工作邮箱，方便审计）
3. 收邮件 → 输入 6 位验证码激活
4. 登录后，在右上角头像 → Settings → Runtime Tokens 里点「Generate」生成一个 token
5. 复制 token，形如 mul_8982fee5983c832b67f0452375682def0857f3b1

⚠️ token 只显示一次，复制完就从 Multica 看不到了。建议先粘贴到记事本，发给管理员后再删。

Step 2. 创建你自己的飞书应用

每个 Hermes 跑一个独立的飞书 App，互不打架。

1. 浏览器打开 https://open.feishu.cn → 用你的飞书账号登录
2. 进入「开发者后台」→「创建企业自建应用」
3. 填：
   • 应用名称：Hermes-<你的名字>（例：Hermes-jingwen）
   • 应用描述：随便填，比如「我的 AI 助理」
   • 应用图标：随便选
4. 创建后，在「凭证与基础信息」里复制：
   • App ID（形如 cli_a956bba669b8dbc9）
   • App Secret（形如 Z9dafN7KNLdQsceQSf8Gft6SdC014OZA）
5. 在「权限管理」里，至少勾选：
   • im:message（收发飞书消息）
   • im:message.group_at_msg（群聊 @ 触发）
   • contact:user.base:readonly（识别说话人）
6. 在「事件订阅」里：
   • 订阅方式选 WebSocket（不要选 Webhook，不需要域名验证）
   • 订阅事件勾：im.message.receive_v1（接收消息）
7. 点「版本管理与发布」→ 创建新版本 → 提交审核（个人自建应用通常自动通过）

Step 3. 把这 4 样发给管理员

私信 Allen 以下信息（飞书私聊就行）：

姓名拼音：jingwen
Multica runtime token：mul_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
飞书 App ID：cli_xxxxxxxxxxxxxxxx
飞书 App Secret：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

管理员开通后会回你一个 Dashboard URL，类似：

http://8.129.13.96:9123

打开它，在右上角填入你的 Multica runtime token 即可开始用。

---

2. 管理员要做的（5 分钟）

Step 1. 选一对空闲端口

当前已占用的端口：

用户	WebUI 端口	Dashboard 端口
admin	8787	9119
guohua	—	9121
linjun	—	9122

下一个新用户：用 9123（dashboard）即可，webui 端口可不分配（团队成员通过 Multica 访问，不直接走 webui）。

可用范围：9123, 9124, 9125, ...

Step 2. 写用户配置文件

在 ECS 上：

ssh root@8.129.13.96
cd /opt/hermes-deploy/users

# 1) 写 env 文件（飞书凭据）
cat > jingwen.env <<'EOF'
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZAI_API_KEY=<复用 admin.env 里的 key 即可>
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
EOF
chmod 600 jingwen.env

# 2) 写 yaml 配置（直接抄模板即可）
cp template.yaml jingwen.yaml

团队 GLM key 可以共用，不需要每人单独申请。直接 grep ZAI_API_KEY admin.env 拿到。

Step 3. 一条命令部署

cd /opt/hermes-deploy
bash deploy.sh jingwen "" 9123

参数说明：

• jingwen — 用户名（要与 users/jingwen.env 文件名一致）
• "" — 不分配 WebUI 端口（团队成员走 Multica，不需要直连 webui）
• 9123 — Dashboard 端口（Multica 会通过这个端口和 hermes 通信）

如果 deploy.sh 第二个参数不接受空字符串，传一个不会冲突的值如 8788 即可。

Step 4. 在 Multica 里绑定 runtime

1. 浏览器打开 https://multica.86lux.net
2. 用 admin 账号登录 → Admin → Runtimes → 「Add Runtime」
3. 填：
   • Owner：选刚注册的同事邮箱
   • Token：粘贴他给你的 mul_xxxxxx
   • Endpoint：http://127.0.0.1:9123（本机走 docker bridge 即可，Multica 和 hermes 都在同一台 ECS）
   • Display name：Hermes-jingwen
4. 保存。

Step 5. 验证 + 回执

# 1. 容器在跑
docker ps | grep hermes-jingwen

# 2. 容器能看到 wiki canon
docker exec hermes-jingwen ls /wiki | head

# 3. dashboard 通
curl -s -o /dev/null -w 'http %{http_code}\n' http://127.0.0.1:9123

回执给同事：

你的 Hermes 已开通：
- Dashboard：http://8.129.13.96:9123
- 在 Multica 后台已绑定你的 token，刷新 multica.86lux.net 就能看到

第一次试试在你刚创建的飞书应用里 @ 它说「你好」。

---

3. 出问题怎么办

容器起来了但飞书不响应

• 检查飞书 App 的「事件订阅」是否选 WebSocket（不是 Webhook）
• 检查权限是否勾了 im:message
• 检查应用是否「已发布」状态

docker logs hermes-jingwen --tail 50 | grep -i 'feishu\|websocket\|connect'

Multica 看不到这个 runtime

• 检查 endpoint 是否填的 http://127.0.0.1:9123（不是公网 IP）
• 检查 token 有没有粘贴时多/少字符
• 在 Multica 后台 Runtimes 页面点「Test」会直接探活

看不到 wiki 内容

• /wiki 是只读挂载，所有 hermes 容器自动有
• 如果 docker exec hermes-jingwen ls /wiki 是空的，说明 deploy.sh 没注入挂载，重跑 bash deploy.sh jingwen "" 9123 即可（脚本已经把 -v /opt/wiki-vault/canon:/wiki:ro 写进去）

同事忘了备份 token

让他在 Multica 重新「Generate」一个新的，旧的会自动失效。然后告诉你新 token，你在 Admin → Runtimes 里 Edit 替换即可。

---

4. 把同事踢出去 / 离职清理

ssh root@8.129.13.96
docker stop hermes-jingwen && docker rm hermes-jingwen
docker volume rm hermes-data-jingwen
rm /opt/hermes-deploy/users/jingwen.{env,yaml}
# Multica 后台：Admin → Users → 找到该用户 → Disable

让同事自己删除他的飞书 App 即可（你删不了他的）。

---

关联

• Docs-as-Code 发布架构 — 整套 wiki 流转架构
• 企业版自动化运行架构 — Hermes 在 ECS 的运行机制
• 企业版Review Gate机制 — Multica 评审机制