Docker部署HomeAssistant：HACS与Zigbee/MQTT接入

智能家居折腾到第三年，我最深的体会是：买设备不难，难的是让这些设备真的听你的话。厂商 App 装了一屏，设备之间互不相识，想做个"人走灯灭、开门亮灯"的联动，得在四五个 App 里来回跳。真正把局面盘活的，是一套跑在 Docker 里的 HomeAssistant，再配上 HACS 这个扩展生态入口，最后把家里的 Zigbee、MQTT、局域网设备一批批接进来。这套组合我前后搭过五六次，从树莓派到小主机到群晖再到 Windows 上的 Docker Desktop，踩过的坑基本能写一本小册子。这篇就按我实际部署的顺序，把 Docker 装 HomeAssistant、装 HACS、再接入设备这三段讲透，包含完整配置、参数取舍理由和排查清单。适合刚入门想自建智能家居中枢的朋友，也适合已经跑起来但被实体失联、数据库膨胀、USB 掉线折磨过的人。

1. 整体方案设计与选型思路拆解

1.1 为什么把 HomeAssistant 塞进 Docker 里跑

先聊一个很多人跳过的前置问题：HomeAssistant 官方其实提供了好几种安装形态，HAOS 整机镜像、Supervised 托管版、Core 容器版、还有直接 pip 装。我最终长期用的是 Core 的容器版，原因很实在。

HAOS 是一套完整系统，刷进去整个机器就交给它了，对小白最友好，自带 Supervisor、加载项商店、备份系统，插上就能跑。但它对硬件的要求是"独占"，你没法在这台机器上再跑个下载器、跑个相册备份。而且 HAOS 的加载项本质也是容器，等于多了一层封装，出问题时排查链路变长——你得先怀疑加载项、再怀疑 Supervisor、最后才怀疑核心。

Core 容器版就干净得多。整个 HomeAssistant 就是config目录里的一堆文件，配上几个容器的编排。好处有三个：一是升级回滚极其简单，镜像 tag 写死版本号，出问题改一行切回去；二是宿主资源可以复用，我这台小主机同时跑着 MQTT broker、Zigbee2MQTT、数据库和一个下载器，互不干扰；三是迁移方便，整个config目录打包拷走，换台机器五分钟恢复。

代价也要说清楚：Core 版没有加载项商店，所有附加服务（MQTT、Node-RED、数据库）都得自己写进 compose 文件管理。没有 Supervisor 就没有一键备份，得自己做备份脚本。如果你完全不想碰命令行，HAOS 更省心；但只要你能读懂 YAML，Core 版的灵活度会让你回不去。

我这里的建议很明确：主机上还有别的用途、或者想深入学习容器编排的，选 Core；只想有个能用的中枢、设备量在 30 个以内的，直接上 HAOS，别给自己加难度。

1.2 HACS 到底解决什么问题

HACS 全称 Home Assistant Community Store，翻译过来就是社区商店。它不是 HomeAssistant 的官方组件，但几乎成了事实标准。为什么必须装？因为官方核心自带的集成虽然越来越多，但大量设备、卡片、主题、自动化模板仍然散落在社区仓库里，靠手动 git clone 再改目录，维护起来是灾难。

HACS 干的事可以类比成手机的应用商店：它维护一份社区仓库清单，负责下载、更新、版本管理。你装上它之后，接入一个冷门品牌的设备、装一套漂亮的仪表盘卡片、换个夜间主题，都在界面里点几下完成，不用再去翻命令行。

有几个认知要提前纠正，不然容易走弯路。第一，HACS 分两类东西：集成（Integration）和前端资源（Frontend）。集成改变的是 HomeAssistant 的能力边界，比如接入新的设备协议，装完必须重启核心；前端资源改变的是界面长相，装完刷新浏览器就生效，不需要重启。很多人装完卡片发现没效果，就是因为没去浏览器里强刷缓存。

第二，HACS 只负责下载，不负责配置。它把文件放到custom_components目录里，但集成怎么连、填什么参数，还是得去"设置 - 设备与服务 - 添加集成"里走一遍。新手最常见的困惑是"我装完了怎么没反应"，答案通常就在这一步。

第三，HACS 本身也是一个自定义集成，所以它的安装方式和普通集成不一样——它是"用来装集成的集成"，得手动放一次文件，之后才能靠它自己更新自己。

1.3 硬件、系统与网络的前置盘点

开机之前先把家底盘清楚，这一步能省掉后面一半的返工。

硬件方面，HomeAssistant Core 本身很轻，1 核 1G 能跑，但它周边的服务才是吃资源的。我的经验值是这样：20 台设备以内，2 核 2G 够用；50 台设备加摄像头、再加数据库，建议 4 核 4G 起步，存储留 32G 以上。存储介质优先 SSD，因为 recorder 数据库会持续写盘，用 SD 卡跑一年大概率会写坏。小主机（N100、J4125 那类）是性价比最高的选择，二手价便宜、功耗低、x86 架构镜像兼容性最好。

架构要特别注意。x86_64（amd64）是支持最完整的，ARM64 次之，ARMv7 又次之。如果你用的是龙芯或者国产 ARM 平台，务必先确认镜像有没有对应架构的构建，否则拉镜像会直接报no matching manifest。这个报错很常见，看到就知道是架构不匹配，不是网络问题。

网络方面，最理想的是给主机一个固定的局域网地址。有两种做法：路由器里做 DHCP 静态绑定（按 MAC 地址固定），或者在系统里配静态 IP。我更推荐前者，改起来不用进系统。为什么必须固定？因为设备发现、手机 App 连接、摄像头流地址、自动化里的回调，全都依赖这个地址，它一变，半个系统就瘫了。

还有一个容易被忽略的点：如果你的主机有两个网口或者既有有线又有无线，务必确认 HomeAssistant 走的是哪个网段。我曾经因为容器走了无线、设备在有线网段，折腾了两个小时才发现是跨网段组播被路由器拦了。

2. Docker 环境搭建与 HomeAssistant 容器部署

2.1 不同平台的 Docker 安装路径选择

安装 Docker 这一步，不同平台的差别挺大，我按常见场景分开说。

Linux 上最省事，用官方提供的一键脚本，或者按官方文档加软件源再装。这里有个小建议：如果你的系统是 Debian 系，装完记得把当前用户加进 docker 组，命令是sudo usermod -aG docker $USER，然后退出重新登录。不然每次敲 docker 命令都要加 sudo，很容易在写脚本时埋下权限隐患。另外国内拉取镜像有时会比较慢，可以在/etc/docker/daemon.json里配置可用的镜像加速地址，配置完systemctl daemon-reload && systemctl restart docker生效。

Windows 和 macOS 上，默认路径是 Docker Desktop。Windows 版有个坑必须提前说：它默认用 WSL2 后端，而 WSL2 的网络是 NAT 模式。这意味着容器里的 mDNS 组播出不去，Chromecast、HomeKit、DLNA 这类靠组播发现的设备基本找不到。解决办法有两条：一是在 Docker Desktop 设置里打开主机网络相关选项（新版本支持较完善），二是把 HomeAssistant 跑在 WSL2 里直接配置网络模式。说实话，如果你的主力机是 Windows 又想做正经的智能家居中枢，我更建议单独弄一台 Linux 小主机，别在 Windows 上硬扛。

macOS 的 Docker Desktop 问题更根本：它本身是跑在虚拟机里的，USB 直通基本没法用，Zigbee 网关插上去容器是看不见的。所以 Mac 只适合做开发调试，长期跑不建议。

如果你用的是群晖、威联通这类 NAS，它们自带 Container Manager（旧版本叫 Docker 套件），图形界面创建容器完全够用。需要注意的是 NAS 上的 Docker 版本可能偏旧，compose 文件的某些新语法可能不支持，遇到报错时先降级语法试试。

2.2 compose 文件逐行拆解与参数取舍

环境好了，接下来是核心的编排文件。我直接给一份用了很久的配置，然后逐行讲为什么这么写。

services: homeassistant: container_name: homeassistant image: ghcr.io/home-assistant/home-assistant:stable volumes: - ./config:/config - /etc/localtime:/etc/localtime:ro - /run/dbus:/run/dbus:ro restart: unless-stopped privileged: true network_mode: host environment: - TZ=Asia/Shanghai

先说image。我写的是stable，意思是稳定通道的最新版。但我更推荐生产环境写死具体版本号，比如2024.6.3。原因很实际：HomeAssistant 每月发版，新版本偶尔会改集成行为，某个自定义集成还没来得及适配，升级完就报错。写死版本号，升级变成一次有意识的操作而不是自动行为，回滚也就是改一行。

volumes三项各有用途。./config:/config是全部家当，配置、数据库、自定义组件、日志都在里面，绝对不要用匿名卷，否则哪天容器删了配置就找不回来。/etc/localtime只读挂载是为了让容器时间和宿主一致，时区错了会导致自动化在错误的时间触发，这个坑很隐蔽。/run/dbus是给蓝牙用的，宿主跑了 BlueZ 之后，挂载它容器里才能用蓝牙适配器。

privileged: true是争议最大的一项。它给了容器近乎宿主 root 的权限，安全上确实不理想。但如果你要直通 USB 设备、用蓝牙、或者跑某些需要访问硬件的集成，它就是最省事的方案。折中做法是去掉 privileged，改用devices:显式映射，比如- /dev/ttyUSB0:/dev/ttyUSB0，权限最小化。我是这么配的：只跑纯粹网络设备时不开特权，需要 Zigbee 网关时再补 devices 映射。

network_mode: host我认为是必须的。桥接模式下容器有独立 IP，设备发现要靠组播，桥接网络默认不转发组播，结果就是设备搜不到。host 模式让容器直接用宿主网络栈，mDNS、SSDP 全部正常。代价是端口不再隔离，但 HomeAssistant 用 8123，冲突概率很低。

restart: unless-stopped保证宿主机重启后容器自动起来，除非你手动停过。这个策略比always更符合直觉。

2.3 首次启动、初始化与目录结构说明

文件写好后，在同一个目录执行启动命令：

docker compose up -d docker compose logs -f homeassistant

第二条命令跟着看日志，第一次启动会下载依赖、初始化数据库，通常要一到三分钟。看到Home Assistant initialized之类字样就说明起来了。浏览器打开http://主机IP:8123，进入网页向导，设置管理员账号、名称、位置、单位制。位置一定要填对，它不仅影响日出日落时间，还影响天气和时区推断。

起来之后，进到宿主机的./config目录看一眼，这个目录结构要熟悉：

config/ ├── configuration.yaml # 主配置 ├── automations.yaml # 自动化 ├── scripts.yaml # 脚本 ├── scenes.yaml # 场景 ├── customize.yaml # 实体定制 ├── secrets.yaml # 密钥，密码写这里 ├── home-assistant_v2.db # 默认 SQLite 数据库 ├── custom_components/ # 自定义集成放这里 ├── www/ # 静态文件，可对外访问 └── .storage/ # 界面配置的存储，别手改

这里有个血泪教训：.storage目录存的是你在界面上做的全部配置（区域、标签、集成、仪表盘），它和 YAML 是两套并行体系。千万不要为了"干净"把它删掉，那等于把界面上的配置全部清零。备份的时候这个目录必须一起打包。

还有secrets.yaml值得单独说。密码、Token、经纬度这类信息建议全部抽到这个文件里，主配置用!secret xxx引用。好处是分享配置时可以直接把 secrets 文件排除，不用逐行删。

3. HACS 安装：把集成生态接进来

3.1 安装 HACS 前的三项检查

装 HACS 之前，有三件事必须先确认，否则后面会出现各种"看起来装上了其实没生效"的怪现象。

第一，确认你已经有了一个能正常登录、能添加集成的 HomeAssistant。HACS 本身是个集成，它依赖核心的集成框架，核心没跑顺就谈不上装它。

第二，确认config目录里有custom_components文件夹。如果没有，手动建一个。目录名必须完全一致，大小写敏感，写成Custom_Components是无效的，这是新手高频错误。

第三，确认你的账号在 HomeAssistant 里是管理员。HACS 安装过程需要在界面里完成授权，非管理员账号看不到相关入口。

另外提醒一句，HACS 需要访问代码托管平台来获取仓库列表和下载资源。如果你所在网络环境访问不畅，会出现"装上了但商店里空空如也"的情况。遇到这种表现，先怀疑网络连通性，不要急着重装。

3.2 手动安装 HACS 的完整流程

HACS 的首次安装必须手动放文件，这是官方设计，绕不过去。

第一步，获取 HACS 的发布包。去它的官方仓库 Releases 页面下载最新的hacs.zip。不要用git clone整个仓库，那会把开发分支的文件一起拉下来，容易出问题。

第二步，解压。解压后你会看到一个hacs文件夹，里面应该有manifest.json、__init__.py这些文件。重点来了：最终路径必须是config/custom_components/hacs/，也就是说manifest.json要直接在hacs目录下，不能多套一层。我见过最多的问题是解压出来是hacs-2.0.0/hacs/...，然后用户直接把最外层丢进custom_components，结果路径变成custom_components/hacs-2.0.0/hacs，核心根本扫不到。

第三步，重启 HomeAssistant 容器：

docker compose restart homeassistant

第四步，进界面添加集成。路径是"设置 - 设备与服务 - 右下角添加集成"，搜索 HACS。如果搜不到，说明第三步没生效或者路径不对，回去检查目录结构。

第五步，授权。HACS 会引导你完成账号授权流程，界面上会显示一个验证码和一串数字。这一步按提示操作即可，授权成功后它会去拉取仓库列表，这个过程视网络情况可能要等一两分钟。

第六步，验证。左侧边栏应该出现 HACS 入口。点进去能看到"集成"和"前端"两个标签页，说明装好了。

注意：不要把整个custom_components目录从别的机器直接拷过来覆盖。不同版本的集成可能依赖不同的核心版本，混着来会出现启动报错，而且报错信息往往指向核心而不是集成，非常难查。

3.3 集成与前端卡片的管理节奏

HACS 装好之后，管理节奏比安装本身更重要。我的经验是分三条线走。

集成这条线，原则是"能不装就不装"。每装一个自定义集成，就多一份升级时的适配风险。优先用官方核心集成，官方没有的再考虑 HACS。装的时候在 HACS 里搜索，看清楚仓库的更新时间和 Star 数，半年没更新的仓库要慎重，因为核心每月发版，一年不更新的集成大概率已经跑不起来了。

前端这条线，可以放开一点。仪表盘卡片是可选的，坏了顶多界面难看，不会影响自动化运行。常见的卡片类资源装完记得去仪表盘右上角"编辑 - 三个点 - 资源"里确认已经注册，新版本的 HACS 会自动帮你加，但偶尔会漏。改完卡片资源，浏览器一定要强刷缓存（Ctrl+Shift+R），不然你会看到一半新一半旧的诡异界面。

更新这条线，我给自己定了条规矩：核心和集成分开更新，中间隔三天。具体做法是，先更新 HomeAssistant 核心，观察几天，确认所有集成和自动化都正常，再去 HACS 里批量更新集成。两个一起更，出问题时根本分不清是谁引起的。更新前顺手把config目录打个包，一个 tar 命令几秒钟的事，能省掉一晚上重装的痛苦。

4. 设备接入实战：协议选择与配置落地

4.1 MQTT：设备接入的中枢神经

如果要我从所有接入方式里挑一个必须掌握的，答案就是 MQTT。它是一个轻量级的发布订阅消息协议，设备把状态发到某个主题（Topic），HomeAssistant 订阅这个主题就能拿到数据。好处是协议极简、跨平台、几乎不挑硬件，几十块钱的模块就能跑。

部署 MQTT broker 我推荐 Mosquitto，用 compose 起一个：

services: mosquitto: container_name: mosquitto image: eclipse-mosquitto:2 restart: unless-stopped ports: - "1883:1883" volumes: - ./mosquitto/config:/mosquitto/config - ./mosquitto/data:/mosquitto/data - ./mosquitto/log:/mosquitto/log

配置文件mosquitto/config/mosquitto.conf最小可用版本是这样：

listener 1883 allow_anonymous false password_file /mosquitto/config/passwd persistence true persistence_location /mosquitto/data/ log_dest file /mosquitto/log/mosquitto.log

关键参数解释一下。allow_anonymous false必须设置，否则局域网里任何人都能收发你的设备消息，这等于家门大开。添加用户用这条命令：

docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd hauser

执行后会提示输入密码。-c是创建文件，如果已经有文件了，第二次添加用户要去掉-c，否则会把之前的用户清空——这个坑我踩过一次，加了第二个用户结果第一个用户登不上了。

persistence true让 broker 重启后保留会话和保留消息，对传感器设备挺重要，否则重启瞬间所有状态都变未知。

接入 MQTT 时，HomeAssistant 这边只需要填三样：broker 地址、端口、用户名密码。地址别填localhost，因为容器里没有 localhost 这个说法，要填宿主机的局域网 IP，或者如果两个容器在同一个自定义网络里，填容器名。用 host 网络模式的话直接填宿主机 IP 最稳。

提示：给每个设备规划好主题命名，比如home/floor1/livingroom/temp。这套命名在后期写自动化、做数据库排除时会救你的命，临时起意起的名字三个月后你自己都不认识。

4.2 局域网与云设备接入的三种姿势

家里的设备来源五花八门，接入方式我归纳成三档，按优先级从高到低排。

第一档是本地协议直连，也就是设备本身开放接口，HomeAssistant 直接和它对话，完全不经过厂商服务器。典型代表是 Zigbee、Z-Wave、Matter，以及一些支持局域网协议的设备。这类接入的优点是响应快（几十毫秒）、断网可用、不受厂商停服影响。我现在的原则是：买新设备前先查它支不支持本地接入，不支持就换一个型号。

第二档是 MQTT 桥接，设备本身跑着固件，直接往 broker 发消息。刷了开源固件的插座、开关、传感器都属于这一类，还有自己用模块做的 DIY 设备。这类设备的配置核心就是定义好状态主题和命令主题，配好state_topic、command_topic、availability_topic这几个字段。

第三档是云 API 集成，也就是通过厂商的开放接口走互联网。优点是支持面广、开箱即用；缺点也很明显：依赖厂商服务器，延迟高，厂商改接口就可能失效，而且设备状态是轮询的，实时性差。我的建议是把它当备选，能用本地就用本地。如果某个设备只支持云，那就把轮询间隔调长一点，比如 30 秒或 60 秒，别设成 5 秒，那会给你的核心和厂商接口都造成无谓压力。

下面这张表是我这些年接过的设备类型对照，可以直接拿去当采购参考：

4.3 Zigbee 网关接入与信道规划

智能家居里设备最密集的场景是传感器网络，Zigbee 是这块的主力。接入 Zigbee 的核心是一个网关（也叫协调器），插在主机上的 USB 棒是最常见的形态。

HomeAssistant 里接 Zigbee 有两条主流路线：一条是用官方支持的 ZHA 集成，优点是内置、零额外服务；另一条是用 Zigbee2MQTT，它单独跑一个容器，把 Zigbee 设备全部转成 MQTT 实体。我长期用后者，原因是设备兼容库更新快、调试界面好用、支持的网络拓扑可视化和固件升级功能更全。

Zigbee2MQTT 的 compose 配置大概长这样：

services: zigbee2mqtt: container_name: zigbee2mqtt image: koenkk/zigbee2mqtt restart: unless-stopped volumes: - ./zigbee2mqtt/data:/app/data - /run/udev:/run/udev:ro devices: - /dev/ttyUSB0:/dev/ttyUSB0 environment: - TZ=Asia/Shanghai

这里有个必须重点说的细节：不要用/dev/ttyUSB0这种名字。USB 设备序号是内核按插入顺序分配的，今天插上是 USB0，明天换个口插可能就变成 USB1，然后你的整个 Zigbee 网络就断联了。正确做法是用稳定路径：

ls -l /dev/serial/by-id/

找到那串带设备序列号的路径，形如/dev/serial/by-id/usb-XXXX_YYYY-if00-port0，把它写进devices映射。这样无论插哪个口，路径都不变。这个改动花两分钟，能避免未来无数次莫名其妙的掉线排查。

权限方面，宿主上执行ls -l /dev/ttyUSB0会看到设备属于dialout组。如果容器里访问不了，可以在宿主执行sudo usermod -aG dialout $USER，或者直接用privileged: true图省事（但前面说过，能不开就不开）。

然后是信道规划，这是很多人忽视但影响巨大的参数。Zigbee 工作在 2.4GHz，和 WiFi 频段重叠。WiFi 最常用的信道是 1、6、11，Zigbee 的信道是 11 到 26。要避开的对应关系大致是：WiFi 1 对应 Zigbee 11-14，WiFi 6 对应 15-19，WiFi 11 对应 20-24。也就是说，Zigbee 用 15、20、25、26 这几个信道最安全。我一般选 25 或 26，实测丢包率明显下降。

配置写在zigbee2mqtt/data/configuration.yaml里：

advanced: network_key: GENERATE pan_id: GENERATE channel: 25

network_key第一次配好后一定要记下来备份。它是网络密钥，丢了就意味着所有设备要重新配对，几十个设备重新配对是场灾难。pan_id同理。

配对设备时，先在 Zigbee2MQTT 界面点"允许加入"，然后让设备进入配对模式（通常是长按复位键几秒）。配对成功的设备会自动出现在 HomeAssistant 里，因为 HomeAssistant 那边已经通过 MQTT 集成订阅了发现主题，新设备是自动发现的，不用手动加。

5. 稳定性维护与常见问题排查

5.1 权限、路径与设备映射类故障

这套系统跑起来之后，最常见的故障其实不在软件逻辑，而在权限和路径。我把踩过的几个典型场景整理出来。

第一个是"Zigbee 网关容器启动失败，日志报 permission denied"。原因基本就是设备节点权限不够。排查顺序是：先在宿主执行ls -l /dev/ttyUSB0看属主和属组；再看容器里的用户是不是在那个组里；最后确认devices映射路径写对了。如果宿主能看到设备、容器映射了却打不开，那一定是权限问题，不是硬件坏了。

第二个是"设备偶尔失联，重启就好"。这通常和 USB 供电有关。USB 延长线太长、用了劣质的 USB Hub、或者主机 USB 口供电不足，都会导致网关掉线。我的做法是把 Zigbee 网关用一根带屏蔽的短延长线，挪到离主机 20 厘米以外的地方——因为主机本身是个电磁噪声源，网关贴着机箱插，干扰会明显变大。这个改动听起来玄学，实测确实有效。

第三个是"容器重启后配置丢失"。八成是卷映射写成了相对路径而工作目录不对，或者用了匿名卷。检查docker inspect 容器名里的 Mounts 部分，看宿主路径是不是你期望的那个。写 compose 时建议用绝对路径，虽然长一点，但不会有歧义。

第四个是"数据库文件涨到几个 GB，界面越来越卡"。这是 recorder 组件按默认设置长期记录所有实体导致的结果。解决办法在configuration.yaml里：

recorder: purge_keep_days: 10 commit_interval: 30 exclude: domains: - automation - updater entity_globs: - sensor.*_linkquality - sensor.*_rssi

purge_keep_days是保留天数，默认 10 天，我见过有人设成 365 天。commit_interval是写盘间隔，默认 1 秒，改成 30 秒能大幅减少磁盘写入。exclude是关键，把信号质量、电池电压这类高频变化又没长期价值的实体排除掉，数据量能降一个数量级。Zigbee 设备的 linkquality 每分钟都在变，全记下来纯属浪费。

5.2 网络发现失效与实体失联排查

设备接入之后，第二类高频问题就是"实体突然变成不可用"。我总结了一套从外向内的排查顺序，能覆盖九成情况。

第一步，看底层服务在不在。用docker ps确认容器都活着，特别是 MQTT broker、Zigbee2MQTT 这类中间层。中间层挂了，上面所有实体都会失联，这时候去 HomeAssistant 里翻配置是白费力气。

第二步，看日志。docker compose logs -f --tail=100 服务名是最有效的工具。MQTT 的问题会直接告诉你"connection refused"或者"not authorised"；Zigbee 的问题会显示设备离线还是网络不可达。日志里的关键词比界面上的红色感叹号信息量大得多。

第三步，验证网络连通性。从容器里 ping 一下设备 IP，或者用 mosquitto 的订阅命令看消息有没有在流动：

docker exec -it mosquitto mosquitto_sub -h localhost -u hauser -P 密码 -t '#' -v

这条命令会打印所有主题的消息，如果某个设备的状态主题一直没动静，问题就在设备侧而不是 HomeAssistant 侧。这个判断能帮你省掉大量来回试错。

第四步，检查实体命名。设备重新配对后，如果新生成的实体 ID 和旧的略有不同（比如多了个_2后缀），那所有引用旧实体的自动化都会失效。这是个很隐蔽的坑，表现是"设备明明在线，自动化就是不触发"。养成习惯：设备和实体改完名之后，去自动化和仪表盘里搜一遍旧名字。

5.3 备份、升级与数据库瘦身策略

最后说维护。这部分不性感，但决定了你这套系统能不能安稳跑三年。

备份我分三层。第一层是最小可恢复集：config目录整体打包，包含 YAML、.storage、数据库、自定义组件、密钥。命令就一行：

tar -czf ha-backup-$(date +%Y%m%d).tar.gz ./config

建议用宿主机的定时任务每天凌晨跑一次，保留最近 7 份，老的自然轮换掉。第二层是 Zigbee 网络的密钥和pan_id，单独抄一份存起来，因为设备重新配对的成本太高。第三层是设备清单和自动化逻辑的说明文档，纯文本写清楚每个设备是什么、装在哪、用的什么集成。半年后你自己都会忘，这份文档就是你的记忆。

升级的节奏前面提过，核心和集成分开走。具体操作是：先备份，然后改 compose 里的版本号（如果用stable就docker compose pull），再docker compose up -d。起来之后重点看三件事：所有集成有没有报错、自动化有没有失效、数据库读写有没有异常。观察两三天没毛病，再去 HACS 里更新集成。

有个细节值得注意：HomeAssistant 升级时有时会自动做数据库结构迁移，升级过程中数据库在改写。所以升级前一定要停掉容器再备份，热备份数据库可能拿到一个不一致的快照，恢复的时候会报错。这是我用血换来的教训，一次数据库损坏让我丢了两个月的传感器历史数据。

还有一点关于资源占用的经验。这套系统跑稳之后，日常宿主的 CPU 占用很低，通常在 5% 到 15% 之间浮动，真正吃资源的是启动阶段和数据库整理阶段。如果你发现 CPU 长期跑满，先看是不是某个集成的轮询间隔设得太短，或者有自动化陷入了循环触发。后者有个典型的识别方法：看日志里同一个自动化是不是每秒触发一次，那就是条件判断写错了。

日常巡检我给自己定了个简单清单，每周花两分钟过一遍：容器状态是否全绿、磁盘剩余空间是否超过 20%、日志里有没有重复出现的报错、有没有设备显示低电量。就这四项，能拦住绝大多数"突然全崩"的情况。

我个人在实际操作中的体会是，这套东西真正难的地方不是装，是装完之后忍住不折腾。每次看到新的集成、新的卡片就手痒，改完之后总要花时间调回来。后来我给自己立了个规矩：动生产环境之前先在测试目录里跑一遍，用第二份 compose 文件起一个独立实例，端口和安全配置全部分开。这个习惯养成之后，我的中枢已经连续稳定运行了很久，家里人也终于不再抱怨"灯又乱闪了"。