Appearance
连接 Home Assistant
HA Bridge 通过 Home Assistant API 读取状态并调用服务，需要 HA 服务地址和长期访问令牌。
1. 打开连接设置
登录 HA Bridge，点击顶部「HA 未配置」；已有连接时点击 HA 状态按钮，再点击「修改」。填写连接名称、HA 地址和令牌。
2. 创建长期访问令牌
- 打开 Home Assistant，点击左下角的用户名。
- 打开「安全」选项卡，滑动到「长期访问令牌」区域。
- 点击「创建令牌」，填写容易识别的名称，例如
ha_bridge。 - 复制生成的完整令牌并妥善保存。
令牌只完整显示一次；忘记后需重新创建。不要公开令牌或包含令牌的截图。
3. 填写实际服务地址
建议粘贴平时访问 HA 的服务地址。新版可以只填写 IP 或域名，按需带端口；不用单独选择 HTTP / HTTPS。
| 你的 HA 服务 | 填写示例 | 说明 |
|---|---|---|
| 内网 HTTP，端口 80 | 192.168.1.100:80 | 填写 80 就使用 80，不再尝试 8123 |
| 内网 HTTP，端口 8123 | 192.168.1.100:8123 | 只有实际开放 8123 才填写这个端口 |
| 不清楚常用端口 | 192.168.1.100 | 程序只探测默认 80/443 与 8123，不扫描任意端口 |
| 域名、有可信证书 | https://ha.example.com | 明确指定 HTTPS，保持证书验证开启 |
| 域名、只提供 HTTP | http://ha.example.com | 无需证书；域名不代表一定启用了 HTTPS |
| 自定义 HTTPS 端口 | https://ha.example.com:8443 | 按实际端口填写 |
| 反向代理服务前缀 | https://example.com/ha | 仅当代理确实把 /ha 转发给 HA 时使用 |
| IPv6 | http://[fd00::1]:8123 | IPv6 地址需要方括号 |
不要把所有 HAOS 都当作 8123 端口。 端口取决于 HA 及反向代理的实际配置。明确填写的协议、端口和服务前缀会被保留。
不要带 /lovelace/...、/dashboard-...、/config/... 等页面路径，也不要带账号密码、查询参数或 #。如果不确定，优先复制能访问的 HA 服务根地址。
4. 测试并保存
- 粘贴完整长期访问令牌。首次配置不能为空；修改已有连接时留空会继续使用原令牌，测试连接也支持留空。
- 点击「测试连接」。程序先识别地址，再验证令牌和 WebSocket 实时连接。
- 成功后地址框会显示实际识别的完整地址，核对后点击「保存并连接」。
- 等待状态显示「已连接并实时同步」，再检查实体、设备和区域数量。
上图为隔离演示环境，127.0.0.1:18896 不是通用配置，请换成自己的 HA 地址。正常新安装、尚未添加设备的 HA 可以显示零实体；零数量不等于连接失败。
保存时会再次验证；验证失败不会覆盖原有连接。之后 HA 新增或修改设备，等待同步即可在实体选择器中使用。
完成标志： 状态显示「已连接并实时同步」。继续绘制 3D 户型。
HTTPS、自签名证书与旧版地址填写
- HTTP 服务：不使用证书，无需修改高级设置。关闭证书验证不会把 HTTPS 变成 HTTP。
- HTTPS + 可信证书：使用证书对应的域名，保持「验证安全证书（推荐）」开启。
- HTTPS + 自签名证书：建议安装可信证书。确认服务器身份、理解风险后，才在「高级设置 · HTTPS 证书」取消验证；这个选择仅作用于当前 HA 连接。
- 证书过期、域名不匹配、证书链不完整：优先修复对应问题；不要把关闭验证作为通用排错方式。
图中正在修改的域名仅为示例，尚未保存；底部同步状态属于原有连接。
填写 HTTPS 地址或遇到证书错误时会显示高级设置。自动识别不会偷偷关闭证书验证；遇到证书验证失败时也不会自动降级到 HTTP。内网 IP 不一定提供 HTTPS，域名也可能只提供 HTTP，应以实际服务为准。
旧版若要求完整 URL，请填写 http:// 或 https:// 开头的实际服务地址。
连接失败：按提示排查
| 提示或现象 | 下一步怎么做 |
|---|---|
| 地址或端口格式不正确 | 去掉空格、账号密码、页面参数；端口范围为 1–65535；IPv6 用方括号 |
| 无法读取已保存的令牌 | 检查原有 secrets 密钥目录和读取权限，或重新填写长期令牌 |
| 访问令牌格式不正确 | 重新复制完整令牌，去掉中文、空格和换行 |
| 请填写长期访问令牌 | 首次连接粘贴完整令牌；已有连接可留空复用 |
| 无法解析域名 | 检查拼写、DNS；容器可能无法解析 .local，可改填能访问的内网 IP |
| 拒绝连接 | 确认 HA 已启动，核对实际端口；80 与 8123 不能混用 |
| 连接超时 / 无法连接 | 检查 HA Bridge 所在设备的路由、防火墙、容器网络和端口映射 |
| 令牌无效、已失效或权限不足 | 重新创建长期令牌；同时检查反向代理是否拦截 Authorization 或限制访问 |
| 协议与服务不匹配 | 核对服务到底使用 HTTP 还是 HTTPS；关闭证书验证不能修复协议不匹配 |
| 安全证书不受信任或证书链不完整 | 配置可信证书/完整证书链；自签名证书参考上文高级设置 |
| 安全证书已过期 | 更新证书，并核对设备系统时间 |
| 证书与地址不匹配 | 改用证书对应域名，不要用 IP 代替域名 |
| 地址发生跳转 | 使用最终 HA 服务地址；检查是否被代理跳到额外登录页 |
| 未返回接口 / 返回网页或无效数据 / 404 | 检查是否填到了 NAS、代理管理页或仪表盘页面；核对服务前缀 |
| 实时连接失败或中断 | 代理必须支持 /api/websocket 的 WebSocket 转发；检查网络和代理超时 |
| 请求过于频繁 / 429 | 稍后重试，并检查代理限流策略，避免连续点击 |
| 服务暂时不可用 / 500、502、503、504 | 检查 HA 与代理服务状态，恢复后重试 |
| HA Bridge 不在线或无法完成请求 | 检查浏览器到 HA Bridge 的网络，以及 HA Bridge 服务是否在重启 |
| 其他连接失败 | 打开 HA Bridge 日志查看对应时间的详细诊断，反馈时隐藏令牌和私密地址 |
手机能打开 HA，不代表 HA Bridge 所在的 NAS / Docker 容器也能访问。 若部署在容器里，127.0.0.1 通常指容器自身；请使用容器能访问的 HA 地址。HA Bridge 网页使用 HTTPS，也不要求内网 HA 必须使用 HTTPS，HA 请求由后端发起。
测试失败后可以直接修改并重试，不必删除连接、清空数据或重装。已有连接断开时后台会按原配置重连，不会重新探测端口、更换协议或改变证书设置。