第 8 章

Serve

需要漂亮 HTTPS 入口時，先理解 Serve 與 Funnel 的安全差別；本教程只做私有的 Serve。 本章用可驗證、可回復的節奏帶你完成一件事；先保留私有存取，避免把 Home Assistant 直接曝露在網際網路。

為什麼現在要做這件事

Serve 與 Funnel 不是同一個風險。Tailscale Serve 將本機服務提供給 tailnet 內的裝置；Funnel 是提供給更廣泛網際網路。官方文件明確區分兩者，所以本章只處理 Serve 的私有入口，Funnel 留在本教程範圍外。

本章界線：App 文件的 share_homeassistant 選項可啟用 Serve 或 Funnel 行為，預設為 disabled。不要在未理解 reverse proxy 與 HA HTTP 設定前把它切到公開模式。

先懂三個名詞

tailnet 是你的 Tailscale 私有網路；Machine 是加入其中的一台裝置；Home Assistant App 則是由 Supervisor 管理、可在 HA 的 Apps 頁面開啟與設定的 Tailscale 服務。先分清這三層，後面的按鈕才不會按錯地方。

層級負責什麼本章怎麼驗證
Tailscale 管理主控台帳號、Machines、路由與 policyMachines 中找得到 HA
HA Tailscale App在 HA 主機上運行 Tailscale狀態正常、日誌無阻斷錯誤
Home Assistant登入、儀表板與管理者權限以個人帳號正常登入

動手做：安全地完成本章

  1. 先記錄目前狀態

    在 Home Assistant 左側進入 設定 → Apps，找到 Tailscale；若畫面用舊名稱，可能顯示 Add-ons。記下它是否運行，先不要改未使用的進階選項。

  2. 開啟需要的入口

    依本章目標查看 App 的 Info、Configuration、Log 或 Web UI。Web UI 的帳號授權只在信任的個人裝置完成。

  3. 到管理主控台交叉核對

    開啟 Tailscale admin console 的 Machines 頁面，確認 Home Assistant 對應的 Machine、最後連線狀態與功能標記；不要用截圖中的名稱或 IP 當自己的值。

  4. 從另一台裝置測試

    拿一台已登入同一 tailnet 的手機或筆電，完成一次本章目標的存取測試。成功後記下測試時間與裝置，方便日後排錯。

實作：只啟用私有 Tailscale Serve

  1. 保留 HA 的本機 HTTP

    官方 App 文件以 HTTP 可達的 HA 為前提；若已有其他 HTTPS 反向代理，不要混用設定，先依文件評估。

  2. 設定反向代理信任

    在 configuration.yaml 的既有或新增 http: 區段設定 use_x_forwarded_for: true 與 trusted_proxies: - 127.0.0.1，儲存後重啟 Home Assistant。

  3. 在 admin console 開 HTTPS

    到 DNS 設定選定 tailnet 名稱、啟用 MagicDNS，並在 HTTPS Certificates 選 Enable HTTPS。這是 Serve 取得憑證的前提。

  4. 在 App 啟用 serve 並重啟

    將 App 的 share_homeassistant 設為 serve，保持 share_on_port 的預設 443，重啟 App。請勿選 funnel。

  5. 以 tailnet 裝置測試 URL

    以 https://<machine>.<tailnet>.ts.net（不加舊埠號）從已登入 tailnet 的另一台裝置開啟，再以 HA 個人帳號登入。

範圍限制：Funnel 可讓未安裝 Tailscale 的網際網路裝置抵達服務；這不是本教程的設定目標。

選項怎麼選才不會擴大風險

先選最小可行做法，再逐步擴充。若你只是要回家看儀表板，私有 tailnet 存取通常比公開入口更容易控制；若你需要 LAN 子網，先列出一個網段與明確用途，不要一次宣告所有網路。

需求建議起點暫時不要做
遠端看 HA已登入 tailnet 的裝置私有存取公開埠口與不必要的公開分享
管理設備Machines 清單與個人帳號共用管理員帳密
存取家中 LAN單一已核准 subnet route未盤點就宣告多段子網

完成前的安全檢查

檢查登入 Tailscale 的帳號是否正確、Home Assistant 是否仍以獨立個人帳號管理、以及 Machines 清單有沒有陌生或已淘汰的裝置。權限設計採最小權限：需要連 HA 的人才取得路徑，需要管理 tailnet 的人才有管理主控台權限。

注意：不要在 issue、群組或截圖公開授權網址、auth key、tailnet 網域、完整 IP、裝置序號或原始日誌。

用兩個網路情境驗收

  1. 家中網路

    在本地 LAN 開啟 HA，確認既有帳號與儀表板沒有因本章設定受到影響。

  2. 不同網路

    讓測試手機改用行動網路或另一個安全網路，先確認 Tailscale 已連線，再完成一次 HA 存取。若本章是路由設定，僅測試你有權管理的目標。

  3. 記錄結果

    記下成功／失敗、使用的裝置與時間。這比日後只記得「以前可以」更容易定位問題。

  4. 停在安全邊界

    本教程不包含 exit node、DNS override 或公開 Funnel 設定；沒有需求就保持停用。

把這次設定留下可交接的記錄

網路設定最怕「當時能用，但沒人記得為什麼」。完成本章後，請在自己的密碼管理器或案場維護文件記下日期、操作者、目的、變更前後狀態與驗證裝置。記錄不是要保存密碼、auth key 或完整私有網段；這些機密應留在受控的祕密管理工具，文件只放能讓下一位維護者理解決策的描述。

例如可以寫：「2026-08-19，由管理者確認 Home Assistant Machine 仍在指定 tailnet；以受管理筆電在非家用網路測試私有存取成功。」若是 subnet router，再記下「僅宣告已核准的單一 LAN CIDR，且由管理主控台核准」，不要把住址、客戶姓名、完整 Tailscale 網域或裝置識別碼寫入公開 repo。這樣在手機遺失、換路由器、App 更新或管理權交接時，才能判斷要回復哪一層。

該記下不應放進公開文件下次誰會用到
變更目的、日期、驗證結果帳密、auth key、OAuth 授權連結HA 維護者
Machine 的用途與擁有者角色完整 tailnet 網域與私有 IPTailscale 管理員
核准哪一個「用途明確」的子網未遮罩 CIDR、掃描結果、住址網路維護者
最小變更原則：一次只改一項，做完從另一個網路測試，再把結果記下。這比同時切換路由、policy、DNS 與公開分享更能保留可回復性。

常見問題先這樣排

  • 找不到 Apps：確認你的 HA 安裝方式是否由 Supervisor 管理；Container/Core 不能照本教程的 App 路徑操作。
  • Machines 沒有 HA：回 App Web UI 完成授權，然後查看 App 日誌，而不是反覆重裝。
  • 可以看 Machines 但打不開 HA：先確認客戶端已登入同一 tailnet，再檢查 HA 的登入帳號與網址。
  • 路由看起來存在但 LAN 不通：確認該 route 已在 Machines 的 route settings 核准；再以正確 CIDR 與有權限的目標測試。
  • 設定後變得不確定：回到上一個已知可用狀態，保留日誌與變更記錄，再一次只改一項。

FAQ

我需要公開路由器埠口嗎？
本教程的私有 tailnet 流程不要求你為 HA 建立公開 port forwarding；請依自己的網路與資安政策評估。
Tailscale 會取代 Home Assistant 登入嗎？
不會。Tailscale 管理網路路徑；Home Assistant 仍應使用個人帳號、強密碼與適當的管理權限。
看到舊名稱 Add-on 怎麼辦？
HA 介面與翻譯可能因版本而不同；認出 Tailscale App、Info、Configuration、Log 與 Web UI 等功能，再以目前畫面和官方文件為準。
可以順便設定 exit node 或 DNS override 嗎？
本教程刻意不含這些進階範圍。先把私有 HA 存取與單一 subnet route 驗證完成，再依官方文件另行規劃。

官方來源與版本提示

本文以 Home Assistant Community App: Tailscale 文件與 Tailscale Docs為準。介面文字會隨 App 與管理主控台版本調整；遇到名稱不同時，優先依畫面與官方文件操作。