Telegram Bot Webhook 502 故障排查：HTTPS 憑證、防火牆與逾時問題完整指南

當你的 Telegram Bot 突然停止回應，使用者訊息石沉大海，而 Bot 後端日誌卻一片空白時，問題很可能出在 Webhook 上。如果你在 Bot API 日誌中看到 502 Bad Gateway 或 504 Gateway Timeout，意味著 Telegram 伺服器無法成功連接你的 Bot 後端。這是跨境客服、社群營運和自動化 Bot 最常見的故障之一，但排查路徑其實固定且可預期。

本文將提供一份從 HTTPS 憑證、防火牆規則到逾時設定的逐步排查清單。無論你是使用自建 Bot 服務還是 TG-Staff 控制台，都能按圖索驥快速恢復服務。

---

為什麼 Telegram Bot 會返回 Webhook 502 錯誤？

Telegram Bot 的 Webhook 機制本質是：當使用者向 Bot 發送訊息時，Telegram 伺服器會向你在 setWebhook 中配置的 URL 發送一個 POST 請求。如果該請求無法被成功接收並返回 200 OK，Telegram 就會在重試若干次後標記為錯誤。

502 Bad Gateway 表示上游伺服器（你的後端）無法訪問或返回了無效回應。常見原因包括：

• HTTPS 憑證無效或過期
• 伺服器防火牆/安全組未開放 443 連接埠
• Telegram IP 段被封鎖（雲服務商或 CDN 規則）
• 後端處理逾時（預設 30 秒上限）
• Webhook URL 配置錯誤（如使用 HTTP 而非 HTTPS）
• CDN/WAF 誤攔截或反向代理配置錯誤

下面我們按步驟逐一排查。

---

第一步：檢查 HTTPS 憑證是否有效

Telegram 要求 Webhook URL 必須使用受信任的 CA 簽發的有效 HTTPS 憑證。自簽憑證、過期憑證或憑證鏈不完整，都會直接導致 502 錯誤。

使用 OpenSSL 快速檢驗憑證

在終端機中執行以下命令，檢查伺服器 443 連接埠的憑證資訊：

openssl s_client -connect your-domain.com:443 -servername your-domain.com

如果輸出包含 Verify return code: 0 (ok)，說明憑證有效。如果返回 20 (unable to get local issuer certificate) 或 21 (unable to verify the first certificate)，則憑證鏈不完整。

你也可以使用 SSL Labs 線上檢測工具 進行更全面的檢查。

憑證自動續期方案（Let’s Encrypt）

憑證過期是 Webhook 502 的常見原因。推薦使用 Certbot 自動續期：

sudo certbot renew --quiet

配置 cron 定時任務（每天執行兩次），確保證書在到期前自動更新。如果使用 Nginx，Certbot 會自動重載配置。

---

第二步：排查防火牆與網路連通性

即使憑證完美，如果伺服器 443 埠不可達，Telegram 依然無法連線。

驗證埠口可達性（nc / telnet）

在伺服器上執行：

nc -zv your-domain.com 443
# 或
telnet your-domain.com 443

如果連線被拒絕或逾時，表示防火牆或安全群組規則未放行 443 埠。

檢查 Telegram IP 段是否被封鎖

Telegram 伺服器使用固定 IP 段發起 Webhook 請求。請確認你的防火牆、雲服務商安全群組或 CDN/WAF 規則沒有封鎖以下位址段：

• Telegram 官方 IP 範圍：https://core.telegram.org/resources/cidr.txt
• 重點放行 149.154.160.0/20 和 91.108.56.0/22

注意：部分雲服務商預設安全群組會拒絕所有入站流量，需要手動新增規則。

---

第三步：排查 Webhook 請求逾時與伺服器效能

Telegram 對 Webhook 請求的預設逾時時間是 30 秒。如果你的後端處理邏輯耗時過長（例如資料庫慢查詢、呼叫外部 API 無回應），Telegram 會在逾時後重試，最終返回 504。

設定合理的逾時與重試策略

• 後端返回 200 OK 的回應時間應控制在 15 秒以內，預留緩衝空間。
• 如果業務邏輯必須長時間處理（例如產生報表），建議先回覆使用者「正在處理，請稍候」，後台非同步執行。
• 避免死結或無限迴圈：檢查程式碼中是否有未釋放的資料庫連線或無窮迴圈。

使用 TG-Staff 主控台檢視回應狀態

如果你使用 TG-Staff 管理 Bot，可以直接在主控台檢視 Webhook 狀態與錯誤日誌：

1. 登入 app.tg-staff.com
2. 進入對應專案的「設定」頁面
3. 查看 Webhook 狀態 指示器：如果顯示「連線失敗」或「回應逾時」，優先檢查前三步

TG-Staff 主控台會記錄每次 Webhook 請求的回應碼，幫助你快速定位是逾時還是其他錯誤。

---

第四步：檢查 Webhook URL 設定是否正確

很多人忽略的細節：Webhook URL 必須使用 HTTPS，且不能有拼寫錯誤。

呼叫 setWebhook 時，請確認：

• URL 以 https:// 開頭（HTTP 會導致 502）
• 路徑正確，無多餘斜線（如 https://example.com/ 可能被解釋為預設路徑）
• 無拼寫錯誤（檢查網域、子網域、路徑大小寫）

範例正確指令：

https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://your-domain.com/webhook

---

第五步：查看 Telegram API 回傳的具體錯誤碼

Telegram 提供了 getWebhookInfo 方法，可以精確告訴你為什麼 Webhook 失敗。

呼叫：

https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo

回傳結果中的關鍵欄位：

欄位	含義	常見值
last_error_date	最近一次錯誤發生的時間戳記	Unix 時間
last_error_message	錯誤描述	”SSL_ERROR”, “NETWORK_ERROR”, “TIMEOUT”
max_connections	最大並發連線數	預設 40
pending_update_count	待處理訊息數	數值越大表示積壓越嚴重

常見錯誤解讀：

• SSL_ERROR：憑證問題（過期、自簽、鏈不完整）
• NETWORK_ERROR：防火牆、IP 封鎖或 DNS 解析問題
• TIMEOUT：後端回應超過 30 秒
• WRONG_URL：Webhook URL 格式錯誤

---

第六步：常見進階場景與排查清單

CDN 與反向代理

如果你的網站使用了 Nginx/Apache 反向代理或 CDN（如 Cloudflare），請檢查：

• Nginx 設定：確保 proxy_pass 指向正確的後端埠，且 proxy_set_header 包含 Host、X-Real-IP 等必要標頭
• Cloudflare：代理模式必須為 Full (Strict)；如果使用 Flexible SSL，Telegram 無法驗證憑證鏈
• WAF 規則：不要誤封鎖 Telegram 的 IP 段（參考第二步）

IPv6 與雙棧問題

如果你的伺服器僅支援 IPv4，但 DNS 解析回傳了 AAAA 記錄（IPv6 位址），Telegram 可能嘗試連線 IPv6 位址失敗。

解決方案：

• 在 DNS 記錄中移除 AAAA 記錄
• 或確保伺服器支援雙棧（IPv4 + IPv6）

---

常見問題

問： 為什麼我的憑證有效但依然返回 502？ 答： 可能原因包括：防火牆未放行 443 埠、Telegram IP 段被雲服務商安全組屏蔽、CDN 代理模式設定錯誤（請使用 Full Strict）、或者伺服器響應超過 30 秒超時。請依次檢查第二步和第三步。

問： 如何查看 Telegram Bot Webhook 的具體錯誤資訊？ 答： 呼叫 Bot API 的 getWebhookInfo 方法（如 https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo），返回結果中的 last_error_message 欄位會提供具體錯誤原因，如 “SSL_ERROR” 或 “NETWORK_ERROR”。

問： 使用 TG-Staff 時如何檢測 Webhook 狀態？ 答： 登入 TG-Staff 控制檯（app.tg-staff.com），進入對應專案的設定頁面，查看「Webhook 狀態」指示器。如果顯示異常，可結合控制檯提供的錯誤日誌快速定位。

問： 伺服器響應時間超過 30 秒怎麼辦？ 答： 建議優化後端處理邏輯（如使用非同步任務佇列），確保返回 200 OK 響應在 15 秒內完成。如果必須長時間處理，可考慮先回覆使用者「正在處理」訊息，後臺繼續執行。

問： 自簽名憑證可以用嗎？ 答： 不可以。Telegram 要求 Webhook URL 必須使用受信任的 CA 簽發的有效 HTTPS 憑證。推薦使用 Let’s Encrypt 免費憑證並透過 Certbot 自動續期。

---

快速恢復 Bot 服務

如果你正在處理 Telegram Bot Webhook 502 故障，按本文清單排查通常可以在 15 分鐘內定位問題。如果你需要更簡單的管理方式，可以免費試用 TG-Staff：

• 在 app.tg-staff.com 註冊，一鍵配置 Webhook 並監控 Bot 狀態
• 查看 TG-Staff 文件 中的 Webhook 配置指南
• 聯絡 @tgstaff_robot 客服 Bot 獲取技術協助

TG-Staff 內建的 Webhook 狀態檢測和錯誤日誌功能，能幫你快速發現憑證過期、逾時或網路問題，讓團隊專注於營運而非排查故障。