【反向代理實作】NPM、Caddy、Traefik 三份完整設定，以及接 HA 一定會卡的那一關

charles

這篇的內容（39 段）

1. 反向代理在做什麼
2. 換來四件事
3. 做完這篇你會有什麼
4. 第一步：先把前置條件備齊
5. 1-1. 一個網域
6. 1-2. 決定內網還是外網
7. 1-3. DNS 記錄
8. 你會看到什麼（驗證）
9. 2-1. 為什麼會被拒絕
10. 2-2. ⚠ 2026.8 起這個設定搬家了
11. 2-3. 現在的做法（介面）
12. 3-1. docker-compose.yml（整份）
13. 3-2. 啟動
14. 你會看到什麼
15. 3-3. 登入
16. 3-4. 新增第一個 Proxy Host
17. Hosts → Proxy Hosts → Add Proxy Host
18. 3-5. 你會看到什麼
19. 3-6. 另外兩個服務
20. 4-1. 為什麼 Caddy 的設定這麼短
21. 4-2. Caddyfile（整份）
22. 4-3. docker-compose.yml（整份）
23. 4-4. 產生帳密雜湊
24. 你會看到什麼
25. 4-5. 先驗證設定檔，再啟動
26. 你會看到什麼（正常）
27. 5-1. 它跟前兩個的根本差別
28. 5-2. 建立網路與檔案
29. 5-5. 啟動與驗證
30. 你會看到什麼（正常）
31. 5-6. WebSocket
32. 第六步：三個方案怎麼選
33. 7-1. HTTP 驗證
34. 你會看到什麼（驗權杖）
35. 你會看到什麼
36. 你會看到什麼
37. 兩種解法
38. 第九步：要不要對外開放
39. 自我檢查

家裡跑了 HA、NAS、Frigate、Grafana，每一個都要記 IP 加通訊埠，而且全部是沒有憑證的 http。

反向代理就是解決這個的：所有服務走同一個入口，用好記的網址，統一一張憑證。

這篇給三個方案各一份完整可以直接跑的設定，而且特別處理一件事 —— 把 Home Assistant 接到反向代理後面，有一關是一定會卡的，而它的錯誤訊息不會告訴你要去哪裡改。那一關放在第二步，在你選方案之前就先做完。



反向代理在做什麼

1. 沒有反向代理：
2.   http://192.168.1.50:8123   ← Home Assistant
3.   http://192.168.1.20:3000   ← Grafana
4.   http://192.168.1.20:5000   ← Frigate
6. 有反向代理：
7.   https://ha.example.com
8.   https://grafana.example.com
9.   https://frigate.example.com
10.   （全部指到同一台代理，由它依網址轉給後面的服務）

複製代碼

換來四件事

• 好記的網址，不用背通訊埠
  
• 統一的 HTTPS 憑證，而且自動續簽
  
• 存取控制集中在一個地方
  
• 後端換 IP 或通訊埠時，只要改代理的設定，所有書籤照樣能用
  

做完這篇你會有什麼

• 一台反向代理，把 HA 與另外兩個服務接上去，全部走 HTTPS
  
• HA 的即時更新（WebSocket）正常運作
  
• HA 日誌裡看到的來源 IP 是真實訪客的 IP，不是代理的 IP
  
• 不用對外開任何通訊埠也能拿到有效憑證的做法
  

---

第一步：先把前置條件備齊

1-1. 一個網域

免費的也行（DuckDNS、No-IP），但強烈建議買一個，一年兩三百塊。理由是第七步要用的 DNS 驗證需要供應商的 API，免費服務多半沒有或很難用。

買完把網域的名稱伺服器指到 Cloudflare（免費方案就夠）。後面的 DNS 驗證會用它的 API。

1-2. 決定內網還是外網

• 模式 A：只給內網用 —— 不開任何通訊埠，DNS 記錄指向內網 IP，出門靠 VPN。最安全，而且設定最單純
  
• 模式 B：對外開放 —— 要開 80/443，而且要額外做防護
  

第一次做，先做模式 A。它不需要動路由器的通訊埠轉發，出問題也不會影響到外面。整套跑順了再考慮要不要開放。

1-3. DNS 記錄

到 Cloudflare 的 DNS 頁面新增三筆 A 記錄（模式 A 填代理主機的內網 IP）：

1. ha.example.com        A    192.168.1.10    （Proxy status: DNS only）
2. grafana.example.com   A    192.168.1.10    （DNS only）
3. frigate.example.com   A    192.168.1.10    （DNS only）

複製代碼

⚠ Proxy status 一定要是 DNS only（灰色雲朵）。開成橘色雲朵的話，Cloudflare 會試著幫你代理流量，但你的 IP 是內網位址，它連不到，症狀是外面看起來像壞了、裡面卻是好的。

你會看到什麼（驗證）

1. nslookup ha.example.com
2. # 或
3. dig +short ha.example.com

複製代碼

1. 192.168.1.10

複製代碼

回傳的不是你填的 IP → DNS 還在傳播，等幾分鐘。或是你有在用 Pi-hole／AdGuard，它可能擋掉或改寫了。

---

第二步：先改 Home Assistant，這是最容易卡的一關

順序很重要：先做這一步，再去架代理。反過來做的話，你架好代理、打開網址，看到的是一片空白加一行 400: Bad Request，而錯誤訊息完全沒提到該去哪裡改。

2-1. 為什麼會被拒絕

HA 預設不相信任何代理。請求經過代理之後，真正的來源 IP 藏在 X-Forwarded-For 標頭裡，而那個標頭任何人都可以偽造。所以 HA 的態度是：除非你明白地指定「哪些 IP 送來的 X-Forwarded-For 可以信」，否則帶著這個標頭的請求一律擋掉。

2-2. ⚠ 2026.8 起這個設定搬家了

網路上絕大多數教學（包括這篇的舊版）都叫你在 configuration.yaml 寫一段 http:。

從 Home Assistant 2026.8 開始，這些設定移到圖形介面了。升級時既有的 http: 區塊會自動匯入介面，並且在設定 → 系統 → 修復產生一則提醒，要你把 YAML 裡那段刪掉。YAML 寫法會在 2027.2 停止支援。

這個變化最麻煩的地方在於它不會壞 —— 舊寫法現在還能動，所以你不會發現自己抄了一份即將過期的做法。但有一個症狀會讓人卡住：設定還留在 configuration.yaml 的時候，介面上對應的欄位是灰色、不能改的。很多人以為是介面壞了。

2-3. 現在的做法（介面）

設定 → 系統 → 網路，捲到 HTTP 伺服器 那一區：

• 打開 信任 X-Forwarded-For
  
• 在 信任的代理 加入代理主機的位址
  

要填什麼位址，分兩種情況：

• 代理跑在另一台機器 → 填那台機器的 IP，例如 192.168.1.10
  
• 代理跑在同一台機器的 Docker 容器裡 → 填 Docker 的網段，例如 172.16.0.0/12。容器每次重建 IP 會變，填單一位址會在某次重啟後突然失效
  

⚠ 不要填 0.0.0.0/0。那等於「相信所有人送來的 X-Forwarded-For」，任何人都能偽造來源 IP，HA 的登入失敗封鎖與 IP 黑名單全部繞得過去。

順便把同一頁的兩個開關也設好：

• 啟用 IP 封鎖 → 打開
  
• 封鎖前的登入嘗試次數 → 5
  

改完重新啟動 Home Assistant。

2-4. 還在 2026.8 之前的版本（或你偏好 YAML）

放在 configuration.yaml 的最外層（頂格，跟 default_config: 同一層，中間空一行）：

1. default_config:
3. http:
4.   use_x_forwarded_for: true
5.   trusted_proxies:
6.     - 192.168.1.10          # 反向代理那台機器
7.     - 172.16.0.0/12         # 代理跑在容器裡的話用這個
8.   ip_ban_enabled: true
9.   login_attempts_threshold: 5

複製代碼

⚠ trusted_proxies 一定要是清單（每一行前面有減號）。寫成 trusted_proxies: 192.168.1.10 這種單行形式是常見錯誤，HA 會啟動失敗或忽略整段。

改完重啟 HA。

以下還有約 80% 的內容
登入後即可閱讀完整教學

登入繼續閱讀使用 Google 登入