2025.3.4
首页 ▸ Common tasks ▸

常见任务 - Supervised

配置文件访问

您的 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 SupervisedHome Assistant Supervised 是完整的 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 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 SupervisedHome Assistant Supervised 是完整的 Home Assistant 生态系统，没有 Home Assistant 操作系统。 [Learn more] 安装，并使用最新版本的 os-agent。确保您的 supervisor 使用 slave bind propagation 配置数据卷。

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

添加新的网络存储

  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

在 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" 了解有关命令的更多信息。

相关主题