#排查手册

本页只保留可对外共享的排查思路，适合与 PetaX 或其他外部协作方对齐问题范围。已移除仅限我方内部环境使用的入口、域名和探活命令。

#1. RabbitMQ 白名单 / TLS 连通性

可用 openssl s_client 对 broker 做一次 mTLS 握手，快速判断网络与证书链是否通过：

openssl s_client -connect <broker_host>:5671 -servername rabbitmq \
  -CAfile <ca.pem> -cert <client.crt> -key <client.key> -tls1_2 </dev/null

• 未放行 / 未打通：连接建立后立刻断开，常见为 read 0 bytes，通常说明出口 IP 未在白名单或中间链路被拦截。
• 已打通：能看到 ServerHello、证书链，并出现 Verify return code: 0 (ok)。

#2. 队列是否在投递

如果可以安全观测队列，优先看两个信号：队列消息数与消费者数。若消费者在线但长时间没有新消息，通常更接近“上游未投递”；若消息持续堆积，则更接近“消费侧未处理”。

建议使用不会销毁消息的方式排查，例如临时 basic.get 后 Nack(requeue=true)，或只读队列元信息。

#3. 区分“未投递” vs “已投递但未落账”

这两类问题只看最终业务记录往往分不出来。更可靠的方法是临时抓取原始消息体：

• 抓到原始消息：说明上游已投递，问题更可能在消费、字段映射或业务入账环节。
• 一段时间始终抓不到消息：说明问题更可能在上游通知未开通、未触发，或路由未到达。

如需临时查看消息，建议在排查完成后将消息 Nack(requeue) 放回，避免影响正式消费。

#4. HTTP 回调是否实际到达

如果接收侧具备网关、WAF 或应用访问日志，可按 request_path 或回调名聚合调用次数。若某类回调始终为 0，而同类其他回调有量，通常说明该通知未开通、未触发，或上游路由配置遗漏。

例如：settled-round 持续有量，但 settled-ticket 长期为 0，可优先确认该通知是否已在 PetaX 侧启用。

#5. 外部 Service API 返回码含义

• 502：表示调用链路上的上游失败；若前面还有 Cloudflare 或其他网关，外部看到的可能仍然是 502。
• 520：表示 Cloudflare 能连到源站，但源站对该路径返回了未知错误。若带不带 token 都是 520，通常说明请求甚至没走到鉴权，更像是路径、前缀或路由问题。
• 对照法：若同主机下认证类路径正常，而业务 Service API 路径持续 520，应优先核对服务前缀、路由发布状态，以及白名单范围是否一致。