4、Home Assistant Core 容器部署：用 Docker Compose 搞定一切

好，咱们继续。上一章我们把 Docker 环境搭好了，现在要动真格的了——把 Home Assistant Core 跑起来。

你可能会问：为什么非要用 Docker Compose？直接 docker run 不香吗？

嗯，我刚开始也这么想。后来在项目里维护了七八个容器，每次升级都要敲一堆参数，烦得不行。Docker Compose 说白了就是个「一键部署脚本」，把配置写进 YAML 文件里，以后想改什么，改一行就行。

4.1 准备工作：先想清楚目录结构

我个人习惯，所有容器数据都放在 /opt/docker 下面。这样备份、迁移都方便。你想想看，要是每个容器都随便扔个目录，时间长了你自己都找不到。

我建议这样规划：

/opt/docker/
├── homeassistant/
│   ├── config/        # Home Assistant 配置目录
│   ├── docker-compose.yml
│   └── .env           # 环境变量文件（可选）

为什么要单独建一个 config 目录？因为 Home Assistant 的所有配置、数据库、日志都写在这里。以后升级容器，只要这个目录在，配置就不会丢。

我的小习惯： 在 /opt/docker 下再建一个 backup/ 目录，每周定时把 config 打包备份。别问我为什么，问就是吃过亏。

4.2 编写 docker-compose.yml

好，开始写核心文件。先创建目录：

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

然后新建 docker-compose.yml，内容如下：

version: '3.8'

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro  # 如果你要用蓝牙
    network_mode: host
    environment:
      - TZ=Asia/Shanghai
    privileged: false

这里有几个关键点，我得跟你掰扯清楚：

配置项 说明 我的建议
network_mode: host 使用宿主机网络，容器直接占用宿主机 IP 智能家居场景强烈推荐，避免端口映射的麻烦
volumes 挂载目录，config 是核心 时区和 dbus 也挂上，省得后面折腾
restart: unless-stopped 容器挂了自动重启 比 always 更灵活，手动停止后不会自动重启
privileged: false 不开启特权模式 安全第一，除非你明确知道需要什么权限
注意： 使用 network_mode: host 后，Home Assistant 会占用宿主机 8123 端口。如果你宿主机上已经有其他服务在用这个端口，会冲突。我在项目中遇到过两次这种情况，最后只能换端口或者停掉其他服务。

4.3 首次启动：见证奇迹的时刻

文件写好了，启动就一行命令：

docker compose up -d

等等，先别急着敲。我建议你先检查一下：

  1. 当前目录对不对？ 确保你在 /opt/docker/homeassistant 下
  2. docker-compose.yml 有没有语法错误？ 可以用 docker compose config 验证
  3. 端口 8123 有没有被占用？ ss -tlnp | grep 8123

确认没问题，再执行启动命令。你会看到类似这样的输出：

[+] Running 2/2
 ✔ Network homeassistant_default  Created
 ✔ Container homeassistant        Started

嗯，这里要注意：第一次启动会拉取镜像，大概 200MB 左右，取决于你的网速。我当年在树莓派上第一次部署，等了快十分钟，还以为死机了。

查看启动日志：

docker compose logs -f

看到类似 Starting Home Assistant Core 和 Home Assistant Core is running! 就说明成功了。

4.4 初始化配置：走进 Home Assistant 的世界

打开浏览器，访问 http://你的树莓派IP:8123。你会看到一个初始化向导页面。

这个过程很简单，跟着走就行：

  1. 创建账号： 设置用户名和密码。我建议用强密码，因为 Home Assistant 会暴露在局域网里
  2. 设置家庭名称： 比如「我的家」或者「Smart Home」
  3. 选择时区： 默认应该已经识别到了，确认是 Asia/Shanghai
  4. 选择单位： 公制（摄氏度、米）

完成之后，你会进入主界面。嗯，这时候可能有点懵——空空如也，啥都没有。

别急，这才是开始。Home Assistant 默认只加载了核心组件，你需要自己添加设备、集成、自动化。

初始化完成后，我建议你立刻做三件事：

  • 进入「配置」→「系统」→「日志」，看看有没有报错
  • 进入「配置」→「系统」→「存储」，确认配置目录挂载正常
  • 备份 /opt/docker/homeassistant/config 目录，这是你的救命稻草

4.5 避坑指南：我踩过的那些坑

说实话，Home Assistant 的容器部署本身不难，但有几个坑我不得不提：

  • 权限问题： 如果你发现 Home Assistant 无法访问某些设备（比如 USB 传感器），很可能是容器内用户权限不够。我曾经折腾了一下午，最后发现是 /run/dbus 没挂载。
  • 网络模式： 如果你用了 bridge 模式而不是 host，会发现很多设备发现不了。因为 mDNS 广播在 bridge 网络里传不过去。
  • 升级问题： 别手贱直接 docker compose pull 然后 up -d。我建议先备份 config 目录，再看 release notes，确认没有 breaking changes 再升级。
一个小技巧： 如果你不确定当前配置对不对，可以用 docker compose config 命令。它会解析你的 docker-compose.yml，输出最终生效的配置。我每次改完文件都会跑一遍这个命令，省得启动时报错。

4.6 验证部署：确认一切正常

最后，我们做几个快速验证：

# 查看容器状态
docker compose ps

# 查看资源占用
docker stats homeassistant --no-stream

# 测试配置文件是否可写
docker compose exec homeassistant touch /config/test.txt

如果一切正常，你会看到容器状态是 Up，CPU 和内存占用都很低（刚启动时可能稍高）。

好，到这里，Home Assistant Core 的容器部署就完成了。下一章我们会聊怎么配置网络和存储，让 Home Assistant 真正融入你的家庭网络。

记住：容器只是载体，真正的魔法在配置里。别急，咱们一步步来。

← 上一章 📖 返回目录 下一章 →