记录器

此集成默认情况下作为 history 集成的依赖项启用。

Home Assistant 使用 SQLAlchemy，这是一种对象关系映射（ORM）。这使得可以使用多种数据库解决方案。

支持的数据库解决方案包括：

• MariaDB ≥ 10.3
• MySQL ≥ 8.0
• PostgreSQL ≥ 12
• SQLite ≥ 3.40.1

尽管 SQLAlchemy 支持 Home Assistant 之外的数据库解决方案，但它在不同数据库上的行为可能不同，并且记录器所依赖的功能在不同数据库中可能表现不同，甚至根本无法工作。

默认和推荐的数据库引擎是 SQLite，不需要任何配置。数据库存储在您的 Home Assistant 配置目录（’/config/’）中，并命名为 home-assistant_v2.db。

要更改您安装中 recorder 集成的默认值，请将以下内容添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中：

磁盘空间要求

最低要求是在任何时候都至少有与数据库大小相同的可用临时空间。表重建、修复或重新打包可能随时发生，这可能导致在操作期间数据的磁盘副本。在版本升级期间满足最低要求至关重要，因为此时模式可能会更改，此操作几乎总是需要临时复制部分数据库。

例如，如果您的数据库在磁盘上为 1.5 GiB，您始终必须至少有 1.5 GiB 的空间。

高级配置

# 示例 configuration.yaml 条目
recorder:

配置过滤器

默认情况下，没有实体会被排除。为了限制暴露给 recorder 的实体，您可以使用 include 和 exclude 参数。

# 示例过滤器以包含指定域并排除指定实体
recorder:
  include:
    domains:
      - alarm_control_panel
      - light
    entity_globs:
      - binary_sensor.*_occupancy
  exclude:
    entities:
      - light.kitchen_light

Filters are applied as follows:

1. 不使用过滤器
   • 包含所有实体
2. 仅包含
   • 实体列表中的实体包含：include
   • 否则，实体匹配域包含：include
   • 否则，实体匹配通配符包含：include
   • 否则：排除
3. 仅排除
   • 实体列表中的实体排除：exclude
   • 否则，实体匹配域排除：exclude
   • 否则，实体匹配通配符排除：exclude
   • 否则：包含
4. 域和/或通配符包含（还可能有排除）
   • 实体列表中的实体包含：include
   • 否则，实体列表中的排除：exclude
   • 否则，实体匹配通配符包含：include
   • 否则，实体匹配通配符排除：exclude
   • 否则，实体匹配域包含：include
   • 否则：排除
5. 域和/或通配符排除（没有域和/或通配符包含）
   • 实体列表中的实体包含：include
   • 否则，实体列表中的排除：exclude
   • 否则，实体匹配通配符排除：exclude
   • 否则，实体匹配域排除：exclude
   • 否则：包含
6. 没有域和/或通配符的包含或排除
   • 实体列表中的实体包含：include
   • 否则：排除

以下字符可用于实体通配符：

* - 星号表示零个、一个或多个字符
? - 问号表示零个或一个字符

如果您只想在日志簿中隐藏事件，请查看 日志簿集成。但是，如果您对某些事件有隐私顾虑，或想让它们既不在历史中也不在日志簿中，您应使用 recorder 集成的 exclude/include 选项。这样它们就不会进入您的数据库，您可以通过排除某些经常记录的事件（如 sensor.last_boot）来减少存储并保持数据库的大小。

常见过滤示例

定义要 exclude（即黑名单）的域和实体非常方便，当您基本上对记录的信息满意，但只是想删除一些实体或域时。

# 示例 configuration.yaml 条目，包含排除
recorder:
  purge_keep_days: 5
  db_url: sqlite:////home/user/.homeassistant/test
  exclude:
    domains:
      - automation
      - update
    entity_globs:
      - sensor.sun*
      - weather.*
    entities:
      - sensor.date
      - sensor.last_boot # 来自 'systemmonitor' 传感器平台
      - sun.sun # 不记录太阳数据
    event_types:
      - call_service # 不记录操作

通过使用 include 配置定义要记录的域和实体（即白名单）在您的系统中有很多实体时非常方便，而且您的 exclude 列表可能会非常庞大，因此最好直接定义要记录的实体或域。

# 示例 configuration.yaml 条目，包含
recorder:
  include:
    domains:
      - sensor
      - switch
      - media_player

您还可以使用 include 列表来定义要记录的域/实体，并在 exclude 列表中排除其中一些。如果您例如包含了 sensor 域，但想排除一些特定传感器，这样合理。您可以包括 sensor 域并排除您不感兴趣的传感器实体，而不是将每个传感器实体添加到 include 的 entities 列表中。

# 示例 configuration.yaml 条目，包含和排除
recorder:
  include:
    domains:
      - sensor
      - switch
      - media_player
  exclude:
    entities:
      - sensor.last_boot
      - sensor.date
    entity_globs:
      - sensor.weather_*

操作

操作 purge

执行操作 recorder.purge 开始清除任务，该任务根据 keep_days 操作数据删除超过 x 天的事件和状态。 请注意，清除不会立即减少磁盘空间的使用，但会显著减缓进一步的增长。

操作 purge_entities

执行操作 recorder.purge_entities 开始一个任务，清除与任何指定的 entity_id、domains 和 entity_globs 字段匹配的事件和状态。必须提供三个选择标准字段中的至少一个。

示例自动化以删除特定实体的数据行

以下自动化将删除 sensor.power_sensor_0 超过 5 天的历史记录，时间为每天的 04:15:00。

alias: "清除嘈杂的功率传感器"
triggers:
  - trigger: time
    at: "04:15:00"
actions:
  - action: recorder.purge_entities
    data:
      keep_days: 5
      entity_id: sensor.power_sensor_0

操作 disable

执行操作 recorder.disable 停止将事件和状态保存到数据库。

操作 enable

执行操作 recorder.enable 重新开始将事件和状态保存到数据库。这是 recorder.disable 的相反操作。

处理磁盘损坏和硬件故障

在使用 SQLite 时，如果系统遇到无法恢复的磁盘损坏，它将将数据库移动到一旁，并创建一个新数据库以保持系统在线。在此情况下，必须确保有至少 2.5 倍的数据库大小的可用空闲磁盘空间。启动新数据库是系统最后的恢复选项，通常是由故障的闪存存储、不足的电源、非干净关机或其他硬件故障引起的。

在这种情况下，可以通过查阅 SQLite 恢复指南 来恢复旧数据库。

自定义数据库引擎

以下是与 db_url 配置选项配合使用的示例。

数据库启动

如果您在与 Home Assistant 同一台服务器上运行数据库服务器实例，则必须确保此操作在 Home Assistant 之前启动。对于运行 Systemd 的 Linux 实例（Raspberry Pi、Debian、Ubuntu 等），您应该编辑服务文件。 为了方便起见，已添加 db_max_retry 和 db_retry_wait 变量，以确保记录器足够多次重试与数据库的连接，以使您的数据库启动。

sudo nano /etc/systemd/system/home-assistant@homeassistant.service

并为数据库添加操作，例如 PostgreSQL：

[Unit]
Description=Home Assistant
After=network.target postgresql.service

保存文件并重新加载 systemctl：

sudo systemctl daemon-reload

安装说明

并不是所有针对所选数据库引擎的 Python 绑定都可以直接安装。本节包含应帮助您将其工作的信息。

MariaDB 和 MySQL

请确保数据库服务器的默认字符集设置为 utf8mb4（请参阅 MariaDB 文档）。 如果您在虚拟环境中，请在安装下面描述的 mysqlclient Python 包之前不要忘记激活它。

pi@homeassistant:~ $ sudo -u homeassistant -H -s
homeassistant@homeassistant:~$ source /srv/homeassistant/bin/activate
(homeassistant) homeassistant@homeassistant:~$ pip3 install mysqlclient

对于 MariaDB，您可能需要安装一些依赖项。如果您使用 MariaDB 10.3，则必须安装 libmariadb-dev-compat 包。请根据您的 MariaDB 版本安装正确的包。

在 Python 端，我们使用 mysqlclient：

sudo apt-get install libmariadbclient-dev libssl-dev
pip3 install mysqlclient

对于 MySQL，您可能需要安装一些依赖项。您可以选择 pymysql 或 mysqlclient：

sudo apt-get install default-libmysqlclient-dev libssl-dev
pip3 install mysqlclient

在安装依赖项后，必须手动创建数据库。在启动期间，Home Assistant 将查找指定在 db_url 中的数据库。如果数据库不存在，它不会为您自动创建。

数据库引擎必须是 InnoDB，因为不支持 MyIASM。

SET GLOBAL default_storage_engine = 'InnoDB';
CREATE DATABASE DB_NAME CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

其中 DB_NAME 是您的数据库名称

一旦 Home Assistant 找到数据库，并具有正确的权限，所有必需的表将自动创建并相应填充数据。

PostgreSQL

使用 utf8 编码创建 PostgreSQL 数据库。PostgreSQL 的默认编码为 SQL_ASCII。使用 postgres 用户帐户；

createdb -E utf8 DB_NAME

其中 DB_NAME 是您的数据库名称

如果正在使用的数据库不是 utf8，则将 ?client_encoding=utf8 添加到 db_url 可能会解决任何问题。

对于 PostgreSQL，您可能需要安装几项依赖：

sudo apt-get install postgresql-server-dev-X.Y
pip3 install psycopg2

要使用 Unix Sockets，首先从 postgres 用户帐户创建您的用户；

createuser USER_NAME

其中 USER_NAME 是运行 Home Assistant 实例的用户名称（请参见 确保您的安装安全）。

然后将以下行添加到您的 pg_hba.conf 中：

local DB_NAME USER_NAME peer

其中 DB_NAME 是您的数据库名称，USER_NAME 是运行 Home Assistant 实例的用户名称（请参见 确保您的安装安全）。

之后重新加载 PostgreSQL 配置：

$ sudo -i -u postgres psql -c "SELECT pg_reload_conf();"
 pg_reload_conf
----------------
 t
(1 row)

服务重启也可以。