选择部署方式

HA Bridge 支持 Home Assistant Add-on 和独立 Docker 两种部署方式，请根据自己的系统选择对应教程。正式镜像同时支持 linux/amd64 和 linux/arm64，安装时会自动选择与当前设备匹配的版本。

部署前确认

• HAOS 或带 Supervisor 的冬瓜系统可以正常打开 Add-on 商店；其他设备已经安装并能够正常运行 Docker；
• 设备可以通过局域网访问 Home Assistant；
• 设备可以访问互联网，用于拉取镜像、首次激活和授权状态校验；
• 默认访问端口为 18080；如有冲突，将部署配置中的 APP_PORT 改为其他未占用端口，并使用新端口访问。

Home Assistant Add-on 仓库

首次安装优先使用 Gitee 国内仓库：

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

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

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

添加方法见HAOS（冬瓜）部署。已有安装继续在原 Add-on 页面更新；添加新仓库不会自动迁移安装和数据，详见已有安装的更新源说明。

Docker 镜像说明

以下镜像说明只适用于独立 Docker 部署。HAOS（冬瓜）Add-on 会自动使用专用适配镜像，不需要手动填写镜像地址。

Docker 部署教程中的 image 或 docker pull 命令有两个可选镜像。首次部署与日常更新优先使用阿里云镜像；只有阿里云镜像无法拉取时才改用 Docker Hub。

默认：阿里云个人镜像仓库

镜像名称：阿里云个人镜像仓库。首次部署与日常更新优先使用。

crpi-w1apw3w3zzp43y80.cn-shanghai.personal.cr.aliyuncs.com/weidaye1122/ha_bridge:latest

备用：Docker Hub

镜像名称：Docker Hub。仅在阿里云镜像无法拉取时使用。

weidaye1122/ha_bridge:latest

只需二选一，不要同时写入两条镜像地址。首次部署时直接保留教程里的默认阿里云地址即可；已经运行的旧容器不会自动切换镜像来源，修改 image 后需要按对应教程重新创建容器，但必须保留原来的 data 和 secrets 数据目录。

选择你的设备

设备或系统	推荐方式	教程
群晖 DSM	Host 网络 Compose 项目	群晖部署
威联通	Host 网络 Compose 应用	威联通部署
飞牛	Host 网络 Docker Compose 项目	飞牛部署
极空间	Host 网络 Docker Compose 应用	极空间部署
绿联云 UGOS Pro	Host 网络 Docker Compose 项目	绿联云部署
带 Home Assistant 商店的冬瓜系统	Home Assistant 商店安装	HAOS（冬瓜）部署
64 位树莓派、其他 Linux、NAS、小主机或没有 Add-on 商店的冬瓜系统	Host 网络通用 Docker 部署与更新	通用 Docker 部署与更新

部署后的步骤

1. 确认 HA Bridge Add-on 或 HaBridge 容器处于运行状态；
2. 使用教程中说明的地址打开 HA Bridge；
3. 完成首次设置与激活；
4. 连接 Home Assistant；
5. 创建空白仪表盘或使用「栖光」模板。

HAOS 用户直接在 Add-on 页面更新；独立 Docker 用户可参考使用 DockerCopilot 更新。更换设备前请先阅读备份与恢复和解绑与建议。