HA Bridge

Appearance

HAOS（冬瓜）部署 ​

本教程适用于能够正常打开 Home Assistant 商店的冬瓜系统。安装后，HA Bridge 会由 Home Assistant 统一管理启动、更新和备份，不需要手动执行 Docker 命令。

先确认安装方式

打开 Home Assistant 的「设置」，如果可以看到「Add-ons」并进入 Add-on 商店，请使用本教程。如果系统没有 Add-on 商店，说明当前环境不是带 Supervisor 的 HAOS，请改用通用 Docker 部署与更新。

一、部署前准备 ​

开始前请确认：

  • Home Assistant 已经正常运行；
  • 当前账号拥有管理员权限；
  • 系统可以访问 GitHub 和 HA Bridge 阿里云镜像仓库；
  • 端口 18080 没有被其他 Add-on 或服务占用。

HA Bridge Add-on 同时支持 AMD64 和 ARM64，安装时会自动选择与当前设备匹配的镜像，不需要手动选择架构。

在 Home Assistant 中打开「设置」，进入「应用」（Add-ons）。

在 Home Assistant 设置中进入应用

进入应用页面后，点击右下角的「安装应用」。

在应用页面点击安装应用

二、添加 HA Bridge 仓库 ​

  1. 打开 Home Assistant，进入「设置 → Add-ons」。
  2. 点击右下角的「Add-on 商店」。
  3. 点击右上角的菜单按钮，选择「仓库」。
  4. 在仓库地址中粘贴：
text
https://github.com/weidaye1122/ha-bridge-addon
  1. 点击「添加」，等待仓库刷新完成。
  2. 返回 Add-on 商店，找到并打开「HA Bridge」。

打开 Add-on 商店右上角菜单，选择「仓库」。

在应用商店菜单中打开仓库

仓库列表页面会显示当前已配置的仓库。

查看当前仓库列表

在「添加仓库」对话框中粘贴 HA Bridge 仓库地址，然后点击「添加」。

添加 HA Bridge 仓库地址

添加完成后，返回仓库列表确认「HA Bridge Add-ons」已经出现。

确认 HA Bridge Add-ons 已添加

在应用商店搜索框中输入「HA Bridge」，即可看到安装项。

在应用商店搜索 HA Bridge

添加后暂时搜不到

先关闭仓库窗口，重新打开 Add-on 商店并刷新页面。如果仍未出现，请确认仓库地址完整且没有多余空格，并检查系统是否能够访问 GitHub。

三、安装并启动 HA Bridge ​

  1. 在 HA Bridge 页面点击「安装」。
  2. 等待镜像下载和安装完成，首次安装所需时间取决于当前网络速度。
  3. 安装完成后，建议开启「开机启动」和「自动恢复」。
  4. 点击「启动」。
  5. 页面右上角显示「运行中」后，点击「打开网页界面」。

也可以在同一局域网的浏览器中直接打开：

text
http://Home Assistant_IP:18080

请将 Home Assistant_IP 替换为自己的 Home Assistant 局域网 IP 地址。

HA Bridge Add-on 详情页中的安装按钮

安装完成后，在页面中点击「启动」。

安装完成后启动 HA Bridge

启动成功后，页面显示「运行中」，此时可以点击「打开网页界面」。

HA Bridge 显示运行中

四、完成首次设置 ​

第一次打开 HA Bridge 时，按照页面提示完成以下设置：

  1. 创建 HA Bridge 本地管理员账号；
  2. 输入 HA Bridge 激活码；
  3. 填写 Home Assistant 地址；
  4. 填写 Home Assistant 长期访问令牌；
  5. 保存并确认连接状态正常。

首次打开 HA Bridge 时创建本地管理员账号

详细操作请继续阅读：首次设置与激活和连接 Home Assistant。

五、更新 HA Bridge ​

HA Bridge Add-on 发布新版本后，Home Assistant 会在 HA Bridge 页面显示可用更新。独立 Docker 的 beta 或 latest 镜像更新，不代表 Add-on 已同步提供该版本；以 Add-on 页面可用版本为准。

  1. 进入「设置 → Add-ons → HA Bridge」。
  2. 如果页面暂未显示新版本，进入 Add-on 商店并执行一次「检查更新」。
  3. 返回 HA Bridge Add-on 页面，点击「更新」。
  4. 等待更新完成并重新启动。
  5. 确认页面显示「运行中」，再打开网页界面检查版本和原有数据。

更新时不要卸载 Add-on，也不要删除 Add-on 数据。/data 保存数据库、项目、素材、授权状态、Home Assistant 链接及本地账号，/run/secrets 保存本地安全信息。

支持独立账号文件的新版还会在 Add-on 自己的 /data 中保存 admin-account.json，正常升级时保留它。该目录不是 Home Assistant 的 /config，也不一定能从普通文件编辑器中访问。

六、备份与恢复 ​

在 Home Assistant 创建备份时，请确认备份中包含 HA Bridge Add-on 数据。建议在更新、迁移或重装前先创建一次完整备份。

恢复时应同时恢复 HA Bridge Add-on 及其数据，避免只恢复应用而遗漏原有仪表盘、账号和连接配置。

七、常见问题 ​

添加仓库后找不到 HA Bridge ​

重新打开 Add-on 商店并检查更新；确认仓库地址为：

text
https://github.com/weidaye1122/ha-bridge-addon

安装时提示无法拉取镜像 ​

确认 Home Assistant 主机可以访问互联网，然后重新尝试安装。如果仍然失败，请打开系统日志查看具体的镜像下载错误。

启动后打不开网页 ​

先确认 Add-on 页面显示「运行中」，再打开日志检查启动状态。同时确认局域网内没有其他服务占用端口 18080。

更新后原有数据不见了 ​

不要重新创建本地账号或覆盖配置，先停止 Add-on 并检查是否曾卸载或删除 Add-on 数据。如果已经创建过 Home Assistant 备份，请优先从更新前的备份恢复。

忘记 HA Bridge 本地账号或密码 ​

查看重置本地账号与密码，先确认当前 Add-on 版本已包含该功能。只处理 HA Bridge 自己的账号文件，不要卸载并清除应用数据，也不要修改 Home Assistant 账号。

让 Home Assistant 的日常使用更直观。

HA Bridge