Docker 部署：十分钟跑起来

为什么从 Docker 开始

如果你家里已经有一台常开的 NAS 或者软路由，那么 Docker 部署 HA 是成本最低、速度最快的入坑方式：不用买新硬件，不用刷系统，拉一个镜像起来就开始用。对于本站读者——大多已经跟着自建 NAS 完全指南装好了 NAS、或者按软路由入门指南折腾过软路由——这几乎应该成为默认选项，而不是先去买新机器。

本篇假设你已经有基本的 Docker 使用经验（会用命令行或容器管理界面拉镜像、映射端口、挂载目录），整个过程大概十分钟，比装一个常用软件还快。如果你完全没有 Docker 基础，也不用慌，照着步骤一步步来，每条命令都有解释；真的不想碰命令行的话，下一篇讲的 HA OS 路线更适合你，那是全程图形化的体验。本篇的操作环境以常见的 Linux 宿主机为例，群晖、威联通等 NAS 的容器管理界面只是操作形式不同，参数一一对应。

Docker 部署五步走

第一步：准备配置目录

HA Container 启动时需要一个空目录来存放配置文件，这个目录会跟着 HA 用一辈子——配置、数据库、备份全都在这里，将来换机器搬家也是拷它。建议放在有冗余的存储上，比如 NAS 的数据盘，而不是随便一个临时分区。

以 Linux 为例，约定俗成的位置是 /config 或 /homeassistant 之类的路径，名字随意，只要你记得住。给目录设置好权限，容器里的进程要以普通用户身份读写它，权限没设对是新手部署失败的头号原因。如果你是在群晖上操作，建议放在 Docker 共享文件夹下，方便在 File Station 里随时查看，具体操作可参考群晖 DSM 实用指南。目录命名没有硬性要求，但一旦定下来就别再改，compose 文件、备份脚本、定期清理任务全都会引用它，改一次要牵一发动全身。

一个常见的目录规划：

子内容 说明 备注
configuration.yaml 主配置文件 可以全程界面操作，也可以手写
home-assistant.db SQLite 历史数据库 越用越大，定期维护
backups/ 备份文件存放处 建议再同步到别处
.storage/ 界面写回的配置 尽量别手动动它

第二步：写 docker-compose 文件

用 compose 文件管理容器是最推荐的做法——它把启动参数写成一个文件，将来重建、迁移都是一条命令的事。下面是一份可直接照抄的最小配置（字段含义在表后解释）：

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - /你的配置目录:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped
    privileged: true
    network_mode: host

几个关键字段的含义：

字段 作用 注意事项
image 镜像地址，stable 为稳定版 想跟测试版可换 tag
volumes 把宿主目录挂进容器 配置目录必须挂载
TZ 时区，影响历史记录和日出日落 写成你所在时区
restart 宿主机重启后自动拉起 建议 unless-stopped
network_mode host 模式让容器用宿主网络 发现局域网设备需要它
privileged 特权模式 接 USB 协调器需要，纯云设备可去掉

这里最容易被问倒的是 network_mode 为什么选 host：HA 需要在局域网里发现设备（HomeKit、Matter 的配对都依赖组播），桥接网络会让发现机制失效。如果你用群晖的 Container Manager 或 Portainer 图形界面操作，道理一样，记得开 host 网络。

关于 image 标签多说一句：stable 是官方维护的稳定版，适合绝大多数人；latest 未必等于稳定版，新手别图 latest 这个名字。要不要持续更新是后面的事，第一台机器先求稳。

第三步：拉起容器

在 compose 文件所在目录执行：

docker compose up -d

第一次拉镜像需要一点时间，取决于你的网络。拉完之后容器会在后台运行，这时候打开浏览器访问 http://宿主主机内网IP:8123，能看到 HA 的欢迎界面就算部署成功了。如果打不开，按这个顺序排查：容器是否在运行、8123 端口是否被占用、配置目录权限是否正常。查看容器实时日志的命令是 docker compose logs -f，绝大多数启动报错都会直接印在里面，学会看日志比到处问人快得多。

部署后的访问链路

常见踩坑清单

部署环节的失败原因翻来覆去就那么几个，提前记住能少走弯路。下面这份清单按出现频率从高到低排，遇到问题照着对：

  • 端口被占用：8123 被别的服务抢走，表现为页面打不开或容器日志里端口绑定失败，要么换端口要么停掉冲突服务。
  • 权限不对：容器内部无法写配置目录，表现为无限重启或启动日志报错，给目录赋权限即可。
  • 时区没设：历史记录的时间和自动化里的时间全错。TZ 一定要设对，否则日出日落功能也会跟着错位，天黑自动开灯这种规则就全废了。
  • 网络模式用了 bridge：设备发现功能部分失灵，HomeKit 集成死活搜不到设备，这是最隐蔽的一个坑，容器明明跑着却以为集成坏了。
  • 镜像拉不下来：换镜像源或者给 Docker 配代理，网上的方案很多，不属于本书范围。
  • 宿主机一重启容器没起来：restart 策略没配，记得设 unless-stopped，停电一次就明白了。

部署失败原因分布

部署完成的自检

容器跑起来之后，别急着接设备，先花两分钟做一组自检，后面会省掉很多莫名其妙的坑：

  1. 打开页面能正常加载，说明端口和权限都正常。
  2. 在关于页面里确认时区显示正确，说明 TZ 生效。
  3. 尝试发现一次局域网设备（比如添加集成时搜索 HomeKit），说明 host 网络生效。
  4. 重启一次容器，配置不丢、页面还能打开，说明挂载生效。

这四步都通过，你这个 HA 就算站稳了。接下来要做的第一件事不是接灯，而是跟着下一篇把形态选择这事想清楚——Docker 部署虽然快，但它的能力边界你得心里有数。

之后的事情

容器跑起来只是开始，第一次打开的初始化向导（建用户、设位置）在「首次配置」那篇会细讲。这里先提醒两件 Docker 部署特有的事：

第一，Container 形态没有 Add-on 商店，所有周边服务（MQTT 代理、代码编辑器等）都要你在宿主机或其它容器里自行解决——这点在「配置目录与 Add-on 商店」那篇会展开。别等到要用的时候才发现商店里空空如也，那不是坏了，是本来就没有。

第二，升级的时候不要直接在容器里改东西，正确流程是先备份配置目录，再拉新镜像重建容器。数据都在挂载的目录里，重建不会丢配置，但养成先备份的习惯是长命百岁的关键。

什么情况下应该换个部署方式

Docker 路线虽好，也不是所有人都适合。如果你对下面几个问题默默点了头，下一篇的 HA OS 方案值得多看两眼：

  • 家里没有常开的 NAS 或软路由，Docker 部署的前提本来就不成立。
  • 你想用 USB Zigbee 协调器，但宿主机环境对 USB 直通支持很差。
  • 你对周边服务（Node-RED、代码编辑器等）有强需求，Add-on 商店一键安装的诱惑更大。
  • 你希望连备份、恢复、系统更新都由一套完整流程包办，不想自己维护这些脚本。

反过来，如果你机器现成、动手能力在线、追求资源占用小，Docker 部署就是最优解。两种形态之间没有高下，只有匹配度——下一篇会把两种形态放在一起仔细对比，帮你把这件事彻底定下来。

Docker 部署的两面性

延伸阅读