Add-on 與 Docker 架構

為什麼要搞懂 Add-on 底下那層

你在附錄 A已經知道 Add-on 商店在哪、怎麼按安裝。那一篇是「會用」，這一章是「知道它為什麼會壞」。

差別在哪？舉幾個真實會發生的狀況：

• 你在筆電上裝了 Home Assistant，結果左邊選單根本找不到 Add-on 商店 —— 不是你手殘，是安裝方式不對。
• 你裝了 Zigbee2MQTT，它一直起不來，頁面只寫「已停止」。你不知道要去哪看它到底在抱怨什麼。
• 你同時裝了 Node-RED 和另一個網頁工具，第二個死活起不來 —— 兩個搶同一個門牌號碼。
• 你把整台機器重灌了，才發現備份全都躺在那台已經死掉的機器裡。

這四件事的解法，全部藏在同一層知識裡：Add-on 是容器、容器有映像檔、有資料卷、有連接埠、有記錄檔。看完這章，你遇到上面任何一種狀況，都知道第一步該點哪裡。

四種安裝方式，和「有沒有 Add-on 商店」的關係

這是新手最大的一個坑：不是每一種 Home Assistant 都有 Add-on 商店。有沒有商店，在你當初決定怎麼安裝的那一刻就註定了，之後不能靠設定打開。

所以結論很簡單：

• 你想要 Add-on 商店 → 裝 HAOS。Green、Yellow、樹莓派燒官方映像檔、或是一台空的迷你主機裝 HAOS，都可以。
• 你用 Container（例如群暉 NAS 上的 Docker）→ 沒有商店，永遠不會有。需要 MQTT broker、Node-RED 這些東西，就自己另外開一個 Docker 容器來跑，功能一樣，只是要自己動手。

Add-on 的本質：一個被 Supervisor 管起來的 Docker 容器

官方開發文件寫得很直白：Apps（也就是舊稱的 Add-on）底層就是發佈到容器登錄檔（container registry）的容器映像檔，來源例如 GitHub Container Registry 或 Docker Hub。

換句話說，當你在商店裡按「安裝」，發生的事情是：

1. Supervisor 去網路上抓映像檔

   它看那個 Add-on 的設定檔，知道要去哪個網址、抓哪個版本、抓對應你 CPU 架構（arm64 或 amd64）的那一份。這一步最花時間，也最容易因為網路不通而失敗。

2. Supervisor 用那份映像檔開一個容器

   順便照 Add-on 的設定，決定要開哪些連接埠、要把哪些資料夾掛給它、要不要給它 USB 裝置。

3. Supervisor 幫你把設定介面接進 Home Assistant

   所以你才會在 Home Assistant 網頁裡看到那個 Add-on 的「設定」分頁、「記錄檔」分頁，而不用自己去打 Docker 指令。

4. Supervisor 持續盯著它

   它負責啟動、停止、更新、看門狗（Watchdog）重啟、開機自動啟動。這些就是你在 Add-on 頁面上看到的那幾個開關。

所以 Supervisor 就是「管家」。Home Assistant 本體是一個容器，每個 Add-on 各自也是一個容器，Supervisor 站在旁邊管所有人的生死。這也解釋了為什麼 Container 安裝沒有商店 —— 它根本沒有管家，只有 Home Assistant 自己一個容器孤零零地跑著。

Docker 白話版：一家便當店

Docker 的名詞聽起來很硬，但其實每一個都對應得到日常生活。我們把它想成一家連鎖便當店。

如果你是 Container 安裝的使用者，官方文件給的 Docker Compose 範例長這樣，正好把上面幾個名詞全部串起來：

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

對照一下：image 是調理包、volumes 是保鮮盒（左邊是你電腦上的資料夾，右邊是容器裡看到的路徑）、restart 是開店規定、TZ 是時區（第 2 章那個時區設定，在這裡也要對）。network_mode: host 表示它直接用主機的網路，所以連接埠 8123 就直接開在你機器上。

動手：裝一個 Add-on 並看懂每個開關

我們用「檔案編輯器（File editor）」當練習，因為它輕、無害、而且之後很好用。

1. 打開商店

   左下角設定 → 找到 Apps（2026.2 之前叫 Add-ons）。進去之後按安裝 App（Install app）按鈕，就會看到整排可以裝的東西。舊版上這顆按鈕寫的是「ADD-ON STORE」。

   

   

2. 找到「File editor」並安裝

   它在官方（Official）那一區。點進去按安裝，然後就是等。第一次安裝要下載映像檔，樹莓派上花個三五分鐘很正常，畫面沒動不代表當掉。

3. 先別急著啟動，看一下那四個開關

   安裝完會出現幾個切換開關：開機時啟動（機器重開後自動跑）、看門狗 Watchdog（它掛掉時自動把它拉起來）、自動更新（有新版就自己更新）、顯示在側邊欄（左邊選單直接出現捷徑）。檔案編輯器建議：前三個都開，第四個也開。

4. 按「啟動」

   狀態會從「已停止」變成「執行中」。如果變成「已停止」又跳回去，就是它啟動失敗了 —— 這時候直接跳到下一節去看記錄檔。

5. 從側邊欄開它

   左邊選單應該多了一個「File editor」。點進去，你會看到 /config 資料夾 —— 那就是上一節講的「保鮮盒」，你的 configuration.yaml 就在裡面。

6. 試著改一個字再改回來

   不是要你改設定，是要你確認「我真的能寫入」。改完存檔，再改回原樣。這一步做過，將來真的需要編設定檔時你就不會怕。

Add-on 頁面的分頁各是幹嘛的

每個 Add-on 點進去，上面會有幾個分頁。名字依版本略有差異，但功能大同小異：

看記錄檔排錯：三個關鍵字就夠

記錄檔（Log）看起來像亂碼，但你不需要全部看懂。你要做的只有三件事：

1. 從最下面往上看

   記錄檔是由上往下按時間排的，最新的在最下面。它為什麼掛掉的原因，通常就在最後那五到十行。上面幾百行開機訊息可以全部無視。

2. 找這幾個字

   ERROR、FATAL、Traceback、Permission denied、Address already in use、No such file or directory。看到其中一個，那一行前後就是答案。WARNING 通常可以先忽略。

3. 把那一行原文拿去搜尋

   連同 Add-on 名字一起搜，例如「zigbee2mqtt Address already in use」。不要用自己的話描述，直接複製那行英文，找到答案的機率高十倍。

4. 還是沒頭緒就重看一次

   把 Add-on 停掉，重新整理記錄檔頁面，再按啟動，然後盯著它。這樣看到的就是「乾淨的一次啟動」，比在幾千行舊訊息裡撈快得多。

對照一下常見訊息的中文意思：

必裝 Add-on 巡禮

不用全裝。看你要做什麼，對著挑。「來源」欄的意思：官方＝商店裡本來就有；社群＝要先加第三方存放庫（下一節教）。

加第三方存放庫：商店裡沒有的怎麼辦

商店預設只有官方那幾十個。像 Node-RED、Studio Code Server、Zigbee2MQTT 這些，要先把它們的「存放庫（Repository）」加進去，商店才會多出一整排新東西。

1. 複製存放庫網址

   常用的兩個：社群 Add-on 大集合是 https://github.com/hassio-addons/repository，Zigbee2MQTT 官方的是 https://github.com/zigbee2mqtt/hassio-zigbee2mqtt。

2. 進入 Add-on 商店

   設定 → Apps，然後按安裝 App（Install app）進到商店。

3. 打開右上角三點選單裡的「存放庫（Repositories）」

   官方文件寫得很清楚：在商店頁面右上角的三點選單選Repositories。舊版可能顯示中文「存放庫」，是同一個東西。

4. 貼上網址、按新增，然後重新整理

   加完商店會多出好幾區。找不到新東西就按 Ctrl + F5 強制重新整理一次。重整還是沒出現，就去設定 → 系統 → 記錄檔，右上角切到 Supervisor，那裡會寫網址是不是打錯了。

備份自動上傳雲端：讓備份離開這台機器

備份怎麼建、排程怎麼設、保留幾份、為什麼不能只存本機，第 9 章已經講完了，這裡不重複。

這一節只補第 9 章沒細講、又剛好跟本章有關的一件事：把備份送上雲端這件事，現在完全內建，不需要裝任何 Add-on。以前這是第三方 Add-on 的地盤，現在備份頁面的「位置（Location）」可以同時勾好幾個地方，每次備份自動送到每一處。各個目的地的差別在這裡 —— 尤其是那些會咬人的限制：

接一個雲端目的地上去，只有三步：

1. 先把目的地接進來

   有 Nabu Casa 訂閱的話什麼都不用做，它本來就在。沒有的話去設定 → 裝置與服務 → 新增整合，裝 Google Drive 或 OneDrive，跟著畫面走一次帳號授權。要用家裡 NAS 的話走另一條路：設定 → 系統 → 儲存空間加一個網路儲存，並標記它可以用來放備份。

2. 回備份頁面把它勾起來

   設定 → 系統 → 備份，在自動備份設定的「位置（Locations）」裡，把剛接好的目的地打開。排程和保留份數照第 9 章設就好。本機 /backup 記得也留著：還原時本機那份快很多，雲端是機器整台死掉時的保命符。

3. 手動跑一次，然後親眼去雲端看檔案在不在

   這步不能跳，沒有驗證過的備份等於沒有備份。真的去 Google Drive 或 OneDrive 的資料夾裡看到那個檔案，才算設定完成。如果你選的是 Home Assistant Cloud，這時就會撞到 5GB 上限 —— 傳不上去的話，回備份設定把媒體（media）資料夾取消勾選，那通常是最肥的一塊，瘦身效果最好。

資源占用：低階硬體怎麼取捨

每個 Add-on 都是一個真的在跑的程式，會吃 CPU、吃記憶體、吃硬碟。樹莓派 4 的 2GB 版本、或是老舊的迷你主機，裝著裝著就會開始卡 —— 網頁變慢、自動化延遲、更新失敗。官方沒有公布每個 Add-on 吃多少資源，下面這張表是相對的輕重分級，不是實測數字，拿來排優先順序用。

幾條實用原則：

• 用不到的就移除，不要只是停用。停用的 Add-on 還是占著硬碟空間。
• 一次只裝一個新東西。裝完觀察一兩天再裝下一個，出事你才知道是誰害的。
• 樹莓派請用 SSD 或 USB 開機，不要用 SD 卡。SD 卡最容易掛的原因就是被寫太多次，而資料庫類的 Add-on 專門幹這件事。
• 先看內建功能能不能解決。很多人裝 Node-RED 只為了做一個「日落開燈」，那件事內建自動化三行就搞定了（見第 8 章）。

常見卡關

1. 找不到 Add-on 商店

   先確認你是哪種安裝方式：設定 → 系統 → 修復（Repairs），點右上角的三點選單 → 系統資訊（System information），裡面會寫你這台到底是 OS 還是 Container。如果是 Container 或 Core，那就是結構上沒有商店，怎麼找都不會有，唯一解是改用 HAOS 重裝（記得先備份，再從備份還原）。如果你是 HAOS 卻找不到某個特定 Add-on，例如 Terminal & SSH，那多半是進階模式沒開 —— 點左下角你的名字進入個人資料頁，把「進階模式（Advanced Mode）」打開。

2. Add-on 裝不起來，卡在安裝中或直接失敗

   九成是下載映像檔失敗。依序檢查：(1) 網路通不通，Home Assistant 出得去外網嗎；(2) 硬碟還有空間嗎，看設定 → 系統 → 儲存空間；(3) 你的 CPU 架構有沒有對應版本 —— 冷門 Add-on 常常只出 amd64，樹莓派裝不了，這種會直接說找不到映像檔。先重試一次，第一次失敗有時候只是抓到一半斷線。

3. Port 衝突：第二個 Add-on 起不來

   記錄檔會出現 Address already in use 或 port is already allocated。去那個 Add-on 的網路分頁，把右邊那格改成一個沒人用的號碼（例如原本 1880 改成 1881），存檔重啟。改完之後你連它的網址也要跟著改成新號碼。如果你根本不需要從外面連它，右邊直接留空，衝突瞬間消失。

4. 更新之後起不來了

   先看記錄檔最後幾行，作者常常會直接寫「這版設定格式改了，請把某某選項改成某某」。如果看不懂，最快的路是用更新前的備份還原（第 9 章）—— 這就是為什麼「更新前先備份」那個開關要打開。另外去設定 → 系統 → 修復（Repairs）看看，重大變更常常會在那裡留一張說明卡。

   

5. 磁碟空間不足

   症狀是各種奇怪的失敗，記錄檔裡有 No space left on device。清理順序：(1) 刪掉舊備份，這通常最肥；(2) 移除（不是停用）用不到的 Add-on；(3) 檢查 media 和 share 資料夾裡有沒有堆積的錄影檔；(4) 資料庫太大的話，調整 Recorder 保留天數。做完前三項還是滿，就該考慮換更大的儲存裝置了。

6. Add-on 一直反覆重啟

   狀態在「執行中」和「已停止」之間跳，通常是看門狗（Watchdog）在把一個本來就會壞的程式反覆拉起來。先把看門狗關掉，讓它安靜地停在失敗狀態，這樣你才看得到完整的錯誤訊息。修好之後再打開。

7. Zigbee2MQTT 找不到 USB 棒

   記錄檔通常是 No such file or directory。去設定 → 系統 → 硬體，點右上角三點選單 → 全部硬體（All Hardware），就會列出目前接上的裝置與它們的路徑，找出那根棒子的路徑複製回 Zigbee2MQTT 的設定裡。不要照抄網路教學上的路徑，每台機器不一樣。另外官方建議優先用 /dev/serial/by-id/ 開頭的那個長路徑，不要用 /dev/ttyUSB0 這種短的 —— 短路徑會隨插拔順序和重開機而變，長路徑綁在裝置本身，插哪個孔都不會跑掉。

常見問題