2025.3.4
首页 ▸ Common tasks ▸

常见任务 - Operating System

本节将提供一些常见任务的指南，以及您为运行、维护和编辑您的 Home Assistant OS 系统所需的信息。如需了解特定主题的更多详细信息，请确保参考此处列出的特定附加组件或主题的文档。

配置文件访问

您的 Home Assistant 操作服务器默认包含两个存储库：官方核心附加组件存储库和社区附加组件存储库。这里提到的所有附加组件都可以通过在 UI 中导航到附加组件商店，使用 Settings > Add-ons > Add-on Store 进行安装。

安装 Home Assistant 操作系统后，首先需要处理的事情之一是为自己提供文件访问权限。通常有几个附加组件用于此，大多数用户会混合使用各种附加组件。主机上的默认目录已映射到附加组件，以便可以通过任何特定附加组件可能提供的服务进行访问。在主机系统上，这些目录存在于 /data 分区的 /mnt/data/supervisor/ 中。

使用以下列出的任何附加组件，可以访问以下目录：

  • addons
  • backup
  • config
  • media
  • share
  • ssl

安装和使用 Samba 附加组件

Samba 附加组件允许您与网络上的其他系统共享 Home Assistant 的目录。安装附加组件后，您还可以从客户端计算机使用您喜欢的编辑器编辑文件。该附加组件可以从附加组件商店的官方存储库中安装。

要安装附加组件，请按照以下步骤操作：

  1. 转到 设置 > 附加组件 > Samba share 并选择 安装。
  2. 在 配置 选项卡上，定义 用户名 和 密码，将其存储在安全的地方，并保存更改。
    • 您可以指定任何用户名和密码。
    • 它们与您用于登录 Home Assistant 或从中访问文件的计算机的登录凭据无关。
    • 如果未定义用户名和密码，则附加组件不会启动。
  3. 有关进一步的配置信息，请参阅 文档 选项卡。
  4. 要启动附加组件，在 信息 选项卡上选择 启动。

要从其他设备访问 Home Assistant 目录，请按照以下步骤操作：

  1. 转到 设置 > 系统 > 网络 并记下 主机名。

    • 或者，您可以在路由器上查找 Home Assistant 的主机名或 IP 地址。

  2. 从另一台设备连接到 Home Assistant 的方式取决于您的系统。使用以下选项之一：

    • 在 Windows 上：打开 文件资源管理器，在地址栏中输入带有两个反斜杠的 IP 地址或主机名，例如 \\your.ha.ip.address 或 \\hostname。

      文件资源管理器显示使用 IP 地址导航到文件共享的截图 文件资源管理器显示使用 IP 地址导航到文件共享的截图

    • 在 OS X 上：打开 访达，选择 前往 > 连接服务器…，并输入 IP 地址或主机名为 smb://your.ha.ip.address 或 smb://hostname。

    • 在 Ubuntu 上：打开 文件，在地址栏中输入 IP 地址或主机名为 smb://your.ha.ip.address 或 smb://hostname。

  3. 输入您在 Samba 附加组件配置中输入的凭据。

    • 您还可以选择将凭据保存，以便不需要再次输入。

  4. 完成！您现在可以访问目录，其可以作为驱动器挂载或固定到快速访问中。

安装和使用 Visual Studio Code (VSC) 附加组件

Studio Code Server 附加组件通过功能丰富的基于 Web 的 Visual Studio Code 编辑器提供访问。目前仅支持 AMD64 和 aarch64/ARM64 机器。该附加组件还通过 VSC 内置终端提供对 Home Assistant 命令行界面 (CLI) 的访问，允许检查日志、停止和启动 Home Assistant 和附加组件、创建/恢复备份等。（有关更多信息，请参见 命令行访问 Home Assistant）。

使用 Home Assistant 操作系统安装上的文件编辑器附加组件访问的配置.yaml 文件示例的截图。 使用 Home Assistant 操作系统安装上的 Studio Code Server 附加组件访问的配置.yaml 文件示例。

要在 Home Assistant 中安装和使用 Studio Code Server，请按照以下步骤操作：

  1. 要安装附加组件，请转到 设置 > 附加组件 > Studio Code Server 并安装该附加组件。
  2. 安装附加组件后，如果需要，选择 在侧边栏中显示 选项。然后，选择 启动。
  3. 有关配置设置的信息，请打开 文档 选项卡。
  4. 要开始浏览，在 信息 选项卡上选择 打开 Web 界面。

安装和使用文件编辑器附加组件

文件编辑器 附加组件是一个基于 Web 的文件系统浏览器和文本编辑器。它是 Visual Studio Code 的更基本和轻量替代品。在编辑时，会自动检查 YAML 文件的语法错误。

使用 Home Assistant 操作系统安装上的文件编辑器附加组件访问的配置.yaml 文件示例的截图。 使用文件编辑器附加组件访问的配置.yaml 文件示例。

要在 Home Assistant 中安装和使用文件编辑器，请按照以下步骤操作：

  1. 要安装附加组件，请转到 设置 > 附加组件 > 文件编辑器。
    • 安装该附加组件后，您可以在 /config 目录中编辑文件。
  2. 如果您想访问 /config 目录外的目录，请在附加组件中打开 配置 选项卡并禁用 强制基本路径 选项。
    • 注意：强制基本路径 选项旨在保护您免于无意中更改设置文件。
  3. 有关其他配置设置的信息，请打开 文档 选项卡。
  4. 要确认您的更改，选择 保存。
  5. 要开始浏览，在 信息 选项卡上选择 打开 Web 界面。

安装和使用 SSH 附加组件

如果您想使用 Home Assistant 命令行或 SSH 客户端，您可以通过 终端与 SSH 附加组件实现。

终端与 SSH 附加组件提供以下功能：

  • 提供可以从 Home Assistant 用户界面访问的 Web 终端。
  • 允许您使用 Home Assistant 命令行界面 (CLI)，该接口提供自定义命令，以检查日志、停止和启动 Home Assistant 和附加组件、创建/恢复备份等。
  • 允许使用 SSH 客户端连接到您的系统。
  • 还包括常用工具，如 nano 和 vi 编辑器。
  • 终端与 SSH 附加组件 不提供 对基础主机文件系统的访问。

要开始使用 终端与 SSH 附加组件，请按照以下步骤操作：

  1. 在左下角选择您的用户以打开 个人资料 页面。确保启用 高级模式。
  2. 要安装附加组件，请访问附加组件商店 设置 > 附加组件 并安装 终端与 SSH 附加组件。
  3. 要使用 Web 终端，启动 附加组件，然后选择 打开 Web 界面。
    • 现在您可以开始输入您的 命令。
  4. 如果您希望通过 SSH 客户端访问，则需要输入凭据：
    • 打开 配置 页面。
    • 输入密码或授权密钥。
    • 然后保存并启动附加组件。

备份

要了解如何备份系统或如何从备份恢复系统，请参考 常见任务 下的备份文档。

替代方案：使用 Home Assistant 命令行界面创建备份

一般来说，要创建或从备份恢复，请按照 常见任务 下描述的步骤进行。但是，如果您已安装 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]，也可以从命令行创建备份。请按照以下步骤操作：

  1. ha backups list - 列出备份及其短名称
  2. ha backups restore slugname - 恢复特定备份
  3. ha backups new --name nameofbackup - 创建备份

有关命令行用法的更多信息，请使用 ha help 命令或参考 Home Assistant 命令行文档。

更新 Home Assistant

如果您已安装 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]，则会收到来自不同组件的更新通知：

  • Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]
  • Home Assistant SupervisorHome Assistant Supervisor 是一个管理 Home Assistant 安装的程序，负责安装和更新 Home Assistant、插件、它本身以及（如果使用）更新 Home Assistant 操作系统。 [Learn more]
  • Home Assistant CoreHome Assistant Core 是 Home Assistant 本身的核心。它是一个 Python 程序，支持每种安装类型，但可以独立安装。 [Learn more]
  • 如果安装了其他附加组件，则会收到更新通知

更新 Home Assistant 操作系统

Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 的更新与其他更新是独立的。它们不会触发修复问题，并且通常向后兼容。

先决条件

  • 备份 您的安装。
    • 确保备份已下载并存储在系统外部。
    • 以便在系统出现问题时，可以 从该备份恢复。

更新 Home Assistant 操作系统

  1. 打开 设置 面板。
  2. 你会在顶部看到更新通知。

如果没有看到那个通知，请在右上角选择三个点的菜单并选择 检查更新。

ha os update

这将更新到最新版本。如果你想更新到特定版本，请使用 ha os update --version 12.0。

关于更新期间使用的引导槽

Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 使用两个引导槽。在第一次安装时，使用引导槽 A。之后，在每次操作系统更新时，另一个引导槽被更新并触发重启。在重启时，系统从另一个引导槽启动（A ➝ B ➝ A,…）。当引导失败时，系统会自动使用之前的引导槽，以便从最后一个工作操作系统启动。

更改使用的引导槽

您可以手动指定使用先前的引导槽。这在系统启动但仍然有问题的情况下可能很有用。例如，当设备不再正确检测或您看到另一个可能与操作系统的最新更新相关的问题时。

  1. 要检查当前使用的引导槽以及各个槽中安装的操作系统版本，请在 Home Assistant 命令行中输入以下命令：

    ha os info

  2. 要更改引导槽，请输入以下命令：

    • 这将启动到另一个（先前的）操作系统版本。
    ha os boot-slot other

另外，如果操作系统在使用 GRUB 启动引导加载程序的平台上运行，在启动时会早期呈现一个启动菜单。可以在此选择备用引导槽，并将其标记为在后续启动中作为活动槽，如果下一次启动尝试成功。

更新 Home Assistant Core

更新 Home Assistant Core 的最佳实践：

  1. 备份您的安装，并将备份和 备份应急包 存放在安全的地方。
  2. 检查 Home Assistant 更新说明 中的向后不兼容更改。确保检查您正在运行的版本与您要升级的版本之间的所有更新说明。使用浏览器中的搜索功能 (CTRL + f / CMD + f) 搜索 向后不兼容更改。
  3. 更新 Home Assistant。
  4. 检查持久通知和日志，看是否有任何需要解决的配置问题。

当您运行 Home Assistant 操作系统 时，有 2 种方式可以更新 Home Assistant Core。

  1. 打开您的 Home Assistant UI。
  2. 导航到 设置 面板。
  3. 在顶部会出现更新通知。
    • 故障排除：如果您没有看到该通知：
      • 在右上角，选择三个点 菜单，然后选择 检查更新。
      • 转到 系统 > 更新。
        • 选择更新通知。
        • 选择齿轮图标 ，然后将 可见 设置为启用。
ha core update --backup

这里的 --backup 标志确保您在需要降级时拥有当前设置的部分备份。

网络存储

您可以配置网络文件系统 (NFS) 和 Samba/Windows (CIFS) 目标，以便在 Home Assistant 和附加组件中使用。 要列出当前连接的所有网络存储，请转到 UI 中的 设置 > 系统 > 存储。

Important

您需要更新到 Home Assistant 操作系统 10.2 才能使用此功能。

存储面板中网络共享列表的截图。

添加新的网络存储

  1. 转到 UI 中的 设置 > 系统 > 存储。
  2. 选择 添加网络存储。
  3. 填写网络存储的所有信息。
  4. 选择 连接。

连接新网络存储的截图。

网络存储配置

名称

这是系统中用于挂载目录的名称。

用途

在此处选择目标的用途。查看以下用途类型

服务器

运行 NFS/CIFS 的服务器的 IP/主机名。

协议3

服务器用于网络存储的服务。

[NFS]1 远程共享路径

用于连接到远程存储服务器的路径。

[CIFS]2 用户名

连接到存储服务器时使用的用户名。对于域账户，请使用用户主体名称。例如：user@domain.com。

[CIFS]2 密码

连接到存储服务器时使用的密码。

[CIFS]2 共享

在存储服务器上连接的共享。

1 带有 [NFS] 前缀的选项仅适用于 NFS 目标。
2 带有 [CIFS] 前缀的选项仅适用于 CIFS 目标。
3 对于 CIFS 选项，仅支持版本 2.1+。

用途类型
备份

这将成为一个目标。您可以在创建自动或手动备份时使用它。您添加的第一个此类型存储将成为新的默认目标。如果您想更改默认目标，请查看以下文档。

媒体

一个新目录将以您为网络存储提供的名称创建在 /media 下。此目录可供 Home Assistant 和附加组件访问。

共享

一个新目录将以您为网络存储提供的名称创建在 /share 下。此目录可供 Home Assistant 和附加组件访问。

更改默认本地备份位置

默认情况下，您添加的第一个类型为 备份 的网络存储将用作默认本地备份位置。

如果您想更改用于存储备份的本地网络存储，请按照以下步骤操作：

  1. 转到 设置 > 系统 > 备份。
  2. 在右上角，选择三点菜单 并选择 更改本地备份位置。
  3. 选择您首选的网络位置并保存更改。 选择用于本地备份的默认位置
  4. 故障排除: 看不到您的外部存储位置？此列表仅包含您添加的类型为 备份 的网络存储目标。

忘记密码和密码重置

请参考 我被锁定了! 文档页面。

安装第三方插件仓库

Home Assistant 允许任何人创建一个插件仓库，与社区分享他们自己的插件。

Warning

Home Assistant 无法保证第三方插件的质量或安全性。使用风险自负。

要添加一个插件仓库，请按照以下步骤操作：

  1. 复制仓库的 URL。

    • URL 是 git 仓库的克隆 URL（在 GitHub 上，使用代码按钮并复制 HTTPS URL）。

    • 本文档使用一个示例插件仓库。它并没有实际用途，但遵循相同的步骤。

    • 如果您对插件开发感兴趣，请参考我们的 插件开发文档。

      https://github.com/home-assistant/hassio-addons-example
  2. 转到 设置 > 插件 并选择 插件商店。 插件商店截图
  3. 在右上角，选择三点 菜单，选择 仓库。
  4. 添加仓库的 URL 并选择 添加。 插件商店截图
    • 结果：会出现一个新卡片，显示仓库。 插件商店截图

故障排除：仓库未显示

如果您已添加插件仓库，但未显示，请确保刷新您的浏览器。如果仍然没有显示，则插件仓库可能包含无效的配置数据。

  1. 转到 设置 > 系统 > 日志 并在右上角选择 Supervisor 以获取 Supervisor 日志。
    • 这应该会告诉您出了什么问题。
  2. 将这些信息报告给插件仓库的作者。

配置检查

在更改配置或自动化文件后，请检查配置是否有效，然后再重新启动 Home Assistant Core。

从用户界面运行配置检查

  1. 前往 你的用户个人资料 并启用 高级模式。
  2. 前往 开发者工具 > YAML，在 配置验证 部分，选择 检查配置 按钮。
    • 这确保在重新启动 Home Assistant 之前没有语法错误。
    • 它会检查有效的 YAMLYAML 是一种人类可读的数据序列化语言。它用于以结构化格式存储和传输数据。在 Home Assistant 中，YAML 用于配置，例如在 configuration.yaml 或 automations.yaml 文件中。 [Learn more] 以及有效的配置结构。
  3. 如果您需要进行更全面的配置检查，请 从 CLI 运行检查。

从 CLI 运行配置检查

使用以下命令检查配置是否有效。命令行配置检查验证 YAMLYAML 是一种人类可读的数据序列化语言。它用于以结构化格式存储和传输数据。在 Home Assistant 中，YAML 用于配置，例如在 configuration.yaml 或 automations.yaml 文件中。 [Learn more] 文件并检查有效的配置结构以及其他一些元素。

ha core check

Home Assistant 版本

要查看您的系统运行哪个版本，请转到 设置 > 关于。

运行特定版本

要升级到特定版本，可以使用 CLI。下面的示例展示了如何升级到 2025.3.4。

ha core update --version 2025.3.4 --backup

这里的 --backup 标志确保您有当前设置的部分备份，以防您需要稍后降级。

要降级您的安装，请进行 部分恢复备份。

运行测试版

如果您想在其他人之前测试下一个版本，您可以安装测试版。

  1. 在 Home Assistant 中，转到 系统 > 更新。
  2. 在右上角，选择三个点的菜单。
  3. 选择 加入测试版。
  4. 转到 配置 面板。
  5. 安装呈现给您的更新。
    • 故障排除：如果您没有看到该通知：
      • 在右上角，选择三个点的菜单 ，然后选择 检查更新。
      • 转到 系统 > 更新。
        • 选择更新通知。
        • 选择齿轮 ，然后将 可见 设置为活动状态。

  1. 加入测试频道。

    ha supervisor options --channel beta

  2. 重新加载 Home Assistant 管理器。

    ha supervisor reload

  3. 将 Home Assistant Core 更新到最新的测试版。

    ha core update --backup

    这里的 --backup 标志确保您拥有当前设置的部分备份，以防需要降级。

运行开发版本

如果您想使用最新的 Home Assistant Core 开发分支，您可以升级到 dev。

Caution

dev 分支可能是不稳定的。潜在后果包括数据丢失和实例损坏。

  1. 加入 dev 频道。

    ha supervisor options --channel dev

  2. 重新加载 Home Assistant SupervisorHome Assistant Supervisor 是一个管理 Home Assistant 安装的程序，负责安装和更新 Home Assistant、插件、它本身以及（如果使用）更新 Home Assistant 操作系统。 [Learn more]。

    ha supervisor reload

  3. 将 Home Assistant CoreHome Assistant Core 是 Home Assistant 本身的核心。它是一个 Python 程序，支持每种安装类型，但可以独立安装。 [Learn more] 更新到最新的 dev 版本。

    ha core update --backup

    这里的 --backup 标志确保您有当前设置的部分备份，以防需要降级。

使用外部数据磁盘

Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 支持将数据存储在辅助存储介质上。例如，这可以是第二个内部 SSD 或 HDD，或是 USB 连接的 SSD 或 HDD。此数据磁盘不仅包含用户数据，还包含大部分 Home Assistant 软件（核心、管理程序等）。这意味着快速的数据磁盘将使系统整体运行更快。

显示数据磁盘功能架构的图形

数据磁盘功能可以在现有安装中使用而不丢失数据：系统会自动将现有数据迁移到外部数据磁盘上。然而，建议在继续之前创建并下载完整的 备份！

Caution

目标磁盘上的所有数据将被覆盖！

Important

外部数据磁盘的存储容量必须大于现有（启动）磁盘的存储容量。

Important

如果您之前使用 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 使用了数据磁盘，则需要使用主机计算机在将其再次用作数据磁盘之前删除所有分区。

使用用户界面移动数据分区

  1. 将数据磁盘连接到您的系统。
  2. 在 UI 中进入 设置 > 系统 > 存储。
  3. 选择 移动数据磁盘。
  4. 从可用设备列表中选择数据磁盘。
  5. 选择 移动。
    • 根据数据量，可能需要一段时间。

使用命令行界面移动数据分区

要查看当前的数据磁盘，请使用：

$ ha os info
...
data_disk: /dev/mmcblk1p4
...

要获取可由 datadisk 使用的潜在目标列表：

ha os datadisk list

要启动移动到新数据磁盘的操作，请使用 move 命令：

ha os datadisk move /dev/sdx

系统将准备数据磁盘并立即重启。重启可能需要 10 分钟或更长时间，具体取决于新数据磁盘的速度；请耐心等待！

Warning

使用 USB 连接的 SSD 可能会消耗相当多的电力。例如，在 Raspberry Pi 3 上，官方的 Raspberry Pi 电源（PSU）仅提供 2.5A，这可能会太紧张。如果遇到问题，请使用更强大的电源。或者使用一个有电源的 USB 集线器。将集线器连接到 Raspberry Pi 的一个 USB 插槽，然后将 SSD 连接到集线器。在此设置中，集线器的电源将为已连接的设备供电。

将外部数据磁盘迁移到另一个系统

本节介绍如何将外部数据磁盘从一个系统移动到另一个系统。 如果以下元素适用于您的用例，这可以是一种选择：

  • 您已经有一个功能正常的 Home Assistant 实例（系统 1），它使用外部数据磁盘。
  • 您有另一个新的 Home Assistant 实例（系统 2）。
  • 您现在想在系统 2 上使用系统 1 的数据磁盘。

目标是将数据从系统 1 迁移到系统 2。实现这一目标的一个方法是 恢复备份。另一种方法是移动数据磁盘。如果您在外部磁盘上有大量数据，或者您的外部磁盘比新系统有更大的存储容量，则这可能是一个有趣的选择。

先决条件

  • 一个使用外部数据磁盘的 Home Assistant 实例（系统 1）
  • 一个您想将外部数据磁盘迁移到的 Home Assistant 实例（系统 2）

将外部数据磁盘迁移到另一个系统

要将外部数据磁盘从一个系统迁移到另一个系统，请按照以下步骤操作：

  1. 创建备份 并将这两个系统的备份存储在另一个系统上（这不是严格必要的，但建议这样做，以防万一，至少对于重要数据）。
  2. 关闭系统 1 并移除数据磁盘。
  3. 确保系统 2 已安装 Home Assistant OS，并且 Home Assistant 正在运行。此时 Home Assistant 正在使用启动驱动器（例如 SD 卡）上的数据磁盘（分区）。
  4. 确保系统 2 已完成基本的 入门 步骤，包括最后的步骤，其中设备会自动发现。
  5. 将外部磁盘插入系统 2，进入 设置 > 系统。选择三个点 菜单，选择 重启 Home Assistant > 重启系统。 结果：显示修复问题 检测到多个数据磁盘。
    • 修复问题出现的原因是系统 2 现在看到两个具有相同名称的文件系统。在重启期间，现有数据磁盘引发了名称冲突，因为未定义应使用哪个文件系统。这可能导致您最终随机选择的系统。因此，您必须做出决策。
  6. 打开修复问题并选择一个选项：
    • 选择 使用检测到的数据磁盘而不是当前系统。
      • 这将覆盖系统 2 的当前文件系统，使用您的外部数据磁盘。
      • 您将无法再访问当前的 Home Assistant 数据。它将被标记为非活动数据磁盘。
    • 如果您改变了对使用外部数据磁盘的想法：
      • 拔掉外部数据磁盘。
      • 如果由于某种原因无法拔掉外部数据磁盘，请选择 标记为非活动数据磁盘（重命名文件系统）。
        • 这确保在重启后不会出现名称冲突。
        • 这也意味着您无法使用存储在外部磁盘上的文件系统。
        • 您继续使用系统 1 的当前文件系统。

通过命令行访问 Home Assistant

在 SSH 命令行 中，您可以使用 ha 命令来检索日志、检查已连接硬件的详细信息等。

Home Assistant 

ha core check
ha core info
ha core logs
ha core options
ha core rebuild
ha core restart
ha core restart --safe-mode
ha core start
ha core stats
ha core stop
ha core update

Supervisor 

ha supervisor info
ha supervisor logs
ha supervisor reload
ha supervisor update

主机 

ha host reboot
ha host shutdown
ha host update

硬件 

ha hardware info
ha hardware audio

用法示例

要将 Home Assistant 更新到特定版本，请使用以下命令：

ha core update --version x.y.z

将 x.y.z 替换为您想要的版本，例如 --version 2025.3.4

您可以通过输入 ha help 获取 CLI 功能的更好描述：

Home Assistant CLI 是一个小而简单的命令行工具，允许您控制和配置 Home Assistant 的不同方面。

用法：
  ha [command]

可用命令：
  addons         安装、更新、删除和配置 Home Assistant 插件
  audio          音频设备处理。
  authentication Home Assistant 用户的身份验证。
  backups        创建、恢复和删除备份
  banner         打印 CLI Home Assistant 横幅以及一些有用的信息
  cli            获取信息、更新或配置 Home Assistant cli 后端
  core           提供对 Home Assistant Core 的控制
  dns            获取信息、更新或配置 Home Assistant DNS 服务器
  docker         针对信息和 OCI 配置的 Docker 后端
  hardware       提供有关您系统的硬件信息
  help           有关任何命令的帮助
  host           控制运行 Home Assistant 的主机/系统
  info           提供一般的 Home Assistant 信息概述
  jobs           获取信息并管理正在运行的作业
  multicast      获取信息、更新或配置 Home Assistant 多播
  network        针对更新、信息和配置导入的网络
  observer       获取信息、更新或配置 Home Assistant 观察者
  os             针对更新、信息和配置导入的操作系统
  resolution     Supervisor 的解决中心，显示问题并建议解决方案
  supervisor     监视、控制和配置 Home Assistant Supervisor

标志：
      --api-token string   Home Assistant Supervisor API 令牌
      --config string      可选的配置文件（默认是 $HOME/.homeassistant.yaml）
      --endpoint string    Home Assistant Supervisor 的端点（默认是 'supervisor'）
  -h, --help               ha 的帮助
      --log-level string   日志级别（默认为 Warn）
      --no-progress        禁用进度指示器
      --raw-json           从 API 输出原始 JSON

使用 "ha [command] --help" 了解有关命令的更多信息。

控制台访问

您还可以通过直接连接的键盘和显示器访问 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]，即控制台。

从命令行擦除数据磁盘

在 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 中，ha os datadisk wipe 命令会擦除数据磁盘。该命令删除所有用户数据以及 Home Assistant Core、Supervisor 和任何已安装的插件。

命令 ha os datadisk wipe 将数据分区（无论是 eMMC 上的内部存储卡还是外部附加的数据磁盘）标记为在下次重启时清除。该命令会自动重启系统。重启后，数据将被清除。然后系统将继续启动并重新安装所有 Home Assistant 组件的最新版本。

ha os datadisk wipe 命令只能从本地终端运行。连接一个显示器和键盘并使用终端。

请注意，一些系统有重置按钮，您可以使用该按钮来清除数据磁盘，而无需使用命令行：

  • 如果您拥有搭载 Raspberry Pi Compute Module 5 的 Home Assistant Yellow，请使用上面描述的命令行步骤。

  • 如果您拥有搭载 Raspberry Pi Compute Module 4 的 Home Assistant Yellow，则有一个红色硬件按钮可以擦除数据磁盘。请按照 重置 Home Assistant Yellow 的程序进行操作。

  • 如果您拥有 Home Assistant Green，则有一个黑色硬件按钮可以擦除数据磁盘。请按照 重置 Home Assistant Green 的程序进行操作。

从命令行列出所有用户

在 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 中，ha auth list 命令列出注册在您 Home Assistant 上的所有用户。

ha auth list 命令只能从本地终端运行。连接一个显示器和键盘并使用终端。

启用 I2C

Home Assistant 使用 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]，这是一种管理环境，这意味着您不能使用现有的方法在 Raspberry Pi 上启用 I2C 总线。要使用 I2C 设备，您必须

  • 为 Home Assistant Operating System 启用 I2C
  • 设置 I2C 设备，例如传感器

使用 SD 卡读取器启用 I2C

访问启动分区

您需要：

  • SD 卡读取器
  • 已刷写 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 的 SD 卡

关闭/关闭您的 Home Assistant 安装并拔掉 SD 卡。 将 SD 卡插入 SD 卡读取器，并找到一个名为 hassos-boot 的驱动器/文件系统。文件系统可能会自动显示/挂载。如果没有，请使用您的操作系统磁盘管理工具查找 SD 卡读取器，并确保第一个分区是可用的。

添加文件以启用 I2C

  • 在 hassos-boot 分区的根目录中，添加一个名为 CONFIG 的新文件夹。
  • 在 CONFIG 文件夹中，添加另一个名为 modules 的新文件夹。
  • 在 modules 文件夹中添加一个名为 rpi-i2c.conf 的文本文件，内容如下： 
    i2c-dev
  • 在 hassos-boot 分区的根目录中，编辑名为 config.txt 的文件，并添加两行内容： 
    dtparam=i2c_vc=on
dtparam=i2c_arm=on

从新的操作系统配置开始

  • 将 SD 卡插回您的 Raspberry Pi。
  • 启动时，hassos-config.service 将自动识别新的 rpi-i2c.conf 配置。
  • 可能需要再次重启，以确保刚导入的 rpi-i2c.conf 在启动时处于可用状态。

通过 Home Assistant Operating System 终端启用 I2C

或者，通过将键盘和屏幕连接到您的设备，您可以访问 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 的物理终端。

您可以通过该终端启用 I2C：

  • 以 root 身份登录。

  • 输入 login 并按 Enter 访问 shell。

  • 输入以下内容以启用 I2C，您可能需要根据平台将 sda1 替换为 sdb1 或 mmcblk0p1：

    mkdir /tmp/mnt
mount /dev/sda1 /tmp/mnt
mkdir -p /tmp/mnt/modules
echo -ne i2c-dev>/tmp/mnt/modules/rpi-i2c.conf
echo dtparam=i2c_vc=on >> /tmp/mnt/config.txt
echo dtparam=i2c_arm=on >> /tmp/mnt/config.txt
sync
reboot

故障排除

重启主机后，/dev 中应该有 i2c-0 和类似的设备文件。如果此类设备文件缺失，则启用 I2C 由于某种原因失败。您可以使用 lsmod | grep i2c 在终端检查 I2C 内核模块的状态。如果它们已加载，您应该至少找到 i2c_dev 条目。模块的活动使用由一个数字表示，例如 i2c_dev 20480 2 表示有两个活动的 I2C 设备文件。

还可以使用万用表检查活动 I2C，显示 I2C 引脚 GPIO2 和 GPIO3 上的 3.3 V。

相关主题