使用Docker部署Home Assistant简单可靠，核心是用官方镜像启动容器并正确挂载配置目录与设备权限；推荐docker-compose方式，需配置volumes、privileged、host网络及USB设备映射，首次启动自动初始化配置。

使用Docker部署Home Assistant简单可靠，适合长期运行且便于备份升级。核心是用官方镜像启动容器，并正确挂载配置目录与必要设备权限。

准备基础环境

确保已安装 Docker 和 Docker Compose（推荐方式）。Linux 系统建议使用非 root 用户加入 docker 组，避免每次执行 sudo；树莓派等 ARM 设备需拉取对应架构镜像（如 ghcr.io/home-assistant/home-assistant:stable 自动适配）。

创建配置目录并初始化

Home Assistant 需要持久化存储配置、插件和日志：

• 新建目录：mkdir -p ~/homeassistant/config
• 首次启动后，容器会自动生成默认配置文件（configuration.yaml、secrets.yaml 等），无需手动创建
• 若已有旧配置，可直接复制到该目录（注意保留文件权限）

运行容器（推荐 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/Z-Wave USB棒
      - "/dev/ttyUSB0:/dev/ttyUSB0"

说明：

• privileged: true：启用设备直通和部分系统权限（如访问 USB、调整时间、网络模式等）
• network_mode: host：避免端口映射问题，让 HA 直接使用宿主机网络（默认监听 8123 端口）
• devices：按实际设备路径添加 Zigbee/Z-Wave 棒，可通过 dmesg | grep tty 查看接入设备名

启动与日常维护

执行以下命令即可启动：

• docker-compose up -d 后等待 1–2 分钟，浏览器访问 http://[宿主机IP]:8123
• 查看日志：docker-compose logs -f homeassistant，排查启动失败原因（常见为配置语法错误或设备权限不足）
• 更新版本：docker-compose pull && docker-compose up -d
• 备份配置：定期压缩 ~/homeassistant/config 目录即可（不含数据库时体积小，适合 Git 或 NAS 存档）

不复杂但容易忽略的是设备节点权限和首次配置生成时机——只要 config 目录为空，容器启动后会自动初始化一套最小可用配置，之后再修改 configuration.yaml 并重启服务即可生效。