Docker部署Home Assistant最稳定易维护，核心三步：装Docker、建配置目录、运行容器；需注意平台差异、路径规范、镜像源配置及host网络模式等关键细节。
用 Docker 部署 Home Assistant（HA）是目前最稳定、易维护的方式。核心就三步：装好 Docker、准备好配置目录、跑起容器——不需要编译、不污染系统，重启或升级都只需几条命令。
环境准备与镜像拉取
确保 Docker 已安装并运行正常（docker --version 和 docker info 可验证）。不同平台注意细节：
- Windows/macOS：用 Docker Desktop，安装时勾选 WSL2（Win11）或 Hyper-V（Win10），并在设置中配置国内镜像源（如阿里云：
https://.mirror.aliyuncs.com） - Linux（含树莓派）：建议用非 root 用户加入
docker组，避免每次输sudo；ARM 设备直接拉ghcr.io/home-assistant/home-assistant:stable，会自动适配架构 - 群晖/爱快等 NAS 或软路由：确认已启用 Docker 套件，存储建议单独划出 ≥10GB 分区（如
/mnt/docker），避免和系统盘混用
配置目录与启动方式
Home Assistant 的所有配置、插件、数据库都存在 /config 目录下，必须做持久化映射：
- 新建空目录，例如：
mkdir -p ~/homeassistant/config（Linux/macOS）或D:\ha_config（Windows） - 路径不能含中文、空格或特殊符号，否则容器可能启动失败
- 首次启动时容器会自动生成默认
configuration.yaml等文件，无需手动创建 - 已有旧配置可直接复制进去，注意保留文件权限（Linux/macOS 下推荐用
cp -a）
运行容器（推荐 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"
- "/dev/ttyUSB0:/dev/ttyUSB0"
说明：
-
privileged: true是关键，用于访问 USB 设备（Zigbee/Z-Wave 棒）、调整系统时间、使用主机网络等 -
network_mode: host让 HA 直接使用宿主机网络，省去端口映射，也利于 mDNS 自动发现设备 -
devices行按实际插入的 USB 棒路径添加，可用dmesg | grep tty（Linux）或设备管理器（Windows）确认 - Windows 用户若用
docker run启动，需加-e TZ=Asia/Shanghai -p 8123:8123替代 host 网络
启动、访问与日常维护
执行 docker-compose up -d 后等待 2–5 分钟（首次初始化较慢），浏览器打开 http://[宿主机IP]:8123 即可进入设置向导。
- 查看日志排错：
docker-compose logs -f homeassistant，常见问题包括配置语法错误、USB 设备权限不足、时区未设 - 更新版本：
docker-compose pull && docker-compose up -d - 备份配置：压缩整个
config目录即可（不含数据库时通常仅几 MB，适合 Git 或 NAS 定期存档） - 如需 HACS（Home Assistant Community Store），首次进后台后在「配置 → 设备与服务」里搜索添加即可，无需额外容器
