Home Assistant 完整教學 2026：9 萬星開源智慧家庭中樞，HAOS／Docker 安裝、Zigbee 與 Matter 設定、自動化 YAML 到能源儀表板一次學會

Home Assistant（以下簡稱 HA）是一套在地優先（local-first）的開源智慧家庭中樞：所有自動化都跑在你自己的機器上，不依賴廠商雲端。它由 Open Home Foundation 維護，GitHub 已累積約 9 萬顆星，最新穩定版為 2026.9.4（2026-09-27 釋出），官方維持每月一次大版本更新。

對台灣的自架玩家來說，它幾乎是唯一能把小米、Aqara、IKEA、Philips Hue、Matter 裝置全部收進同一個介面，而且斷網照樣運作的選擇。

一、Home Assistant 是什麼？先搞懂三件事

1. 它是中樞，不是裝置。 HA 本身不發無線訊號，它負責整合。你原有的 Wi-Fi 裝置、Zigbee 燈泡、藍牙溫濕度計，都透過各自的「整合（Integration）」進入 HA。
2. 它是 Python 專案。 後端 Python 3、前端 Polymer，由 Paulus Schoutsen 於 2013 年創立，現由 Open Home Foundation 治理。原生支援超過 1,500 種裝置整合，社群外掛（HACS）更是數千個。
3. 它是一個平台，有四種裝法。 這是新手最常卡關的地方——HAOS、Container、Supervised、Core 不是「版本」，而是四種完全不同的架構，選錯會讓後面每一步都痛苦。

二、跟 Apple Home、Google Home 差在哪？

關鍵差異不是「誰的 App 好看」，而是誰擁有你的自動化邏輯。雲端平台一旦停止服務或改變政策，你的燈光情境就跟著消失；HA 的邏輯存在你自己的 YAML 檔裡。

反過來說，HA 也能用 HomeKit Bridge 或 Matter 把裝置「分享」給 Apple Home 與 Google Home，等於兩邊都要。

三、四種安裝類型完整對照（最重要的一張表）

一句話建議：

• 想要「裝好就忘了它」→ HAOS（含官方預裝機 Home Assistant Green）。
• 已經有一台跑 Docker 的 NAS 或 Proxmox 主機 → Container，但你會失去 Add-on 商店，MQTT、Node-RED、Matter Server 全都要自己起容器。
• Supervised 的實際意義是「不要碰」：官方要求底層必須是 Debian 12，隨手裝了第三方套件就會被判定 Unsupported／Unhealthy，從此無法升級。除非你有明確理由，否則別選。

四、安裝實戰：三條路

路線 1：Home Assistant Green（零組裝）

插電 → 接網路線 → 瀏覽器打開 http://homeassistant.local:8123 → 建立帳號。就這樣，這是給不想碰任何指令的人。

路線 2：HAOS 燒錄（樹莓派 / x86 迷你電腦）

1. 從官方網站下載對應硬體的 HAOS image。
2. 用 Balena Etcher 或 Raspberry Pi Imager 燒到 SD 卡／SSD／USB。
3. x86 機器需進 BIOS 開 UEFI、關 Secure Boot。
4. 開機後在區網連 http://<IP>:8123。

硬體建議：樹莓派最低 2GB RAM 可跑，但請務必用 SSD 而非 microSD——HA 的資料庫寫入頻繁，SD 卡是最常見的陣亡原因。若之後想跑本機 AI 推論或影像分析，直接上 x86 Mini PC 會舒服很多。

路線 3：Docker（Container 模式）

先建目錄：

mkdir -p ~/homeassistant && cd ~/homeassistant

最短的 docker run 版本（Linux）：

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Asia/Taipei \
  -v ~/homeassistant:/config \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

用 Docker Compose 管理更清楚（compose.yml）：

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

啟動並確認：

docker compose up -d && docker ps

兩個實務提醒：

• 要接 USB 協調器（Zigbee／Z-Wave）時，必須把裝置傳進容器，建議用 by-id 路徑避免重開機後編號跳掉：-v /dev/serial/by-id/usb-XXXX:/dev/ttyUSB0。
• network_mode: host 只在 Linux 有效。macOS／Windows 的 Docker Desktop 不支援，這種情況請改用 HAOS 虛擬機，不要硬撐。

五、Add-on 與 HACS：官方與社群的分界線

六、無線協定與對應硬體

ZHA 還是 Zigbee2MQTT？ 一句話：裝置少、想省事 → ZHA；裝置多、要細部調校、或想混用不同品牌 → Zigbee2MQTT。 兩者都吃同一支協調器，日後也能遷移（需要重新配對）。

七、自動化：Trigger → Condition → Action

HA 的自動化永遠是這三段式：

• Trigger（觸發）：時間、日落、感測器狀態變化、按鈕按下…
• Condition（條件，可選）：只在符合時才繼續，例如「有人在家」、「太陽已下山」。
• Action（動作）：開燈、發通知、呼叫服務。

UI 編輯器很好用，但底層存的就是 YAML。以下是可以直接抄的範例——日落時開客廳燈，且只有有人在家才執行：

alias: "日落時自動開啟客廳燈光"
description: "當太陽落下且有人在家時開啟客廳燈"
trigger:
  - platform: sun
    event: sunset
    offset: "-00:30:00"   # 日落前 30 分鐘
condition:
  - condition: numeric_state
    entity_id: zone.home
    above: 0               # 家裡至少有一個人
action:
  - action: light.turn_on
    target:
      entity_id: light.living_room
    data:
      brightness_pct: 60
mode: single

幾個小技巧：

• offset 可以讓你在日落「前後」觸發，比死板的固定時間好用。
• mode: single 避免重複觸發時疊加執行；需要排隊可改 queued。
• 想快速除錯，把 action 先換成 persistent_notification.create，確認觸發與條件都對，再換成真正的控制指令。

八、能源儀表板（Energy Dashboard）

到 設定 → 儀表板 → 能源 設定後，HA 會自動畫出電網進出、太陽能發電、電池存量的流向圖，也能追蹤單一家電耗電。

需要的硬體依你想看什麼而定：

• 全戶用電：智慧電表或全屋功率監測器。若感測器只給瞬時功率（W），可用 Riemann sum 積分轉成累計 kWh。
• 太陽能／電池：變流器（Inverter）提供的即時資料。
• 個別家電：具備計量功能的智慧插座。

這是 HA 最有「回本感」的功能：很多人裝完才發現某台老舊除濕機的電費有多誇張。

九、備份與更新

• HAOS／Supervised 內建備份功能，可一鍵產生包含 Core 設定、Add-on 資料與系統快照的完整備份。
• 鐵則：每次大版本升級前先做一次完整備份。 社區型 Add-on 有時會跟不上新版本。
• 備份不要只留在同一台機器上——可以搭配 Google Drive Backup 之類的 Add-on 做異地備援，或至少定期把備份檔抓下來。
• Container 使用者請直接備份 config 目錄，並記得把 secrets.yaml 一起帶走。

十、5 個新手最常踩的坑

1. Recorder 資料庫膨脹。 HA 預設把所有實體狀態變化寫進資料庫。高頻感測器（每秒更新那種）沒排除掉，資料庫會肥到拖垮整台機器——記得在 recorder 設定裡 exclude 這類 entity。
2. 用 microSD 卡跑樹莓派。 這是經典死法，換 SSD 幾乎能解決所有「莫名當機、SD 卡讀寫錯誤」。
3. 把 8123 port 直接開在公網。 絕對不要。正確做法是 VPN（Tailscale／WireGuard）或帶 SSL 的反向代理，或直接用 Nabu Casa 雲端服務。
4. 在 Ubuntu 之類的非指定系統上裝 Supervised。 會直接進入 Unsupported／Unhealthy，之後無法升級，白忙一場。
5. 想在電腦瀏覽器配對 Matter 裝置。 不行，一定要手機 Companion App 開藍牙。

結語：為什麼值得花一個週末

HA 的學習曲線確實比其他平台陡，但換來的是你真正擁有自己的智慧家庭：斷網照跑、邏輯在自己手上、裝置不必挑特定品牌，而且從 Zigbee 燈泡到自製 ESP32 感測器都能收進同一個儀表板。

建議的入門順序很簡單：先用 HAOS 或 Docker 把中樞架起來 → 接進 2～3 個現有裝置 → 寫第一個日落自動化 → 有感覺了再買 Zigbee 協調器擴編。不要第一天就買十顆感測器。

原始來源

• Home Assistant 官方安裝指南
• Home Assistant Container 安裝（官方）
• HAOS 與 Container 差異（官方 FAQ）
• Matter 整合說明（官方）
• home-assistant/core — GitHub（約 9 萬星、Apache-2.0）
• Home Assistant: Complete Getting-Started Guide (2026)

站內延伸閱讀

• Xiaomi Home：小米官方開源 Home Assistant 外掛
• Tailscale 完整教學 2026：36K 星 WireGuard Mesh VPN，從安裝、MagicDNS 到遠端連回家中自架服務
• Cloudflare Tunnel 完整教學 2026：不開防火牆 port 也能把自架服務搬上網
• ESP32 x AI Vibe Coding 入門：用 Claude Code 打造你的第一個智慧硬體專案