Home Assistant 容器版跨版本升级：四阶安全平跳十三期迭代
跨越十三期的技术债务
在使用独立 Docker 容器（homeassistant/home-assistant）运行 Home Assistant 作为机房环境动力监控、UPS 电力遥测与自动化告警中枢时，系统更新无法依靠面板里的一键按钮完成。每一次升级，都需要运维人员手动更新镜像标签、重建容器并监控首次启动时的数据库迁移流程。
在实际生产环境中，一套长期稳定运行的系统停留在 2025.9.4 版本长达十三个月，而官方最新版已经推进至 2026.10.4。面对整整 13 个大版本的跨度，如果直接拉取最新镜像盲跳启动，极易引发严重故障：
- 单向不可逆的数据库迁移：系统自带的 Recorder 历史记录组件在这期间完成了 SQLite Schema 50 至 53 的重大架构变更。一旦跨版本迁移途中因超时断电中断，数据库将陷入不可读死锁。
- 底层 Python 运行时更迭：基础镜像由 Python 3.13 升级到 3.14，引入了更严苛的异步语法限制，旧组件中的废弃 API 会导致配置加载直接报红。
- 2026.8 反向代理配置大变动：官方在 2026.8 重构了网络安全子系统，将反代信任参数纳入
.storage/http内部存储中。若迁移不当，反向代理接入将全量报HTTP 400: Bad Request。
为了彻底消除隐患，必须将漫长的跨度拆解为四级平稳阶梯。
隔离风险的四阶升级阶梯
官方文档通常建议单次跨越不超过 5 至 6 个小版本。经过研判，确立了如下四个独立验收的升级阶段：
| 阶梯 | 目标版本镜像 | 重点隔离的架构风险 | 验收门禁 |
|---|---|---|---|
| 1 | 2025.12.5 | 隔离 SQLite recorder 模式升级（v50 → v53） | 数据库模式就绪，WAL 归一无损 |
| 2 | 2026.3.4 | 隔离 Python 3.13 → 3.14 运行时与 zstd 镜像层 | 查看容器日志：0 个 Setup failed |
| 3 | 2026.8.3 | 隔离 http: trusted_proxies 校验与 .storage/http 配置迁移 | 反向代理标头验证通过，返回 200 |
| 4 | 2026.10.4 | 落地当前最新稳定版，完成旧版认证组件清理 | 基线 259 个实体与传感器全部在线 |
在启动升级前，先停止正在运行的容器，对挂载的 /config 目录进行冷备份，确保持久化数据库和 WAL 文件绝对一致。
🔍 docker-compose.yml — Home Assistant 容器生产配置（14 行）
services:
homeassistant:
container_name: home-assistant
image: homeassistant/home-assistant:2026.10.4
volumes:
- /volume1/docker/home-assistant/config:/config
- /etc/localtime:/etc/localtime:ro
environment:
- TZ=Asia/Kuala_Lumpur
network_mode: host
restart: unless-stopped
stop_grace_period: 60s特别注意 stop_grace_period: 60s 的设定：当 SQLite 数据表较大时，Home Assistant 在收到退出信号后需要数十秒将内存缓冲区与 WAL 日志写回磁盘。Docker 默认的 10 秒超时往往会触发内核 SIGKILL 强制杀进程（Exit Code 137），造成数据库锁损坏。
结果
四阶升级全部顺利执行完毕，无一例回滚：
- 实体完整性：实体总数由基线的 259 个无缝扩展至 265 个（新增 6 个为官方新版内置的电能监控统计），零配置报错，零传感器掉线。
- 记录器健康：数据库无缝完成迁移，耗时不到 1 秒，历史数据行数从 249,875 行平稳增长至 249,897 行。
- 反代网关稳固：上游反代网关继续维持单点登录保护，
X-Forwarded-For传递被系统精准信任，外部访问完全恢复顺畅。
🛡️ 生产级基础设施与系统架构
服务器频繁异常重启、云账单过高，或缺一位能穿透内核日志的架构师？
真正的生产环境稳定性，靠的是穿透表象抓出根因。我独立管理着跨 3 台物理/云主机、162 个容器的高可用自托管生产网络。
