以模块化 YAML 包结构管理 Home Assistant 配置并每日自动验证

方案简介

本方案是 Frenck（Home Assistant 项目负责人）公开的个人 Home Assistant 配置仓库，展示了一套以「模块化 YAML 包」为核心的智能家庭配置管理方法。Home Assistant 是一个开源智能家居平台，可本地运行在例如树莓派上，连接超过 2000 种设备与服务，从灯光、传感器到媒体播放器和电动车，完全不依赖云端。

这套配置仓库不是一份巨大的 configuration.yaml，而是把每个集成拆到 integrations/ 目录下的独立文件中，自动化、脚本、场景也分别拆到各自目录。整个仓库同时是一个「活的」工程化项目：借助 GitHub Actions，每晚对 Home Assistant Core 的 stable、beta、dev 三个版本进行验证；每次提交都会运行 yamllint、remarklint、Prettier、actionlint 等多种 lint 工具。它适合希望把智能家居配置当作软件工程来管理的 Home Assistant 用户，可直接借鉴目录结构、模块化方式与 CI 实践。

亮点与能力

• 完全模块化：每个集成都以独立 YAML 文件存放于 integrations/ 目录，整洁有序、易于查找。
• 每晚自动测试：配置每天对照 Home Assistant Core 的 stable、beta、dev 版本验证，破坏性变更在发布前即可发现。
• ESPHome 就绪：为 ESPHome 设备配置提供专门目录与 CI workflow。
• 深度 Lint：yamllint、remarklint、Prettier、actionlint、zizmor 在每次提交时运行。
• 自动化/脚本/场景分目录：各自独立目录，随规模增长依然易管理。
• 最小化引导文件：configuration.yaml 保持精简，只负责加载 packages。
• CI 专用假密钥：提供 secrets.fake.yaml 供 CI 测试使用。

组成与分工

• Home Assistant：核心智能家居平台，本地运行，承载全部集成、自动化、脚本与场景。
• YAML packages 机制：Home Assistant 的包模式，configuration.yaml 只做最小引导，把 integrations/ 目录作为包加载。
• GitHub Actions：CI/CD 平台，负责每晚多版本验证与提交时的 lint 检查。
• yamllint / remarklint / Prettier / actionlint / zizmor：多种 lint 工具，在每次提交时校验 YAML 与 workflow 文件质量。
• secrets.yaml / secrets.fake.yaml：真实密钥不入库，CI 使用假密钥文件进行测试。
• ESPHome：设备固件配置体系，拥有专门目录与 CI workflow。

前置要求

• 一台可本地运行 Home Assistant 的设备（如 Raspberry Pi）。
• Home Assistant Core（方案对 stable、beta、dev 版本均有验证）。
• GitHub 仓库与 GitHub Actions（用于每晚验证与 lint）。
• 本地不入库的 secrets.yaml，以及供 CI 使用的 secrets.fake.yaml。

实施步骤

1. 按 Frenck 的目录结构组织仓库

按以下结构放置文件（来自仓库 README 的结构说明）：

txt

├── configuration.yaml # Minimal bootstrap, loads packages
├── integrations/ # Modular integration configs (packages)
├── automations/ # Split automation YAML files
├── scripts/ # Split script YAML files
├── scenes/ # Split scene YAML files
├── blueprints/ # Automation & script blueprints
├── esphome/ # ESPHome device configurations
├── secrets.yaml # Secrets (not in repo)
└── secrets.fake.yaml # Fake secrets for CI testing

2. 保持 configuration.yaml 极简

configuration.yaml 只作为最小引导文件，仅负责把 integrations/ 目录作为 packages 加载；每个集成获得自己的文件，保持整洁易导航。

3. 拆分自动化、脚本与场景

把自动化、脚本、场景分别放入 automations/、scripts/、scenes/ 目录，随规模增长依然易于管理。

4. 接入 CI

仿照本仓库，在 GitHub Actions 中建立两条 workflow：一条（home-assistant.yml）每晚对 stable、beta、dev 三个版本验证配置；另一条（linting.yaml）在每次提交时运行 yamllint、remarklint、Prettier、actionlint、zizmor。

使用与配置要点

• 日常新增集成时，在 integrations/ 下新建独立 YAML 文件，而不是往 configuration.yaml 里堆内容。
• 新增自动化/脚本/场景时分别落入 automations/、scripts/、scenes/ 目录。
• 敏感信息写入本地 secrets.yaml（不入库），CI 测试依赖 secrets.fake.yaml 提供假密钥。
• 验证是否成功：查看 GitHub Actions 中 home-assistant 与 linting 两个 workflow 是否通过；每晚的验证会让破坏性变更在发布前暴露。

注意事项与常见问题

• secrets.yaml 不在仓库中（not in repo），克隆仓库后需自备真实密钥文件。
• 作者强调对 YAML 质量要求严格：多种 lint 工具在每次提交时运行，提交前需保证格式合规。
• 本配置是作者的个人配置，定位为开源项目，欢迎借鉴与贡献，具体贡献方式见仓库单独的贡献文档。

优缺点

• ✓ 配置模块化清晰易找
• ✓ 每夜多版本自动验证
• ✕ 需要维护 secrets 文件
• ✕ 依赖 GitHub Actions 环境

出处

本方案挖掘自开源项目 frenck/home-assistant-config，方案内容与实施命令均来自其 README 原文。