一键修复 1panel 爱马仕 Hermes 更新 2026.7.1 版本 qq 链接器挂掉失效的问题

一键修复 Hermes QQ 连接器

🎯 适合：1Panel 用户 / Hermes Agent 使用者 / Docker Compose 运维

问题背景

2026 年 7 月 1 日 Hermes 更新后，QQ 连接器（QQbot platform）挂了。具体表现：

Hermes Agent 正常运行，但 QQ 无法收发消息
日志报错指向 QQ 适配器代码异常
原因是新版 Hermes 的 QQ 适配器有 Bug，需要覆盖替换

如果你的 Hermes 跑在 1Panel 托管的 Docker Compose 环境下，修复起来会有点绕——因为 compose 文件被容器锁着，直接改不进去。

修复思路

核心就三步：

停容器 — docker compose down（解锁 compose 文件）
注入挂载行 — 在 docker-compose.yml 的 volumes: 下加一行，把补丁文件挂进去覆盖掉坏掉的适配器
启容器 — docker compose up -d

听起来简单，但坑不少：

容器运行时会锁定 compose 文件，先停再改顺序不能反
不同机器的 YAML 缩进不一样（2 格 / 4 格 / 混合）
注入不能手滑改坏其他行，否则容器启不来
1Panel 管理的服务名不固定，不能写死

自动化脚本：fix-qq.sh

我把整个流程写成了一个一键脚本，放在 GitHub 上：

GitHub 仓库： dteen/hermes-patches

用法

bash <(curl -sL https://raw.githubusercontent.com/dteen/hermes-patches/main/scripts/fix-qq.sh)

干跑预览（不改任何文件）：

bash <(curl -sL https://raw.githubusercontent.com/dteen/hermes-patches/main/scripts/fix-qq.sh) --dry-run

脚本做了什么

步骤	操作	说明
1	查找容器	自动发现 Hermes 容器名
2	定位 compose 文件	通过 Docker label 反查路径，支持 1Panel 路径
3	检测网络	检查 GitHub 连通性（支持代理）
4	下载补丁	从 GitHub 下载修复后的 `qq-adapter.py`
5	停容器	`docker compose down` — 解锁文件
6	生成新文件	Python 读原 compose → 加挂载行 → 写出 `.new` 文件
7	逐行校验	新文件与原文逐行比对，确保只多了挂载那一行
8	YAML 校验	`docker compose config` 校验语法
9	备份 + 替换	通过校验才备份原文件、替换
10	启动容器	`docker compose up -d`

脚本的 Python 注入引擎会自动检测目标文件的缩进风格（2 格还是 4 格），按已有 volume 条目的缩进走，不会搞乱格式。

安全机制三重保险

┌──────────────────────────────────────────────────┐
│  ① 逐行比对                                      │
│  新文件每一行 vs 原文，除注入行外必须一字不差       │
│  → 不通过 → 报错退出，不动原文件                   │
├──────────────────────────────────────────────────┤
│  ② docker compose config YAML 语法校验            │
│  → 不通过 → 保留 .new 文件供检查，原文件不动       │
├──────────────────────────────────────────────────┤
│  ③ 自动备份                                       │
│  docker-compose.yml.bak.20260705_xxxxxx          │
│  任何时候 cp .bak.* docker-compose.yml 即可回滚   │
└──────────────────────────────────────────────────┘

实际执行效果

下面是脚本在一台 1Panel 服务器上跑的真实输出：

SSH 执行截图

可以看到：

自动找到了 1Panel-hermes-agent-hD7j 容器
定位到 /opt/1panel/apps/hermes-agent/Hermes-Agent/ 下的 compose 文件
逐行校验通过（31 行原文完全一致，仅新增 1 行挂载）
YAML 格式校验通过
容器启动成功

回滚方法

如果新版本修复了这个问题想还原，只需：

# 用备份文件恢复
cp /opt/1panel/apps/hermes-agent/Hermes-Agent/docker-compose.yml.bak.* \
   /opt/1panel/apps/hermes-agent/Hermes-Agent/docker-compose.yml

# 重启
docker compose up -d

或者重新跑脚本，它会检测到已注入，直接跳过。

技术细节

补丁文件做了什么

qq-adapter.py（约 125KB）包含 5 处修复，主要解决：

QQ 协议层连接超时处理
消息序列化兼容性
登录会话保持
重连机制
日志输出优化

为什么不用 `docker-compose.override.yml`

初期尝试过 override 方案，但 1Panel 管理的 compose 有服务名不一致的问题（不是默认的 gateway），override 文件无法正确合并。所以最终方案是直接修改主 compose 文件，配合备份和校验保证安全。

结语

如果你也遇到了 Hermes QQ 连接器挂掉的问题，希望这篇博客能帮你一把。脚本开源在 GitHub，欢迎提 Issue 和 PR。

遇到问题可以：

先跑 --dry-run 预览
跑正式命令，看输出
如果报错，把终端输出贴到 GitHub Issues

修复日期：2026 年 7 月 5 日
测试环境：Debian 12 + 1Panel + Docker Compose

KFC大王