Home Assistant Docker Compose 升级失败排查：镜像、备份和设备映射

环境和现象

测试环境使用 Docker Compose 运行 Home Assistant Container。升级到 2026.5.x 后，docker compose up -d 能把容器拉起来，但页面访问不稳定，移动端偶尔连不上，Zigbee 网关也出现离线。

这类问题不要直接重装。建议按下面顺序排查：

镜像是否拉取成功，版本是否一致。
/config 是否完整，备份是否可恢复。
USB 设备映射是否变化。
Home Assistant 日志是否卡在迁移或第三方集成。
反向代理和 App 访问是否正常。

1. 单独验证镜像

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 '{{.RepoTags}} {{.Id}} {{.Created}}'

这里使用 ghcr.1ms.run 是为了先验证镜像入口。镜像层能稳定拉下来之后，再继续看配置、设备和代理。

如果是生产或长期运行环境，不建议长期只写 stable。升级前可以记录 digest，或者临时固定版本 tag，避免多台机器拉到不同镜像。

2. 备份 Compose 和配置目录

升级前先保存当前 Compose 渲染结果：

bash 复制代码

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

不要只备份 configuration.yaml。Home Assistant 的很多状态在 .storage、数据库文件和集成目录里。容器无法启动时，页面备份入口可能也用不了，所以文件级备份很关键。

3. 推荐 Compose 片段

下面是一个更容易排查的 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

关键点：

network_mode: host 能减少局域网发现类问题。
配置目录固定为 ./config:/config。
USB 网关用 /dev/serial/by-id/，不要依赖 /dev/ttyUSB0 这种易变路径。
升级前先确认 by-id 路径真实存在。

bash 复制代码

ls -lah /dev/serial/by-id/
docker exec -it homeassistant ls -lah /dev/ttyUSB0

4. 日志和端口检查

容器状态为 running 不代表服务 ready。先看日志：

bash 复制代码

docker logs -f --tail=200 homeassistant

再看本机端口：

bash 复制代码

curl -I http://127.0.0.1:8123

常见分支：

日志/现象	处理方向
数据库迁移持续输出	等待迁移完成，避免频繁重启
某个 custom component 报错	先禁用该组件，再启动核心服务
Web 能开，设备不可用	查 USB 映射和集成权限
本机能开，外网不能开	查反代、证书、WebSocket

5. 反向代理检查

如果使用 Nginx Proxy Manager、Caddy 或 Traefik，外网访问异常不一定是 Home Assistant 本体失败。

bash 复制代码

curl -I http://127.0.0.1:8123
curl -I "$HA_PUBLIC_URL"  # 换成你的外部访问地址
docker logs --tail=100 npm

检查项：

上游地址是否仍然指向 127.0.0.1:8123 或正确内网地址。
WebSocket 是否被代理。
证书是否过期。
trusted_proxies 是否和当前反代地址一致。

6. 回滚流程

如果确认需要回滚，按镜像和配置两条线走：

bash 复制代码

cd /opt/home-assistant
docker compose down
cp backups/compose-2026-05-22-0700.lock.yml compose.yml
rm -rf config
tar -xzf backups/ha-config-2026-05-22-0700.tgz
docker compose pull
docker compose up -d
docker logs -f --tail=200 homeassistant

回滚后再按顺序验证：

bash 复制代码

curl -I http://127.0.0.1:8123
ls -lah /dev/serial/by-id/
docker compose ps

总结

Home Assistant Docker Compose 升级失败，通常不是单点问题。镜像、配置目录、设备映射、启动迁移、反向代理都要拆开看。

毫秒镜像适合解决第一层的 GHCR 镜像拉取验证；后面几层仍然要靠备份、设备路径、日志和代理配置来兜底。升级前把 Compose 和 /config 备好，回滚会轻很多。