Telegram Bot Webhook Nginx 反向代理配置指南：SSL、路徑與逾時避坑

部署 Telegram Bot 時，Webhook 是接收使用者訊息最直接的方式，但它對公網 HTTPS 有硬性要求。很多團隊在設定 Nginx 反向代理時踩過 SSL 憑證錯誤、502 逾時、路徑截斷等坑。本文從實戰角度，一步步帶你完成從零到可用的 Nginx 配置，並附排查清單與常見問題，適合 B2B SaaS 營運、社群管理團隊參考。

為什麼 Telegram Bot 需要 Nginx 反向代理？

Telegram Bot 的 Webhook 機制要求你的伺服器必須透過 HTTPS 對外暴露，且監聽埠通常為 443。直接讓 Bot 後端（如 Python 的 Flask、Node.js 的 Express）監聽 443 埠並處理 SSL 憑證並非不可行，但有幾個現實痛點：

• 後端服務可能同時服務於內部 API，不希望暴露在公網。
• 多個 Bot 需要共享同一個公網 IP 與域名。
• SSL 憑證續約、日誌記錄、限速等維運需求需要一個統一入口。

Nginx 反向代理正好解決這些問題：它承擔 SSL 卸載、路徑轉發、負載平衡等職責，後端服務只需監聽內網埠，大幅降低維運複雜度。

Webhook 對 SSL 與埠的強制要求

Telegram API 只接受 TLS 1.2 及以上 的 HTTPS 連線，且 Webhook URL 必須是公網可訪問的 443 或 80 埠（實際生產環境幾乎只用 443）。如果憑證鏈不完整、域名不匹配或協定版本過低，Telegram 會拒絕連線並返回 "SSL certificate is invalid" 錯誤。

反向代理 vs 直連 Bot 伺服器：何時選擇 Nginx

場景	直連 Bot 伺服器	Nginx 反向代理
單 Bot、低流量、臨時測試	可行，簡單	不必要
多 Bot、多域名、需要 SSL 集中管理	維運成本高	推薦
需要限速、IP 白名單、日誌稽核	需自行實現	Nginx 原生支援
後端服務需要同時服務內網	暴露風險	安全隔離

結論：如果你的 Bot 服務於 B 端客戶、需要多人協作或多 Bot 管理，Nginx 反向代理是更穩妥的選擇。

前置準備：你需要哪些資訊與元件？

在動手配置前，確認以下要素齊全：

• Bot Token：從 @BotFather 獲取，形如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。
• 域名：已解析到伺服器 IP，例如 bot.yourdomain.com。
• 後端服務地址：Bot 後端監聽的 IP 與埠，例如 127.0.0.1:3000。
• Nginx 已安裝：版本建議 ≥ 1.18。
• SSL 憑證：推薦 Let’s Encrypt（免費、自動續約），也可用商業憑證。
• 伺服器防火牆：放行 443 埠（ufw allow 443/tcp 或雲平台安全組規則）。

步驟一：設定 Nginx 站點——SSL 憑證與 Webhook 路徑轉發

假設你的域名是 bot.yourdomain.com，後端服務運行在 127.0.0.1:3000，Webhook 路徑為 /webhook/<bot_token>。以下是一個完整的 Nginx server block 範例：

server {
    listen 443 ssl;
    server_name bot.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/bot.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bot.yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location /webhook/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 30s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }

    access_log /var/log/nginx/bot-access.log;
    error_log /var/log/nginx/bot-error.log;
}

將上述內容儲存至 /etc/nginx/sites-available/bot.yourdomain.com，然後建立軟連結到 sites-enabled，執行 nginx -t 測試語法，無誤後 systemctl reload nginx。

關鍵 proxy_set_header 參數詳解

• Host $host：傳遞原始 Host 頭，Telegram 會驗證域名與憑證匹配。
• X-Real-IP $remote_addr：記錄客戶端真實 IP，後端可透過此頭取得使用者 IP。
• X-Forwarded-For $proxy_add_x_forwarded_for：串聯代理鏈 IP，用於稽核。
• X-Forwarded-Proto $scheme：標明原始協定（https），後端可據此判斷是否走 TLS。

遺漏這些頭可能導致後端日誌中 IP 全是 Nginx 內網地址，或 Webhook 簽章驗證失敗。

路徑重寫：避免 Webhook 路徑被錯誤截斷

location /webhook/ 塊會匹配所有以 /webhook/ 開頭的請求。如果後端期望的路徑是 /webhook/<token> 且不包含額外前綴，上述配置已滿足。但若後端監聽根路徑（/），則需要用 rewrite 去除路徑前綴：

location /webhook/ {
    rewrite ^/webhook/(.*) /$1 break;
    proxy_pass http://127.0.0.1:3000;
}

這樣 /webhook/123456:ABC 會被轉發為 /123456:ABC。務必根據後端實際路由調整，否則可能收到 404。

步驟二：解決 HTTPS 憑證問題——Let’s Encrypt 自動續約

Let’s Encrypt 憑證有效期 90 天，需自動續約。使用 Certbot 的 webroot 模式可在 Nginx 運行狀態下完成驗證：

certbot certonly --webroot -w /var/www/html -d bot.yourdomain.com

續約後執行 systemctl reload nginx 使新憑證生效。建議在 cron 中配置：

0 0 * * * certbot renew --quiet --renew-hook "systemctl reload nginx"

如果你使用 standalone 模式，需暫時停止 Nginx，生產環境不推薦。

步驟三：應對 502 Bad Gateway——逾時與後端健康檢查

502 是最常見的反向代理錯誤，原因通常出在以下環節：

• 後端服務未啟動：systemctl status bot-service 或 ps aux | grep bot 確認行程存在。
• 防火牆屏蔽後端埠口：檢查 ufw status 或雲平台安全群組是否放行了後端埠口（如 3000）。
• Nginx 逾時太短：如果後端處理 Webhook 請求耗時較長（例如 AI 推理、資料庫寫入），預設的 proxy_read_timeout 60s 可能不夠。建議根據業務調整：

proxy_connect_timeout 30s;
proxy_read_timeout 120s;   # 延长至 120 秒
proxy_send_timeout 60s;

常見 502 排查清單（防火牆、後端日誌、Nginx error.log）

1. 檢查後端服務日誌：確認是否有異常崩潰或連線拒絕。
2. 查看 Nginx error.log：tail -f /var/log/nginx/error.log，定位具體錯誤行。
3. 測試後端直連：在伺服器上用 curl http://127.0.0.1:3000/health 驗證後端是否回應。
4. 確認防火牆：iptables -L -n | grep 3000 或 ufw status numbered。
5. 檢查 SELinux/AppArmor：部分系統預設禁止 Nginx 代理到本機埠口，需調整策略。

步驟四：驗證 Webhook 配置——curl 測試與 Telegram API 確認

配置完成後，透過 Telegram API 設定 Webhook URL：

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://bot.yourdomain.com/webhook/<YOUR_BOT_TOKEN>"}'

成功後回傳 {"ok": true, "result": true, "description": "Webhook was set"}。

然後查詢 Webhook 狀態：

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

正常回應範例（關鍵欄位）：

{
  "ok": true,
  "result": {
    "url": "https://bot.yourdomain.com/webhook/123456:ABC",
    "has_custom_certificate": false,
    "pending_update_count": 0,
    "last_error_date": 0,
    "last_error_message": "",
    "max_connections": 40,
    "ip_address": "你的服务器公网IP"
  }
}

如果 last_error_message 不為空（如 "SSL certificate is invalid" 或 "Connection timed out"），表示 Nginx 配置有問題，返回步驟一排查。

生產環境注意事項：日誌、限速與安全強化

• 開啟 Nginx 日誌：access.log 記錄請求來源與狀態碼，error.log 記錄異常。定期輪替（logrotate）避免磁碟寫滿。
• 配置 rate limiting：防止 Bot 端點被惡意調用：

limit_req_zone $binary_remote_addr zone=bot_limit:10m rate=10r/s;

location /webhook/ {
    limit_req zone=bot_limit burst=20 nodelay;
    proxy_pass http://127.0.0.1:3000;
}

• 關閉不需要的 HTTP 方法：只允許 POST（Telegram Webhook 使用 POST）：

if (request_method !~ ^(POST)) {
    return 405;
}

• 限制 IP 白名單（選用）：如果只有固定 Telegram IP 段存取，可在 location 區塊添加 allow 指令。但 Telegram IP 會變化，更推薦用簽章驗證而非 IP 白名單。
• 定期檢查 SSL 評級：使用 SSL Labs 測試，確保評級 ≥ A。

常見問題

問：Telegram Bot Webhook 返回 502 Bad Gateway，如何快速排查？
答：首先檢查後端 Bot 服務是否正常運行（systemctl status bot-service 或查看進程）。其次確認 Nginx proxy_pass 指向的 IP:端口是否正確。最後查看 Nginx error.log（通常位於 /var/log/nginx/error.log）確認具體錯誤——常見原因包括防火牆未放行後端端口、proxy_read_timeout 過短（建議 ≥ 60s）。

問：設置 Webhook 時提示 “SSL certificate is invalid”，但證書明明有效？
答：常見原因有三：1）證書鏈不完整（缺少中間證書，需合併 fullchain.pem）；2）域名與證書 CN/SAN 不匹配；3）Nginx 未正確配置 ssl_certificate 與 ssl_certificate_key 路徑。建議用 openssl s_client -connect yourdomain.com:443 -servername yourdomain.com 驗證證書鏈。

問：Webhook 路徑是否需要包含 Bot Token？如何安全處理？
答：Telegram 官方要求 Webhook URL 路徑必須包含 Bot Token（如 https://yourdomain.com/webhook/123456:ABC-DEF），以驗證請求來源。安全做法是將 Token 存儲在 Nginx 變量或外部文件中，通過 include 指令引入，避免在配置文件中明文硬編碼。日誌中應過濾 Token 字段。

問：使用 Let’s Encrypt 證書後，Webhook 偶爾失效，是什麼原因？
答：可能因為 Certbot 自動續期後未重載 Nginx。建議在 cron 續期命令後加入 --renew-hook "systemctl reload nginx"。另外檢查證書是否在續期後正確替換了舊文件（有時舊進程仍持有舊文件句柄）。

問：如何為多個 Telegram Bot 配置 Nginx 反向代理？
答：在同一個 server block 中，為每個 Bot 使用不同的 location 路徑（如 /webhook/bot1_token 和 /webhook/bot2_token），分別 proxy_pass 到不同的後端端口。也可使用多個 server_name 或子域名隔離。注意每個 Bot 的 Webhook URL 必須唯一。

---

如果你正在管理多個 Telegram Bot 的客服與運營，不想在 Nginx 配置上耗費太多精力，可以試試 TG-Staff——它提供 Web 控制台統一管理 Bot 的 Webhook 與坐席對話，內置分流鏈接、自動翻譯、內容風控等功能，省去自建反向代理的運維成本。註冊即享 3 天免費試用：https://app.tg-staff.com/。更多 Nginx 與 Bot 集成示例，請查閱 官方文檔。如有疑問，聯繫 @tgstaff_robot 獲取技術支持。