From 8ae8d2b468f3aa07e9d67d165e20f3a225bedae9 Mon Sep 17 00:00:00 2001 From: wangliang Date: Fri, 23 Oct 2026 14:57:57 +0800 Subject: [PATCH] =?UTF-8?q?docs(runbook):=20=E8=A1=A5=E5=85=85=20WhatsApp?= =?UTF-8?q?=20=E5=9B=9E=E8=B0=83=20override=20=E4=B8=8E=E5=A4=9A=E6=A0=88?= =?UTF-8?q?=E5=8F=B7=E7=A0=81=E7=9A=84=E5=9D=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/runbook.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/runbook.md b/docs/runbook.md index 43ea4b2..50abda0 100644 --- a/docs/runbook.md +++ b/docs/runbook.md @@ -199,3 +199,6 @@ ss -ltnp | grep -E ':(9000|3100|4100|5440|6390)\s' | WhatsApp webhook 收不到 | 没有公网 HTTPS / Meta 回调地址不对 | 本地联调跑 `bash scripts/public-https.sh`；测试/生产使用正式域名，不要用 Quick Tunnel | | 公网访问到管理后台 | 网关白名单配置 | `services/public-gateway` 只放行 `/webhooks/whatsapp/*`、`/hc/*`、`/widget*`、`/static/public/*`，其余 404 | | AI 回复"系统暂时无法查询订单" | RPC 不可达，bridge 8s 超时 | 本地开发跑 `bash scripts/rpc-tunnel.sh --apply`；测试/生产检查内网 RPC 地址/网络策略，不要用开发机隧道 | +| WhatsApp 真实消息收不到，但 Meta "Send to My Server" 测试事件能到 | WABA 级 `override_callback_uri` 优先于 App 级 callback，且 Meta 对 override 的验证常返回 403（与目标 URL 无关） | `GET //subscribed_apps` 确认 override；`DELETE //subscribed_apps` 后重新 `POST`（不带 override）清掉，确认 App 级 callback 指向目标域名，再发真实消息验证 | +| 多个栈共用同一个 WhatsApp 号，消息被旧环境接走（旧环境 AI 回复、新环境无日志） | crm-new 与旧 crm-ai-demo 配置了同一 `WA_PHONE_NUMBER_ID` / WABA，旧栈 tunnel 仍在接收 | 停旧栈 WhatsApp 接收（停旧 tunnel / 禁用旧 inbox），或给新环境申请独立测试号；不要让两套同时接同一个号 | +| 新建 WhatsApp inbox 后 webhook 验证 403 `verify token mismatch` | 创建接口传入的 `webhook_verify_token` 可能未真正生效，inbox 仍是默认值；`GET /api/v1/inboxes/` 返回的是掩码值，不能用来核对 | 用 `PUT /api/v1/inboxes/` 带完整 config 重新保存一次，再请求 `GET /webhooks/whatsapp/?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...` 确认返回 200 |