#排查手冊

本頁只保留可對外共享的排查思路，適合與 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，應優先核對服務前綴、路由發布狀態，以及白名單範圍是否一致。