① Webhook 入参校验与幂等
入口层先拒绝脏数据,再谈编排。建议固定 Content-Type: application/json,对 body 做大小上限(如 256KB)与解析超时。业务字段用白名单:至少包含事件类型、仓库/项目标识、分支或 tag、提交 SHA、触发者 ID;可选附带构建 profile、环境名。对 Git 类平台自带的 X-GitHub-Delivery 或等价 delivery_id 在 Redis 做短期去重(TTL 24~72h),避免重试导致重复入队。与共享构建目录、权限约定需与团队已落地的隔离策略一致,避免多任务写同一工作区。
② 鉴权 Token 与 Header 配置
公网 Webhook 必须假设会被扫端口与伪造请求。推荐组合:路径或 Header 中的随机共享密钥(长度 ≥32 字节)+ 可选 HMAC-SHA256 签名(body + timestamp,防重放窗口 5 分钟)。Nginx/Caddy 可在边缘层校验 Authorization: Bearer … 或自定义 X-Webhook-Token,通过后转发到内网 OpenClaw 网关。禁止在日志中打印完整 Token;轮换时在双密钥窗口内并行校验旧值与新值。MeshMac 多节点场景下,Token 与签名密钥应来自同一密钥源(如环境变量由配置中心下发),避免各节点不一致导致随机 401。
③ 与 OpenClaw 任务触发串联
校验与鉴权通过后,将标准化后的 payload 转为 OpenClaw 任务:写入与多节点 Worker 共用的队列(Redis Stream、RabbitMQ、或 OpenClaw 提供的任务 API),负载中写明 job_type(如 shared_build)、目标节点标签、脚本入口、超时与重试策略。Webhook 处理函数应快速返回 202,重活交给队列消费者,避免源站重试堆积。节点选取可用标签路由或「任意可用构建机」,并与各节点统一配置、同一任务 schema对齐,确保 Worker 能一致消费。
④ 多节点状态广播与通用通知渠道
构建在哪一台节点跑完,团队往往需要同一条摘要:建议把状态写入中心化存储(Redis Hash、Postgres 一行任务表),由单独的 Notifier 服务订阅变更或轮询「终态」。通知渠道用通用写法即可对接多数环境:向第二个 Webhook URL POST JSON(含 status、node_id、duration、日志链接);或调用邮件 API、企业微信/钉钉/Slack 的 Incoming Webhook。多节点时务必带上 node_id 与 correlation_id(与入站 Webhook 的 delivery id 对齐),便于排错与审计。
⑤ 能力对照表(校验 / 鉴权 / 触发 / 通知)
一表对照各环节职责,便于评审与交接。
| 环节 | 建议做法 | 注意点 |
|---|---|---|
| 入参校验 | Schema/白名单、body 大小上限、delivery 幂等 | 缺字段直接 400,勿默认「最新分支」以免误构建 |
| 鉴权 Token | Bearer 或 HMAC + 时间窗;边缘与业务双检 | 密钥轮换、禁止写日志;各节点配置一致 |
| OpenClaw 触发 | 入共享队列或官方 API;异步 202 | 与 Worker 版本、任务 schema 对齐;设置超时/重试 |
| 状态通知 | 中心化状态 + Notifier;出站 Webhook 或 IM | 带 node_id 与 correlation_id;失败重试与退避 |
⑥ 常见 HTTP 错误排查表
联调与上线后按状态码快速缩小范围。
| HTTP | 常见原因 | 处理建议 |
|---|---|---|
| 400 | JSON 损坏、缺必填字段、超过 body 限制 | 校验源站 payload 样例;放宽限制需评估 DoS 风险 |
| 401 / 403 | Token 错误、签名过期、IP 未放行 | 对时钟与 HMAC secret;检查 WAF/防火墙与白名单 |
| 404 | 路径错误、多节点路由未挂载该服务 | 核对 URL 与反代 location;确认每台节点进程存活 |
| 408 / 504 | 上游 OpenClaw/队列慢、同步阻塞在 Webhook 内 | 改为先入队再返回;加大网关 read_timeout 仅作辅助 |
| 413 | body 过大 | 缩小 JSON 或改引用对象存储链接 |
| 429 | 源站重试过猛或限流策略过严 | 指数退避;幂等键避免重复任务 |
| 502 / 503 | 后端宕机、队列满、TLS 握手失败 | 健康检查与告警;检查到 Redis/内网连通性 |