核心是确保网络通、设备认得、配置落得实：需挂载/config目录实现持久化，用host网络模式支持mDNS/SSDP自动发现，privileged权限直通USB设备，并通过docker-compose一键启停与更新。
用 Docker 部署 Home Assistant 作为智能网关，核心是让 HA 容器能稳定访问本地网络设备、直连 Zigbee/Z-Wave 等硬件，并对外提供统一控制入口。关键不在“装上”，而在网络通、设备认得、配置落得实。
准备持久化配置目录
Home Assistant 的所有配置、插件、数据库和日志都存在 /config 目录下，必须挂载到宿主机才能长期使用：
- 新建目录（例如）：
mkdir -p ~/homeassistant/config - 首次启动前保持该目录为空——容器会自动初始化一套最小可用配置（
configuration.yaml、secrets.yaml等） - 已有旧配置？直接复制进去即可，注意保留文件权限（尤其
.storage和 SQLite 数据库文件）
用 docker-compose 启动容器（推荐）
在项目根目录新建 docker-compose.yml，内容如下：
version: '3.8'
services:
homeassistant:
container_name: homeassistant
image: "ghcr.io/home-assistant/home-assistant:stable"
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
privileged: true
network_mode: host
devices:
- "/dev/ttyACM0:/dev/ttyACM0" # Zigbee USB 棒（按实际路径调整）
- "/dev/ttyUSB0:/dev/ttyUSB0" # 其他串口设备
重点说明：
-
privileged: true：启用设备直通、系统时间同步、网络栈操作等必要权限 -
network_mode: host：跳过端口映射，HA 直接监听宿主机 8123 端口，支持 mDNS、SSDP 自动发现（对米家、苹果 HomeKit、飞利浦 Hue 等集成至关重要） -
devices：仅当接入 Zigbee/Z-Wave 网关时添加；用dmesg | grep tty查看设备名，避免写错
启动与验证是否真正跑通
执行命令启动：
docker-compose up -d
等待 1–3 分钟后，在浏览器打开 http://[宿主机IP]:8123：
- 看到初始化向导页面 → 表示容器已运行、Web 服务就绪
- 卡在白屏或 502 错误 → 查日志：
docker-compose logs -f homeassistant，常见原因：配置语法错误、USB 设备权限不足、时区未设导致初始化阻塞 - 进去了但找不到设备 → 检查是否用了
host网络模式，以及智能设备是否和宿主机在同一局域网段
后续维护要点
日常操作不复杂，但几个细节容易忽略：
-
更新版本：只需两步：
docker-compose pull && docker-compose up -d -
备份配置：压缩整个
~/homeassistant/config目录即可（不含数据库时通常不到 5MB） -
添加 HACS 或自定义组件：放入
config/custom_components/子目录，改完configuration.yaml后重启容器生效 - USB 设备热插拔失效？：确认宿主机 udev 规则是否允许当前用户访问串口（Linux/macOS），Windows 用户需确保驱动正确且 Docker 使用 WSL2 后端
