配置目录与 Add-on 商店

HA 的一切都在配置目录里

用过几天 HA 之后，你会发现一个说起来简单但极其重要的事实：整个系统真正的核心数据，就是配置目录里那几个文件夹和文件。设备怎么分区、自动化怎么写、仪表盘长什么样、历史存在哪——全在里面。理解配置目录，等于拿到了 HA 的地图；备份好配置目录，等于保住了HA 的命根子。

这个目录在哪取决于你的部署方式：HAOS 用户可以通过 Samba share 或文件管理 Add-on 访问，Container 用户就是 compose 文件里挂载的那个宿主目录。无论哪种形态，内容结构是一样的。

一开始不用把这个目录翻个底朝天。随着你的自动化越写越多，自然会更常打开它——早知道结构，到那天就少抓瞎。一个务实的建议：趁现在内容还少，把 configuration.yaml 加上自己的注释，把区域划分和命名规则定下来。命名规则这种东西，等家里有两百个实体再想建立，会痛苦十倍。

两种配置方式：界面与 YAML

HA 的配置可以来自两个源头：图形界面（你点出来的每一项设置，都写进 .storage 目录）和 YAML 文件（你手写的配置）。两者并行存在、各司其职：

• 界面配置对新手友好，所见即所得，改完即生效，不用重启。
• YAML 配置威力更大，可批量、可复用、可版本管理，适合沉淀长期方案。

新手的常见纠结是到底用哪个。答案是：凡界面能做的就用界面，只有界面做不到的（自定义模板、批量声明等）才写 YAML。不要为了显得极客而把能点选的配置全部手写一遍，那是给自己找麻烦。

两类配置还有个协作技巧：自动化和仪表盘这类需要反复调试的东西，优先在界面里做，随时改随时生效；传感器模板、批量定制这类一次成型的大型配置，沉淀进 YAML 更好维护。你没有必要站队，两个工具各有所长。

YAML 的最小语法包

既然逃不开 YAML，花三分钟掌握最小语法包。它的核心规则只有四条，社区里绝大多数配置错误都栽在这四条上：

• 用缩进表示层级，必须用空格，不能用制表符。
• 键值对用英文冒号加空格分隔，冒号后面空格不能省。
• 列表项以英文连字符开头，同一层对齐。
• 注释以井号开头，随便写不报错，多写注释等于给未来的自己留路。

一个典型的自动化片段长这样（注意缩进）：

automation:
  - alias: 天黑开灯
    trigger:
      - platform: sun
        event: sunset
    action:
      - service: light.turn_on
        target:
          entity_id: light.客厅

学会这四条规则，社区里浩如烟海的配置示例你就都能读懂了，这比任何教程都值。注意代码里的冒号、引号都是英文符号，只有在代码里英文符号才是对的，写到中文正文里反而会出问题。

再给一个排错锦囊：YAML 报错时，十有八九是缩进不对或者冒号后面漏了空格，照着这两个方向先检查，比盯着屏幕发呆有效得多。养成改完先校验再重启的习惯，配置错误就不会把系统搞到起不来。

顺手说一下配置里放敏感信息的规矩：配置目录里约定有一个 secrets.yaml，密码、API 令牌这些敏感值应该放进它，然后在主配置里用引用的方式调用，避免明文散落各处。这是从一开始就该养成的习惯——有了它，你连把整个配置目录分享到社区求助都不用担心泄露账号。

Add-on 商店是什么

前面说过，HAOS 用户有个 Add-on 商店——它是装在 HA 旁边的应用市场。Add-on 和集成（Integration）不是一回事，很多新手分不清：

这个区别解释了为什么 Container 用户没有 Add-on 商店却仍能接所有设备：集成是核心功能，Add-on 是 HAOS 的周边福利。Container 用户想要同样的服务，自己在 Docker 里跑一份即可。记住这条对应关系，以后看到教程里说装某个 Add-on 时，你就能条件反射地知道，Container 环境下要去搜同名 Docker 镜像。

常用 Add-on 清单

如果你选了 HAOS，这几个 Add-on 几乎是标配：

• Studio Code Server：浏览器里直接改配置，带语法提示和校验，手写 YAML 的最佳搭档。
• Mosquitto MQTT broker：跑本地 MQTT 服务，接各种 MQTT 设备和传感器必备，很多自制硬件方案都走 MQTT。
• Node-RED：图形化编写复杂流程，和 HA 自动化互补，喜欢的人爱不释手。
• File editor：Studio Code Server 的轻量替代，配置简单打开快，机器性能紧张时选它。
• Samba share：把配置目录变成局域网共享文件夹，用电脑直接编辑，对不习惯浏览器编辑的人友好。

装哪些按需取用，别一上来全装——每个 Add-on 都占内存，用不上的就先不装，将来需要随时可以回来加。一般家庭的安装顺序是：编辑器第一位，MQTT 看有没有 MQTT 设备，Node-RED 等自动化写复杂了再说。

Container 用户怎么补齐这些服务

Container 用户没有 Add-on，但 Docker 本身就是更大的应用商店。列举一下替代方案：

看出来了吧，能力上没有任何缺失，差别只在管理方式：HAOS 的 Add-on 是被统一纳管的，而 Container 方案要你自己维护每个容器的 compose 文件。如果你已经在 NAS 上跑了一堆服务，这其实只是多几个容器而已。

HACS：更大的野生市场

说完官方商店，绕不开 HACS（Home Assistant Community Store）。它是第三方商店，提供社区做的集成、主题、前端组件和自动化模板。生态活跃度极高，很多好玩的功能官方商店里没有。

三条使用 HACS 的建议：

• 装之前看一眼更新频率和讨论区，长期没人维护的组件是潜在地雷。
• HA 核心大版本升级后，第三方组件可能短暂失效，等作者适配就行，不用大惊小怪。
• 组件代码来自社区，安全意识要有——只装星标多、口碑好的。

另外要管理好预期：HACS 的东西不是官方维护的，今天好用不代表明年还好用。把关键功能建立在官方集成上，HACS 组件用来锦上添花，你的系统就稳如磐石。

配置目录的备份与迁移

配置目录既是命根子，备份策略就围绕它展开。核心数据其实很小——几兆到几十兆的配置文件，外加体积可控的数据库。成套做法在备份那篇详细讲，这里只立个规矩：任何大改动之前，先备份这个目录；换机器时，它是你唯一需要带走的行李。

一个常见疑问是：数据库要不要一起备份？要，但不必频繁——它只是历史记录，丢了顶多少看几天曲线，不影响设备和自动化。真正每天都在变化、必须经常备份的是配置部分。分开对待，备份又快又省心。

延伸阅读

• 自建 NAS 完全指南：备份目录同步到 NAS 的自动化做法
• 群晖 DSM 实用指南：用群晖的同步工具保护配置目录