2025.3.4
首页 ▸ 文档 ▸

认证

认证系统保护对 Home Assistant 的访问。

登录界面

您会看到一个登录界面，要求您输入用户名和密码。

从本地网络外部登录时的登录界面截图

用户账户

当您第一次启动 Home Assistant 时，所有者 用户账户将被创建。此账户具有一些特殊权限，可以：

  • 创建和管理其他用户账户。
  • 配置集成和其他设置（即将推出）。

Warning

目前，其他用户账户将拥有与所有者账户相同的访问权限。在未来，非所有者账户将可以限制其访问权限。

Note

如果您想管理用户并且是所有者，但在主配置菜单中没有看到“用户”，请确保您的个人资料中已为您的用户启用 高级模式。

您的账户资料

登录后，您可以通过选择侧边栏底部的圆圈，在 用户资料 页面上查看您的账户详细信息。

个人资料页面截图

您可以：

  • 更改您的密码。
  • 启用或禁用 多因素认证。
  • 删除 刷新令牌。这些是在您从设备登录时创建的。如果您想强制设备注销，请删除它们。
  • 创建 长期访问令牌，以便脚本可以安全地与 Home Assistant 进行交互。
  • 定义语言和其他地区设置。
  • 从 Home Assistant 注销。

Note

未使用的刷新令牌将被自动移除。如果在 90 天内没有用于登录，则刷新令牌被视为未使用。如果您需要永久令牌，则建议使用 长期访问令牌。

确保您的登录安全

确保选择一个安全的密码！ 在将来的某个时间，您可能想要从本地网络外部访问 Home Assistant。这意味着您也会面临随机黑客尝试进行同样操作的风险。将密码视为您家的钥匙。

为了额外的安全性，您可以启用 多因素认证。

向 Home Assistant 添加人员

如果您具有管理员权限，您可以 向 Home Assistant 添加人员 并为其创建用户账户。

更改显示名称或用户名

要了解如何更改显示名称或用户名，请参考 设置基本信息。

其他认证技术

Home Assistant 提供了几种身份验证方式。请查看 认证提供者 部分。

故障排除

来自 127.0.0.1 的认证失败

如果您看到来自 127.0.0.1 的认证失败，并且您正在使用 nmap 设备跟踪器，则应 排除 Home Assistant IP 以免被扫描。

令牌警告

在新的认证系统下，当提供 旧版 API 密码 但未在 Home Assistant 中配置时，您将看到以下警告日志：

WARNING (MainThread) [homeassistant.components.http.auth] 您需要使用承载令牌来访问 /blah/blah 从 192.0.2.4

如果您看到此消息，您需要在 http: 配置中添加 api_password。

承载令牌信息消息

如果您看到以下信息，则这是给集成开发者的消息，告诉他们需要更新如何向 Home Assistant 进行认证。作为最终用户，您无需做任何事情：

INFO (MainThread) [homeassistant.components.http.auth] 您需要使用承载令牌来访问 /blah/blah 从 192.0.2.4

丢失所有者密码

如果您丢失了与所有者账户关联的密码，您需要 启动新的引导过程。

错误：无效的客户端 ID 或重定向 URL

错误：无效的客户端 ID 或重定向 URL 的截图

您必须使用域名，而不是 IP 地址，来远程访问 Home Assistant，否则会在登录表单上收到 错误：无效的客户端 ID 或重定向 URL 错误。但是，您可以在家庭网络中使用 IP 地址访问 Home Assistant。

这是因为我们仅允许将 IP 地址用作客户端 ID，当您的 IP 地址是内部网络地址（例如，192.168.0.1）或环回地址（例如，127.0.0.1）时。

如果您没有 Home Assistant 实例的有效域名，您可以修改计算机上的 hosts 文件来伪造一个。在 Linux 上编辑 /etc/hosts 文件，并添加以下条目：

12.34.56.78 homeassistant.home

将 12.34.56.78 替换为您 Home Assistant 的公共 IP 地址。

这将允许您在 http://homeassistant.home:8123/ 打开 Home Assistant。

数据加载中卡住

一些广告拦截软件，如 Wipr，也会阻止 WebSockets。如果您在加载数据的屏幕上卡住，请尝试禁用广告拦截器。