Telegram 白名单配置排查记录

摘要

排查 30 分钟，根因是 .env 文件中 GATEWAY_ALLOW_ALL_USERS=true 覆盖了 YAML 白名单配置。白名单机制本身正常，但环境变量级别的”全员放行”开关优先级高于白名单，使其长期未实际生效。

---

背景

为 Hermes Agent 配置 Telegram Bot 后，需要限定仅授权用户可调用。按操作手册设置了 YAML 白名单：

# config.yaml
telegram:
  allow_from: '8341474632'

设置完成后存有疑问：该配置是否实际生效，抑或仅为心理安慰。

---

排查过程

步骤一：AI 审查发现环境变量冲突

将配置提交 AI 审查后发现 .env 文件中存在以下条目：

GATEWAY_ALLOW_ALL_USERS=true

该环境变量的语义为”全员放行”，其优先级高于 YAML 层的 allow_from 白名单。只要此变量为 true，白名单即为无效配置。

步骤二：验证测试

将 allow_from 改为 '0000000000'（不存在的用户 ID），重启网关，发送测试消息——网关正常回复。

确认白名单确实未生效。GATEWAY_ALLOW_ALL_USERS 的优先级覆盖了白名单配置。

步骤三：关闭后触发 pairing 机制

移除 GATEWAY_ALLOW_ALL_USERS=true，重启网关，再次发送消息：网关未回复，但返回了配对码。

Hermes Agent 存在 pairing（配对）机制：首次连接时即使在白名单内，仍需执行一次 hermes pairing approve 才能正式开通通信。

---

配置优先级

配置项	作用	优先级
allow_from: '用户ID'	YAML 白名单，限定指定用户	🔽 低（可被环境变量覆盖）
GATEWAY_ALLOW_ALL_USERS=true	环境变量级别全员放行	🔼 高（覆盖 YAML 白名单）
pairing 机制	首次连接需独立配对确认	⛔ 独立系统，与上述两项无关

决策流程

消息进入
    ↓
GATEWAY_ALLOW_ALL_USERS=true? ── 是 → 放行（白名单不参与判断）
    ↓ 否
在 allow_from 白名单内?  ── 是 → 需要首次配对
    ↓ 否
拒绝

---

经验记录

1. 环境变量优先于 YAML 配置，且无显式告警。 GATEWAY_ALLOW_ALL_USERS=true 本身是调试用途的配置，但上线前未清理即成为安全后门。部署前应对 .env 文件做逐项审计。

2. 修改配置后需重启服务。 改动文件未重启进程，配置变更不会生效——这属于基础操作纪律。

3. 首次连接需经过 pairing 流程。 即使白名单匹配，首次通信仍需手动 approve。这是 Hermes 的额外安全核查机制。

4. 先验证后信任。 一条测试消息即可验证白名单是否生效，效果优于反复审查配置文件。

5. 两个放行开关为”或”关系，非”与”关系。 allow_from 和 GATEWAY_ALLOW_ALL_USERS 任一条件满足即可通行。该设计在文档中未见明确说明，属于隐含的安全设计缺陷。