HomeKit Bridge 完整設定：把 Home Assistant 的裝置送進 iPhone「家庭」App

charles

這篇的內容（8 段）

1. 步驟 1：確認網路條件
2. 步驟 2：建立第一座橋
3. 步驟 3：配對
4. 步驟 5：收斂實體數量
5. 步驟 7：超過 150 個配件就拆橋
6. entity_config 的 type 能填什麼
7. 換主機或重灌時保住配對
8. 症狀對照表

做完這一篇，你的 iPhone「家庭」App 裡會多出一台叫 Home Assistant Bridge 的配件，
底下掛著你挑選過的燈、開關、窗簾、感測器；攝影機和門鎖會以獨立配件的形式各自出現。

先說三條會咬人的規則，不先知道的話你會在第四步或第七步整個重來：

• 一座橋最多 150 個配件，這是 HomeKit 協定（HAP）的硬限制，不是建議值
  
• 攝影機、門鎖、支援「活動」的遙控器、電視型媒體播放器，不能放進橋裡，
  必須各自開一個 accessory 模式的實例
  
• 在介面上建立的橋，就只能在介面上改。拿 configuration.yaml 去改它，
  結果不是改到，而是「多開一座在別的埠上的橋」
  

步驟 1：確認網路條件

HomeKit 靠 mDNS（區域網路的裝置探索）找到你的橋，這一關不過的話後面全部免談。

要做的事：

• iPhone 和 Home Assistant 必須在同一個子網路。有分 VLAN 或訪客網路的話，兩邊要放在一起，或是設定 mDNS 轉發
  
• Home Assistant 主機如果有防火牆，開 UDP 5353（mDNS）與 TCP 21063（HomeKit 預設埠）
  
• 用 Docker 跑 Home Assistant 的話，要用 host 網路模式
  

Docker Compose 的寫法：

1. services:
2.   homeassistant:
3.     container_name: homeassistant
4.     image: ghcr.io/home-assistant/home-assistant:stable
5.     volumes:
6.       - /opt/homeassistant/config:/config
7.       - /etc/localtime:/etc/localtime:ro
8.     restart: unless-stopped
9.     privileged: true
10.     network_mode: host

複製代碼

你會看到什麼：在 Mac 或 Linux 上執行下面這行，Home Assistant 一啟動 HomeKit 就會出現在清單裡。

1. # macOS
2. dns-sd -B _hap._tcp
4. # Linux（要先裝 avahi-utils）
5. avahi-browse -rt _hap._tcp

複製代碼

正常會看到類似這樣的一行：

1. Timestamp     A/R Flags if Domain  Service Type   Instance Name
2. 12:01:33.412  Add     3  6 local.   _hap._tcp.     Home Assistant Bridge XXXX

複製代碼

這裡什麼都沒出現，代表 mDNS 沒通，通常是 VLAN 或 Docker bridge 網路造成的，
先把這關解決，不要往下走。

非 host 網路又非改不可的情況：在 Docker 主機上跑 avahi-daemon 的 reflector 模式，
然後在 Home Assistant 的設定裡指定要對外宣告哪個 IP：

1. # configuration.yaml
2. homekit:
3.   - name: HA Bridge
4.     advertise_ip: "192.168.1.50"     # 換成 Docker 主機的實體 IP

複製代碼

步驟 2：建立第一座橋

這一步有兩條路，選一條，之後就一直走那條。

路 A：介面（適合只想挑實體、不需要細調的人）

設定 → 裝置與服務 → 新增整合 → 搜尋 HomeKit Bridge。

接著會問你要用「包含」還是「排除」模式，以及要選哪些網域。
第一次建議這樣選：

• 模式選 包含（include）
  
• 網域勾 light、switch、cover、climate、fan
  
• 感測器先不要勾，第五步再用清單一個一個加
  

路 B：YAML（需要 entity_config 的人只能走這條）

只要你想幫某個實體改顯示名稱、改配件型別、綁電池感測器，
就一定要用 YAML 建立這座橋 —— 介面建的橋沒有這些選項。

在 configuration.yaml 的最外層（不要縮排在任何東西底下）加：

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

登入繼續閱讀使用 Google 登入