Использование secrets.yaml в Home Assistant

Введение

Home Assistant — это мощная платформа автоматизации, конфигурация которой может храниться в YAML-файлах или во внутреннем хранилище .storage. Подробнее о разнице между YAML и .storage можно прочитать в статье: YAML vs Storage в Home Assistant. Режим YAML подразумевает ручное редактирование файлов конфигурации (например, configuration.yaml), а режим .storage используется, когда вы добавляете интеграции и сервисы через графический интерфейс (Настройки → Устройства и службы → Интеграции).

Если вы используете storage‑режим, то Home Assistant сохраняет параметры интеграций, включая логины и токены, во внутренней директории config/.storage/, чаще всего в файле core.config_entries. Эти данные хранятся в открытом виде (в формате JSON) и не шифруются самим Home Assistant. Доступ к ним ограничивается только правами на уровне файловой системы.

Если же вы настраиваете Home Assistant через YAML, то у вас есть дополнительный механизм защиты чувствительных данных — файл secrets.yaml. Он позволяет хранить токены, пароли, ключи API и другие секреты отдельно от основной конфигурации, что делает систему безопаснее и удобнее в сопровождении.

Как работает файл secrets.yaml

Файл secrets.yaml предназначен для безопасного хранения чувствительных данных. Вместо того чтобы указывать значения прямо в configuration.yaml, вы можете сослаться на них через директиву !secret. Home Assistant автоматически подставляет значение из secrets.yaml при загрузке конфигурации.

Без использования секрета — конфигурация с открытым токеном:

telegram_bot:
  - platform: polling
    api_key: 3491876254:ABCDx-YtuvQ1jg9kPLZ4F3Mn2bC6efGhRst
    parse_mode: html

С использованием секрета:

telegram_bot:
  - platform: polling
    api_key: !secret telegram_token
    parse_mode: html

Содержимое файла secrets.yaml:

telegram_token: 3491876254:ABCDx-YtuvQ1jg9kPLZ4F3Mn2bC6efGhRst

Преимущества secrets.yaml

• Безопасность — токены и пароли не попадают в публичные конфиги
• Удобство — все секретные данные собраны в одном месте
• Портируемость — можно делиться конфигом без риска утечки
• Простота обновления — достаточно изменить значение в одном файле

Где хранится файл

Файл secrets.yaml расположен в папке с основной конфигурацией Home Assistant (config/). Типичная структура выглядит так:

config/
├── configuration.yaml
├── automations.yaml
├── secrets.yaml
└── ...

В новых версиях Home Assistant этот файл создаётся автоматически и содержит пример:

# Use this file to store secrets like usernames and passwords.
# Learn more at https://www.home-assistant.io/docs/configuration/secrets/
some_password: welcome

Рекомендации по использованию

• Не делитесь файлом secrets.yaml публично
• Не добавляйте secrets.yaml в Git‑репозиторий — укажите его в .gitignore
• После изменений проверяйте конфигурацию через Панель разработчика → YAML → Проверить конфигурацию

Примеры использования

Пример 1. Telegram Bot

configuration.yaml:

telegram_bot:
  - platform: polling
    api_key: !secret telegram_token
    parse_mode: html

secrets.yaml:

telegram_token: 3491876254:ABCDx-YtuvQ1jg9kPLZ4F3Mn2bC6efGhRst

Пример 2. Базы данных MariaDB

configuration.yaml:

recorder:
  db_url: !secret mariadb

secrets.yaml:

mariadb: "mysql://ha_user:secret@192.168.1.100:3306/ha_db?charset=utf8mb4"

Использование !secret в этом случае удобно при переносе конфигурации между установками или хранении резервных копий. Все конфиги можно публиковать или синхронизировать без риска раскрыть пароль.

Заключение

Файл secrets.yaml — это простое и эффективное средство повышения безопасности конфигурации Home Assistant. Он помогает централизованно управлять паролями, токенами и ключами API, делая систему более надёжной и удобной в сопровождении.

Используйте secrets.yaml с самого начала настройки — это хорошая привычка, которая защитит ваш умный дом от случайных утечек данных.