Home Assistant

Home Assistant 是一个开源的家庭自动化软件，将本地控制和隐私放在首位。它由全球的修补匠和 DIY 爱好者社区驱动。

安装

安装 home-assistant 软件包。这将安装 Home Assistant 的核心版本。

Home Assistant 监督版

请参考 Home Assistant 监督版。

配置

配置文件存储在 /var/lib/hass/。如果不存在配置，则会在启动时写入默认配置。

使用

要启动 Home Assistant，启动/启用 home-assistant.service。

首次启动可能需要长达 20 分钟，因为需要下载和安装所需的软件包。[1] 您可以在日志中查看进度。

提示： 使用 journalctl 跟踪首次更新过程

# journalctl -fu home-assistant

默认情况下，Web 界面在 https://127.0.0.1:8123 上可用。

注意： Web 界面需要 home-assistant-frontend Python 软件包。

备份还原功能在 UI 中不可用。备份可以通过提取 Backup 中的 tar.gz 文件，以用户 hass 身份进行还原

# tar --strip-components=1 -xzf homeassistant.tar.gz -C /var/lib/hass

使用 MariaDB

默认情况下，SQLite 用于 Home Assistant 中的 recorder/history 集成。通过使用 MariaDB 可以实现明显的性能提升（特别是对于大型设置）。Home assistant 使用 SQLAlchemy，这意味着支持任何后端，如 MySQL、MariaDB、PostgreSQL 或 MS SQL Server。这里我们只讨论 MariaDb，对于其他数据库，请参考 recorder 集成文档。

如果尚未安装，请参考 MariaDB 获取安装详细信息。

安装 python-mysqlclient 软件包依赖项。

创建一个新的数据库，下面的示例展示了每个服务使用单个用户名，并对所有以用户名为前缀的数据库具有通配符访问权限，例如：

$ mysql -u root -p

CREATE USER 'username'@'localhost' IDENTIFIED BY 'some_pass' ;
CREATE DATABASE username;
GRANT ALL PRIVILEGES ON username.* TO 'username'@'localhost';
FLUSH PRIVILEGES;
quit;

添加到您的配置文件

/var/lib/hass/configuration.yaml

recorder:
  db_url: !secret recorder_mariadb_url

添加到您的 secrets 文件（如果未使用 Unix 套接字，请参阅 recorder 集成文档获取备用 URL）

/var/lib/hass/secrets.yaml

recorder_mariadb_url: "mysql://USER:PASSWORD@localhost/DATABASE?unix_socket=/var/run/mysqld/mysqld.sock&charset=utf8mb4"

最后，重启 home-assistant.service。数据库现在应该开始填充。有关更多信息，请参考 recorder 集成文档。

使用 Postgresql

您需要将名为 psycopg2 的 python 模块安装到 hass 的 venv 中。

您将需要添加一个 systemd drop-in 文件

/etc/systemd/system/NetworkManager.service.d/postgresql.conf

[Service]
ExecStartPre=/var/lib/hass/.venv/bin/python -m pip install psycopg2

这将确保 psycopg2 始终是一个已安装的模块。

故障排除

无法访问 USB 设备

在默认安装中，Home Assistant 可能没有必要的访问权限来使用某些设备，例如 Zigbee USB 加密狗。这是因为此类设备由 uucp 系统组控制。

编辑 home-assistant.service 并将 SupplementaryGroups=uucp 添加到 [Service] 部分，以便默认的 hass 用户属于正确的组。

然后，在 daemon-reload 和重启 home-assistant.service 后，它应该可以正常运行。[2]

蓝牙集成无法工作

如果您在使用蓝牙集成时遇到问题，并且日志中出现以下错误消息，那是因为蓝牙集成通过 dbus 连接，并且存在一个旧的 systemd 错误。

Config entry 'Bluetooth' for bluetooth integration not ready yet: DBus connection broken: [Errno 32] Broken pipe; try restarting `bluetooth` and `dbus`; Retrying in background

解决方案是切换到 dbus-broker。

或者，添加系统用户和组 hass

# useradd -U -r -s /usr/bin/nologin hass

并为 home-assistant.service 使用 drop-in 文件

/etc/systemd/system/home-assistant.service.d/override.conf

[Service]
DynamicUser=false

请注意，在某些情况下，这会由于权限问题而阻止服务启动。

另外，Passive BLE Monitor 集成需要额外的权限，以便 python 从蓝牙适配器读取原始数据。该集成文档记录的方法 sudo setcap 'cap_net_raw,cap_net_admin+eip' `readlink -f \`which python3\`` 是不够的，因为 Arch home-assistant 软件包以动态用户的身份在虚拟环境中运行 python。为了解决这个问题，请添加到服务覆盖文件

/etc/systemd/system/home-assistant.service.d/override.conf

[Service]
AmbientCapabilities=CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_RAW

有关更多信息，请参阅此用户论坛讨论。

日志中出现 ModuleNotFoundErrors

如果 Home Assistant 在系统软件包升级后损坏，则可能是由系统软件包与 Home Assistant 管理的 Python 库之间的不良交互引起的。要重置 Home Assistant 的 Python 库并从头开始重新安装它们，请删除 modules 目录

# rm -r /var/lib/hass/deps/lib

然后重启 home-assistant.service。

如果第一次重启产生更多 ModuleNotFoundErrors，则可能需要第二次重启。Home Assistant 将检测到其模块丢失并自动重新安装它们。

权限被拒绝错误循环

如果 Home Assistant 未启动，并且 journal 日志包含

home-assistant.service: Unable to locate executable '/var/lib/hass/.venv/bin/hass': Permission denied
home-assistant.service: Failed at step EXEC spawning /var/lib/hass/.venv/bin/hass: Permission denied

此问题似乎是由缺少 hass 用户/组引起的，导致 python 模块以 root 权限安装，并且 /var/lib/hass/ 文件夹被符号链接到 /var/lib/private/hass。

要解决此问题，请添加系统用户和组 hass，并更改文件夹 /var/lib/private/hass/ 的所有者

# useradd -U -r -s /usr/bin/nologin hass
# chown hass /var/lib/private/hass/

通过删除 modules 目录，重置 Home Assistant 的 Python 库并从头开始重新安装它们

# rm -r /var/lib/hass/ /var/lib/private/hass

然后重启 home-assistant.service。

现在 /var/lib/hass/ 应该是一个文件夹（而不是符号链接），用户 hass 是所有者。

参见