Home Assistant 升级翻车：一套 Docker Compose 回滚清单

这两年很多自托管服务都变成了"看起来只是一个容器，实际上挂着一堆状态"。Home Assistant 尤其明显：配置目录、数据库、Zigbee 网关、蓝牙、反代、移动端访问都在同一条链上。

我今天想写的不是新功能介绍，而是一套升级前后都能用的回滚清单。场景很具体：Docker Compose 跑 Home Assistant Container，升级到 2026.5.x 后，容器 running，页面不稳定，设备集成也有离线。

先把升级拆成五个断点

断点	典型问题	处理动作
镜像	GHCR 拉取慢、不同机器版本不一致	单独 `pull`，记录 tag/digest
配置	`/config` 不完整、`.storage` 损坏	整目录备份，不只备份 YAML
设备	Zigbee/蓝牙路径变化	使用 `/dev/serial/by-id`
启动	数据库迁移、组件加载失败	跟日志，先隔离 custom component
访问	App/外网打不开	单独查反代、WebSocket、证书

这个拆分的价值是：你不会在代理问题上重装容器，也不会在设备路径变化时回滚整个系统。

镜像层先单独验证

Home Assistant Container 的上游镜像在 GHCR。对国内环境来说，升级当天把镜像层独立出来很有必要：

bash 复制代码

docker pull ghcr.1ms.run/home-assistant/home-assistant:stable
docker image inspect ghcr.1ms.run/home-assistant/home-assistant:stable \
  --format '{{.Id}} {{.Created}}'

这里用毫秒镜像只是为了把 GHCR 拉取这层先跑通。它解决不了坏配置，也不会帮你修 USB 设备映射。镜像层过了，后面继续排。

升级前我会先留三份东西

bash 复制代码

cd /opt/home-assistant
mkdir -p backups
docker compose ps > backups/compose-ps-$(date +%F-%H%M).txt
docker compose config > backups/compose.lock.yml
tar -czf backups/config-$(date +%F-%H%M).tgz config

这三份东西分别用于：

证明升级前哪些容器在跑。
还原最终 Compose 配置。
恢复 Home Assistant 状态目录。

很多自托管事故的难点不是"没有教程"，而是没有现场。升级前把现场留住，回滚才会像工程操作，而不是猜。

Compose 里最容易忽略的是设备

如果接了 Zigbee 网关，不建议写 /dev/ttyUSB0。这个路径重启后可能变化。

bash 复制代码

ls -lah /dev/serial/by-id/

Compose 里更稳的写法：

yaml 复制代码

services:
  homeassistant:
    image: ghcr.1ms.run/home-assistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/serial/by-id/usb-xxx:/dev/ttyUSB0
    restart: unless-stopped

升级后如果设备离线，但 Web 页面能开，优先查这条线。别一上来就删配置、重装集成。

容器 running 以后继续看 ready

Docker 的 running 只是进程状态，不是业务状态。

bash 复制代码

docker compose ps
docker logs -f --tail=200 homeassistant
curl -I http://127.0.0.1:8123

如果日志在数据库迁移，给它时间。频繁 down/up 可能让现场更乱。

如果日志指向某个 custom component，先禁用组件再启动核心服务。Home Assistant 的第三方生态很丰富，但升级时也意味着更多兼容性变量。

回滚按两条线走

真正要回滚时，我会先回 Compose 和配置目录：

bash 复制代码

cd /opt/home-assistant
docker compose down
cp backups/compose.lock.yml compose.yml
rm -rf config
tar -xzf backups/config-2026-05-22-0700.tgz
docker compose pull
docker compose up -d

启动后再看：

bash 复制代码

docker logs -f --tail=200 homeassistant
curl -I http://127.0.0.1:8123
ls -lah /dev/serial/by-id/

如果本机 8123 正常，外网域名不正常，那就是代理层继续排，不要把锅重新甩回 Home Assistant。

小结

Home Assistant 升级不是一次简单的 docker compose pull && docker compose up -d。它更像一次带状态服务的小发布。