问题

尝试通过 Home Assistant 的 HomeKit Bridge 将 HA 接入 iOS「家庭」App。

使用 HA 后台提供的二维码进行配对时：

  • iPhone 可以正常扫描二维码
  • 但「家庭」App 提示 未找到配件
  • 当时无法完成 HomeKit 配对

环境

  • Home Assistant：Docker
  • Home Assistant 镜像：homeassistant:2025.11.3
  • Ubuntu Server
  • iPhone / iOS
  • Home Assistant 已通过 MQTT 与 ESP32 正常通信
  • HA 可以正常接收到 ESP32 发布的温度数据

排查

1. 检查 HA Docker 网络模式

执行：

docker inspect ha --format '{{.HostConfig.NetworkMode}}'

发现：

bridge

原 HA 使用 Docker 默认的 bridge 网络。

HomeKit Bridge 的设备发现依赖局域网 mDNS，而 Docker bridge 网络可能导致 HomeKit 的 mDNS 发现无法正常工作。

2. 检查 HA /config

发现原 HA 容器：

docker inspect ha --format '{{json .Mounts}}'

返回：

[]

说明 /config 没有挂载到宿主机，而是直接存储在容器内部。

因此在修改网络配置、重建 HA 容器之前，先备份 /config。

备份：

mkdir -p ~/homeassistant-config-backup
docker cp ha:/config/. ~/homeassistant-config-backup/

备份成功：

Successfully copied 62.5MB

3. 重建 HA

将原 /config 复制到宿主机：

~/homeassistant/config/

重新创建 HA 容器，并修改网络模式：

network_mode: host

同时将配置目录挂载：

volumes:
  - /home/<用户>/homeassistant/config:/config

并设置：

restart: unless-stopped

原来的 HA 容器暂时保留，新的容器命名为：

ha2

4. 检查新 HA

新容器：

ha2    homeassistant:2025.11.3    Up

日志没有出现导致 HA 无法启动的错误。

原有配置成功继承：

  • HA 正常打开

  • ESP32 温度信息继续更新

  • 原有 HA 配置正常

  • MQTT 通信正常

5. 再次尝试 HomeKit

修改为：

HA
 ↓
Docker host network
 ↓
局域网 mDNS
 ↓
iPhone Home

之后 HomeKit 成功连接。

原因

推测原因：Docker 默认 bridge 网络导致 HomeKit Bridge 的 mDNS 发现无法正常工作。

将 HA 改为：

network_mode: host

后解决。

解决方案

对于 Docker 部署的 Home Assistant，如果 HomeKit Bridge 扫描二维码后提示：

未找到配件

优先检查 Docker 网络模式：

docker inspect ha --format '{{.HostConfig.NetworkMode}}'

如果为：

bridge

可以考虑改为：

network_mode: host

同时确保 HA 的 /config 使用宿主机目录挂载，而不是存储在容器内部。

额外发现

原 HA 容器的配置没有挂载到宿主机：

Mounts: []
Binds: null

这会导致 HA 配置与容器生命周期绑定。

因此重新部署时顺便改为：

宿主机
~/homeassistant/config/
        ↓
Docker
/config

并设置：

restart: unless-stopped

使 HA 在 Docker / Ubuntu 重启后自动恢复。

相关命令

检查网络：

docker inspect ha --format '{{.HostConfig.NetworkMode}}'

检查挂载：

docker inspect ha --format '{{json .Mounts}}'

备份 HA 配置：

docker cp ha:/config/. ~/homeassistant-config-backup/

查看 HA 日志：

docker logs ha --tail 50

状态

已解决 ✅

HomeKit 已成功连接 HA，iPhone 可以正常使用 HomeKit/Siri 控制 HA 中的设备。