Gateway 在容器裡「看起來正常」，一掛到 Nginx/Caddy 後面就出現 502、WebSocket 握手失敗或無限重導向？ 本文鎖定入口反代 + TLS 終止 + WebSocket 升級這一層，與《Docker 網路分診》互補：前者管封包與封包之間誰看得見誰，本篇管瀏覽器到 Gateway 的 HTTP/1.1 升級鏈路與路徑是否正確。你將拿到六類高頻誤區、兩張拓撲/症狀對照表、可複製設定片段、六步上線 Runbook，以及三條應寫進值班的硬指標。讀完能先判斷該改 Upgrade 頭還是該回去查上游 127.0.0.1:18789。
proxy_pass 卻沒升 HTTP/1.1 與 Upgrade：瀏覽器走 WebSocket 時邊緣回 400/502，日誌卻像「Gateway 掛了」。/openclaw，應用仍依根路徑產生絕對 URL，導致靜態資源與 WS 路徑分裂。proxy_read_timeout 過短：長推理或通道訊息突發時連線被邊緣靜默掐斷，用戶端重連風暴誤傷上游。下面用拓撲表把「同機反代／獨立反代機／子網域／子路徑」的取捨壓平，再進入 Header 檢查表與分症狀矩陣。
同機反代（Nginx/Caddy 與 Gateway 同宿主機）排障路徑最短：curl -v http://127.0.0.1:18789 即可驗證上游。獨立反代機多一跳，需同步核對安全群組、內網 DNS 與 TLS SNI。子網域方案通常避免路徑剝離與 Cookie Path 的糾纏；子路徑適合統一網域策略，但必須在反代與 OpenClaw 基址設定兩側只剝一次前綴，並用瀏覽器開發者工具確認 WS URL 是否仍指向預期 wss:// 路徑。
實務上建議在變更單裡強制附兩張擷圖：一張是瀏覽器網址列最終落點，一張是 Network 面板裡 WebSocket 握手的 Request URL。沒有這兩張圖時，審查很容易把問題誤判為「模型逾時」或「通道 OAuth」，進而在錯誤平面浪費發布時間。若你同時在跑企業 HTTPS 代理，記得區分「辦公網瀏覽器」與「資料中心反代機」兩條路徑——前者可能注入 PAC，後者通常直連，症狀不一致是常態而非異常。
HTTP/2 在邊緣監聽、上游仍走 HTTP/1.1 WebSocket 的組合在 2026 年仍非常普遍：關鍵是確認從用戶端到反代與從反代到 Gateway兩段裡，哪一段允許升級。不要在未抓包的情況下同時開啟「強制 H2」與「自訂 WS 路徑改寫」，否則排障會退化成玄學。
| 拓撲 | 適用 | 維運收益 | 典型坑 |
|---|---|---|---|
| 同機反代 + 回環上游 | 單台 VPS／遠端 Mac 常駐 | 本機 curl 即可分診；TLS 與行程同日誌卷 | 誤綁 0.0.0.0 放大暴露面，需防火牆兜底 |
| 獨立反代機 | 多後端、藍綠、WAF 前置 | 邊緣與運算池解耦；憑證集中續期 | 內網路由、SNI、健康檢查目標易漂移 |
| 子網域 | WS 與站點主域分離 | 路徑語意清晰；CDN 規則好寫 | 多憑證與 HSTS 策略要單獨審查 |
| 子路徑 | 單入口品牌網域 | 使用者記憶成本低 | 前綴剝離、重導迴圈、資源根路徑錯位 |
無論選哪種實作，邊緣都要保證：升級到 HTTP/1.1、透傳或重建 Connection: upgrade 與 Upgrade: websocket，並為長連線設定大於模型最慢分位的讀逾時。下表用於 Code Review 勾選。
另有一條易忽略：反代緩衝。對一般 API 開啟 proxy_buffering 可能提升吞吐，但對串流回應或長保持連線有時會引入額外延遲甚至截斷感知；若你用了串流通道或類 SSE 行為，要在 staging 用真實負載壓一遍再開預設緩衝。
| 檢查項 | Nginx 要點 | Caddy 要點 |
|---|---|---|
| 協定版本 | proxy_http_version 1.1; | reverse_proxy 預設 HTTP/1.1；留意顯式 transport |
| Upgrade 鏈 | Upgrade $http_upgrade; Connection "upgrade"; | 多數場景自動處理；自訂需 header_up |
| Host 與原始用戶端 IP | proxy_set_header Host $host;、X-Forwarded-* | header_up Host {host}；信任反代 hops |
| 長連線 | proxy_read_timeout／send_timeout | transport http { read_timeout ... }（版本語法以文件為準） |
| 大請求體 | client_max_body_size | request_body 限制類指令 |
# 片段：反代到本機 Gateway（埠號依你的部署為準，示例 18789）
location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
# 片段：TLS 自動 + 反代 WebSocket 上游
openclaw.example.com {
reverse_proxy 127.0.0.1:18789 {
header_up Host {host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
}
}
提示：改設定後先用 curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" http://127.0.0.1:18789/ 在上游側驗證握手語意，再測公網 wss://；否則會在 TLS 與反代兩層之間來回甩鍋。
把症狀對應到「邊緣／上游／應用設定」三類，避免一上來就重建容器。若表格指向容器網路，請回到《Docker 網路分診》；若通道已通但 Slack/Telegram 不回，請對照《通道接入排查》。
遇到「僅生產環境重現、預發完全正常」時，優先比對三處 diff：憑證鏈是否同一 CA、CDN/WAF 規則集版本、以及反代 map／if 裡是否對特定 User-Agent 走了分支。很多 502 其實是邊緣規則誤殺，與 OpenClaw 版本無關。
| 現象 | 優先懷疑 | 驗證動作 |
|---|---|---|
| 502 Bad Gateway | 上游未監聽、防火牆、錯誤 socket 族 | 反代機 curl 上游；看 error.log 的 upstream timed out／refused |
| 413 Request Entity Too Large | 邊緣 client_max_body_size 過小 | 調大並 reload；同步 CDN/WAF 側限制 |
| WS 非 101 | Upgrade 遺失、路徑被改寫、http→https 跳轉打斷 | 瀏覽器 Network 裡看握手回應碼；對照 location 順序與 return 301 |
| 重導迴圈 | X-Forwarded-Proto 未設卻強制 https | 暫時關閉邊緣 HSTS 試驗；補全 forwarded 頭 |
| 憑證警示／部分用戶端失敗 | 鏈不完整、錯誤 SNI、混用 IP 憑證 | openssl s_client -servername 拉鏈；校時 NTP |
https:// 基址、是否子路徑、WS 是否與 HTTP 同 host。18789）。127.0.0.1:18789 或內網 VIP，獨立於公網延遲，便於判斷「慢在邊緣還是慢在 Gateway」。若你已接入集中日誌，請把「反代 access 5xx 率」與「Gateway 應用日誌錯誤率」做雙軸對齊：只有一側飆升時，責任邊界一目了然，也方便在復盤會上用資料而不是體感說話。
個人裝置上的反代實驗可以快速驗證設定片段，但休眠、VPN 切換與家庭寬頻入站不穩定會把 TLS 與憑證續期變成手工活；團隊也無法對 502 率做可合約化的 SLO。把反代 + 常駐 Gateway放到可 7×24 的專用主機（例如租用的 Apple Silicon 遠端 Mac 或受控 VPS），才能把限流、憑證與日誌留存做成標準變更，而不是「誰筆電還醒著誰就是維運」。一旦入口穩定，OpenClaw 與 CI、簽名流水線的聯動才談得上可稽核、可交接。
純自建反代棧還要持續跟進 OpenSSL、Nginx 與系統 CVE；對於要把 OpenClaw 與 CI、簽名、多通道機器人長期綁在一起的團隊，穩定獨佔算力 + 清楚地區/租期往往比反覆折騰家用出口更省總帳。MACCOME 的 Mac 雲主機提供多地區節點與可預期的租期檔位，適合作為「TLS 終止背後的那台乾淨常駐機」：先把《三平台安裝與選型》裡的目錄與權限邊界落地，再依 租賃價格 與區域頁把執行層託管到合約化環境——新加坡、東京、首爾、香港、維吉尼亞、矽谷——邊緣反代只負責入口策略與觀測。
連線、工作階段與通道類問題也可在 協助中心 依關鍵字檢索；需要圖形化排錯時，仍可結合遠端桌面策略與站內 SSH/VNC 類文章規劃視窗。
常見問題
502 時先查反代還是查 Docker？
先在反代機上 curl 回環上游；不通再回《Docker 網路分診》。需要方案比對時見 Mac mini 租賃價格。
子路徑和子網域怎麼選？
子網域通常少踩剝離坑；子路徑需兩側基址一致。安裝入口仍建議從 三平台安裝指南 對齊版本。
CDN 後面 WS 掉線？
關快取、拉長閒置逾時，或為控制面子網域繞過 CDN。通道側異常請對照 Slack/Discord/Telegram 排查篇。
日誌與工單去哪裡？
企業變更可走 協助中心 工單，避免在生產群丟半張 Nginx 設定。