主机级 L1 配置（M7-01）

每台主机维护独立的 L1 协议三元组：

  • bid — 业务标识（整型 ID，由调用方业务系统分配）
  • secretKey — 32 字符 AES-256 共享密钥（用于 L1 老协议加解密 / 新 webhook 签名）
  • report_url — 反向上报 URL（变更事件 / agent 上报 / 业务推送）

老版 m2-gateway 整个 exe 共用一份 L1 配置（写在 config.ini）。 新版每个 host_id 都有独立配置，agent 进程内同时承载多个虚拟 L1 上下文，互不污染。

1. 三入口编辑

任何一个入口改了，另两个入口 1 秒内可见最新值。

入口 A：user-web 控制台

https://web.gateway.wechas.com → 我的主机 → 点主机名 → L1 配置 标签页。

适合：用户自己运维，浏览器里改最方便。

入口 B：agent GUI（双击托盘图标）

打开 m2-gateway.exe 主窗口 → L1 配置 标签页 → 改三元组 → 保存。

适合：客户机离线 / 没有公网入站、但有人坐在电脑前能操作 GUI 的场景。

入口 C：Client API

由你的业务系统直接调中枢：

PUT /v1/user/hosts/{host_id}/l1-config
Authorization: Bearer ak_<key_id>.<secret>
Content-Type: application/json

{
  "bid": 8848,
  "secret_key": "0123456789abcdef0123456789abcdef",
  "report_url": "https://your-business.example.com/gateway/report"
}

返回：

{
  "host_id": "...",
  "bid": 8848,
  "secret_key_masked": "0123****cdef",
  "report_url": "https://your-business.example.com/gateway/report",
  "updated_at": "2026-05-14T08:30:00Z",
  "webhook_delivery_id": "wd_01HXX..."
}

适合：SaaS 平台批量改自家用户的主机 L1 配置；CI 流水线统一刷 secret。

2. 推送机制（软重启）

中枢更新 DB 后：

  1. 通过 wshub 向 agent 发 config.updated 控制帧；
  2. agent 收到后不退进程，只重建 L1 上下文（关闭旧 token、用新 secretKey 解密、用新 bid 注册），整个过程约 1 秒；
  3. 同时间窗口内未完成的请求继续用旧 secretKey，新请求用新 secretKey；
  4. agent 完成后回 ack；中枢写 host_online_events.event='configured'。

3. Webhook 推送（变更通知）

如果该主机配置了 report_url，中枢会在 DB 更新后同步触发一次 webhook：

  • 用旧的 secret_key对 payload 做 HMAC-SHA256 签名（防止伪造）
  • payload 里携带新的 secret_key（接收方据此更新自己的密钥本）

详见 Webhook 推送。

4. 审计 & 历史

每次改动产生：

  • audit_log 一行（host.l1_config.update，含 admin/user/api 调用源）
  • host_l1_config_versions 一行（保留全部历史值，加密存储）
  • webhook_deliveries 一行（如果配了 report_url）

用户可在 控制台 → 主机详情 → 操作历史 看到自己主机所有改动。

5. 兼容性

老版 m2-gateway（v0.1.x）只读取 config.ini 一份配置，不支持主机级三元组。 推荐升级 agent 到 0.2.2 以上。如果坚持用老 agent，新中枢仍可调旧 L1 协议（兼容路径）， 但无法享受 webhook 推送和软重启功能。