Hermes升级v0.17.0，3 个坑已踩，附解决方案

Hermes Agent 更新到 v0.17. 0，我升级后接连踩了三个坑，花了大量时间排查，整理出来避免大家走弯路。

这次升级主要影响三类用户：开了 API Server 的、用飞书对接的、以及 Docker Compose 里配了 user/group_add 的。如果你属于其中任何一类，建议先看完再升级。

坑一：API Server 密钥被强制要求 16 位以上

升级后如果你开了 API Server 并且绑定到 0.0.0.0（局域网可访问），gateway 会直接拒绝启动，日志报错：

Refusing to start: API_SERVER_KEY is a placeholder or too short (<16 chars)

这不是 bug，是 v0.17.0 新加的安全加固。能分发终端命令的 API 如果用 8 位密钥，暴力破解几乎是分分钟的事。

解决办法：用 16 位以上的密钥，填到 Compose 文件中的 API_SERVER_KEY 里。如果你的 API Server 只监听 127.0.0.1（默认配置），这个限制不会触发，不用改。

坑二：飞书插件静默失效

升级后飞书 WebSocket 连接直接断了，日志里找不到明显报错，实际上飞书平台压根没加载。

原因有三个：

（1）lark-oapi 变成了可选依赖，不会自动安装

lark-oapi 从默认依赖改成了可选依赖（feishu extra）。所以没有自动安装。

（2）懒加载被默认禁止

以前飞书插件首次使用时会自动从 PyPI 拉 lark-oapi，但现在 Hermes 的 Docker 镜像里设了 HERMES_DISABLE_LAZY_INSTALLS=1，禁止了运行时自动安装。所以飞书插件静默禁用。

（3）权限问题

Hermes 初始设置时，用 pip install --target 安装的包，默认权限是仅 root 可读。重启后 Hermes 的网关进程以 hermes 用户（uid 10000）运行，会导致权限问题读不了。

虽然 import lark_oapi 会报 PermissionError，但错误被上层捕获后只输出了一句 "requirements not met"，日志里完全看不到权限相关的报错。

这是我排查最久的一个坑。

修复说明：

以下命令可以让容器终端中的 Hermes 以 root 身份在容器中帮我们执行，省得 SSH 了，所以以下命令中的路径我都用的容器内路径。如果选择 SSH 执行，记得修改路径。

我是用的绿联 DX4600 ，直接在 Docker 容器中进入终端，命令行输入 Hermes 后回车，就可以和终端内的 Hermes 对话了。其他 NAS 参照操作也行。

临时修复方案：

# 安装 uv pip install lark-oapi==1.5.3 # 修复权限 chmod -R o+rX /opt/data/.local/lib/python3.13/site-packages/

注意两条命令缺一不可：第一条装包，第二条修权限。修复完重启 gateway 就好了。

但这只是临时的，因为没有安装在持久化卷（映射目录）上，容器重建后又会丢了。

永久修复方案（持久化）：

# 安装到持久化目录 /opt/data 下 uv pip install --target /opt/data/.local/lib/python3.13/site-packages lark-oapi==1.5.3 # 修复权限 chmod -R o+rX /opt/data/.local/lib/python3.13/site-packages/

然后在 compose 里指向这个目录：

environment: - PYTHONPATH=/opt/data/.local/lib/python3.13/site-packages

这样装一次就永久生效，重启不丢。

注意：

（1）虽然 lark-oapi 的最新版本是 1.6.8，但还是要装 1.5.3 版本，因为 Hermes 内部的版本锁是 lark-oapi==1.5.3，装 1.6.8 会导致版本检查不通过，飞书插件照样加载失败。

（2）安装命令和 Compose 里的 python 3.13 是与 Hermes 的 python 版本对应的，如果下次 Hermes 更新了 python 版本，这里也需要更新版本号。不过等下次升级 Hermes，可能飞书插件问题已经被官方修复了。

坑三：Docker Compose 里加 group_add 会导致启动失败

之前我的文章曾经介绍过，为了在 Hermes 的目录与 Hermes 协作，把 Hermes 的用户加入了宿主机用户所在的 100 用户组，这在 v0.17.0 版本行不通了。

注意：

如果不确定自己的用户组别，需要在 SSH 用 id 命令查询一下，每个品牌 NAS 的宿主机用户组别可能不同。以下以 100 为例。

问题一：user: "10000:100" 直接拒绝启动

新版 Hermes 用 s6-overlay 做进程管理，容器启动时必须先以 root 身份跑 bootstrap（UID 映射、数据卷权限修复、配置初始化），完成后才降权到 hermes 用户。

如果我们在 compose 里写了 user:，容器直接以指定用户启动，会跳过 root 阶段，bootstrap 就全部跑不了。

问题二：group_add 被 s6-overlay 静默清除

group_add: ["100"] 在 s6-overlay 架构下也不生效。

原因是 s6-setuidgid 降权时会调用 initgroups()，这个函数从容器内的 /etc/group 重新构建补充组列表，Docker 内核层面注入的组会被覆盖掉，等于白加。

这个限制是 s6-overlay 的设计决定的，不是 Hermes 的 bug。

解决方案：

不再用 user=10000:100、group_add 来指定 Hermes 的用户 ID 和用户组 ID，改为用 环境变量 代替：

environment: - HERMES_GID=100 # 我们想让Hermes加入的用户组

这样容器以 root 启动，bootstrap 正常跑完，然后自动把 hermes 用户组映射到我们指定的 GID，文件权限自然就对齐了。

总结

这三个变化都属于"不报错但会出问题"的类型，比较隐蔽，先这样解决。飞书插件的问题估计官方会修复，还没升级到 v0.17.0 的朋友可以先等等。