Docker 容器化部署 Home Assistant

适用场景

已经有一台跑 Docker 的服务器（Unraid、TrueNAS、Synology DSM 7+、Proxmox、独立 Linux）
不想被 Home Assistant OS 的 Supervisor 框架限制
需要和其他服务共用硬件资源

前置条件

Linux 系统（Docker 官方支持的发行版：Ubuntu、Debian、Fedora、CentOS 等）
Docker 引擎已安装（docker --version 能输出版本号）
Docker Compose v2 已安装（可选，推荐用 compose 文件管理）
至少 2GB RAM（Home Assistant 容器本身吃 300~500MB）

创建配置目录

Home Assistant 的所有配置、实体状态、自动化定义都存在宿主机的一个目录里。建议创建一个专门目录：

mkdir -p /opt/homeassistant/config
cd /opt/homeassistant

方式一：docker run（快速启动）

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v /opt/homeassistant/config:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

参数说明：

参数	作用
`--privileged`	让容器能访问 USB Zigbee/Z-Wave 适配器
`--restart=unless-stopped`	Docker 重启或服务器重启后自动拉起
`-e TZ=Asia/Shanghai`	设置时区，影响自动化中的时间条件
`-v /opt/homeassistant/config:/config`	挂载配置目录到容器内
`-v /run/dbus:/run/dbus:ro`	可选，让 Home Assistant 监听宿主机的 DBus 事件
`--network=host`	重要：容器直接用宿主机网络，避免端口映射问题

方式二：docker compose（推荐）

创建 docker-compose.yml：

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    privileged: true
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
      - /run/dbus:/run/dbus:ro
    network_mode: host

启动：

docker compose up -d

首次访问

容器启动后（首次启动大约 1~3 分钟，因为要初始化数据库和安装 Python 依赖），浏览器打开：

http://<服务器IP>:8123

USB 适配器透传

如果你用 --network=host + --privileged，USB 设备会自动被容器识别。可以进容器验证：

docker exec -it homeassistant ls /dev/ttyUSB*

如果能看到 /dev/ttyUSB0 等设备，就可以在 ZHA 集成里直接选择。

备份与迁移

容器化的备份就是备份 /opt/homeassistant/config 目录。迁移到另一台机器：

停止容器：docker stop homeassistant
把 config/ 目录打包复制到新服务器
在新服务器上跑同样的 docker run 或 docker compose up -d
启动完成

常见问题

Synology DSM 7+ 上部署

DSM 7+ 有官方 Home Assistant DSM 套件，在套件中心搜索即可。套件底层就是 Docker 容器，Synology 帮你处理了端口映射和 USB 透传，不需要手动敲命令。

容器启动后 CPU 100%

首次启动时 Home Assistant 会扫描网络、初始化数据库，CPU 高占用是正常的。等几分钟就会回落。

更新到新版本

docker pull ghcr.io/home-assistant/home-assistant:stable
docker compose up -d

Docker 会拉取新镜像并重启容器，/config 目录里的数据不会丢。