HAOS（冬瓜）部署

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

先确认安装方式

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

一、部署前准备

开始前请确认：

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

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

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

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

二、添加 HA Bridge 仓库

首次安装优先使用 Gitee 国内仓库；如果 Gitee 无法访问，再使用 GitHub 备用仓库。两个地址提供同一个 HA Bridge Add-on，首次安装选择一个地址即可。

1. 打开 Home Assistant，进入「设置 → Add-ons」。
2. 点击右下角的「Add-on 商店」。
3. 点击右上角的菜单按钮，选择「仓库」。
4. 在仓库地址中粘贴 Gitee 国内仓库（推荐）：

https://gitee.com/weidaye1122/ha-bridge-addon

5. 点击「添加」，等待仓库刷新完成。
6. 返回 Add-on 商店，找到并打开「HA Bridge」。

GitHub 备用仓库（Gitee 无法访问时使用）：

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

已经安装过 HA Bridge

请先阅读已有安装的更新源说明。添加另一个仓库不会自动迁移原有安装和数据。

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

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

在「添加仓库」对话框中粘贴上面的 Gitee 地址，然后点击「添加」。请完整复制地址，避免多余空格。

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

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

添加后暂时搜不到

先关闭仓库窗口，重新打开 Add-on 商店并执行「检查更新」。如果仍未出现，请确认仓库地址完整且没有多余空格，并检查 Home Assistant 主机是否能够访问所选仓库（优先 Gitee，备用 GitHub）。电脑浏览器能打开仓库，不代表 Home Assistant 主机也能正常拉取。

三、安装并启动 HA Bridge

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

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

http://Home Assistant_IP:18080

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

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

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

四、完成首次设置

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

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

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

五、更新 HA Bridge

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

Gitee 国内仓库会从 GitHub 自动同步，发布后可能存在同步延迟。Add-on 版本可能带有适配修订号，例如 0.6.5-1 对应 HA Bridge 0.6.5。

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，也不一定能从普通文件编辑器中访问。

已有安装的更新源说明

• 从 Gitee 安装的用户，继续通过 Gitee 仓库检查更新。
• 从 GitHub 安装的用户，继续在原有 HA Bridge Add-on 页面更新；GitHub 备用仓库仍保留更新。
• 添加 Gitee 仓库不会自动将原 GitHub 安装切换到 Gitee。Home Assistant 可能将不同仓库中的同名 Add-on 识别为独立安装，数据也不会自动合并。

已有 GitHub 安装但收不到更新时，先按下方更新不显示的排查步骤检查原仓库。需要迁移到 Gitee 时，先创建包含 HA Bridge Add-on 及其数据的完整备份，并确认迁移方案；不要直接卸载原 Add-on 后重装，当前教程不提供未经实机验证的跨仓库迁移步骤。

六、备份与恢复

日常导出仪表盘、户型和素材，或迁移到另一套安装时，可使用 HA Bridge 内的加密业务备份。业务恢复保留当前账号和授权，中控需要重新配对。

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

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

七、常见问题

添加仓库后找不到 HA Bridge

重新打开 Add-on 商店并检查更新；首次安装优先确认使用 Gitee 地址：

https://gitee.com/weidaye1122/ha-bridge-addon

如果 Home Assistant 主机无法访问 Gitee，可改用上方的 GitHub 备用地址。已经安装的用户先按已有安装的更新源说明处理。

已发布新版本，但 Home Assistant 没有显示更新

1. 确认发布的是 Add-on 版本，并核对自己已安装 Add-on 对应的仓库来源。
2. 在 Add-on 商店右上角菜单执行「检查更新」，再返回原有 HA Bridge Add-on 页面。
3. 如果刚刚发布，等待仓库同步完成后再检查。
4. 仍无更新时，查看 Home Assistant 的 Supervisor 日志，重点检查所用 Gitee 或 GitHub 仓库是否有连接超时、DNS 解析失败或 Git 拉取失败。

仓库负责提供版本信息，阿里云镜像仓库负责下载安装文件。看不到新版本时先排查仓库刷新；已经看到新版本，但安装失败时检查镜像下载错误。只刷新 HA Bridge 网页不会刷新 Home Assistant 的 Add-on 仓库。

安装时提示无法拉取镜像

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

启动后打不开网页

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

更新后原有数据不见了

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

忘记 HA Bridge 本地账号或密码

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