通用 Docker 部署与更新

本方式适用于已安装 Docker 的 Linux 主机、NAS、小主机、64 位树莓派，以及没有 Supervisor/Add-on 商店的冬瓜系统。HA Bridge 同时提供 linux/amd64 和 linux/arm64 镜像，Docker 会自动拉取与当前设备匹配的版本。

树莓派与冬瓜系统

• 树莓派需要使用 64 位 Raspberry Pi OS 或其他 64 位 Linux 系统；镜像会自动拉取 ARM64 版本，无需手动指定平台。
• 如果冬瓜系统可以打开 Home Assistant 商店，请优先使用HAOS（冬瓜）部署。只有没有商店、仅提供普通 Docker 环境时才使用本教程。
• 如果 18080 被占用，将 APP_PORT 改为其他未占用端口。

部署前准备

• 已安装并可正常使用 Docker。
• 设备所在局域网可访问 Home Assistant。
• 设备可以访问互联网，用于拉取镜像、首次激活和授权状态校验。
• 端口 18080 未被其他服务占用。

启动服务

先在 /opt 下创建持久化目录：

mkdir -p /opt/ha-bridge/data
mkdir -p /opt/ha-bridge/secrets

再执行以下命令：

docker run -d \
  --name ha-bridge \
  --restart unless-stopped \
  --network host \
  -e APP_PORT=18080 \
  -v /opt/ha-bridge/data:/data \
  -v /opt/ha-bridge/secrets:/run/secrets \
  crpi-w1apw3w3zzp43y80.cn-shanghai.personal.cr.aliyuncs.com/weidaye1122/ha_bridge:latest

网络模式与端口

本教程使用 Docker 的 host 网络，HA Bridge 直接监听设备的局域网端口，不需要 -p 映射。-e APP_PORT=18080 表示通过 设备 IP:18080 访问。

如果 18080 已被占用，将命令中的 APP_PORT=18080 改为其他未占用端口，例如 APP_PORT=18081，然后通过 设备 IP:18081 访问。Host 网络适用于 Linux 与 NAS 的 Docker 环境。

启动后，在浏览器打开：

http://设备 IP:18080

首次使用请继续完成首次设置与激活。

常用命令

# 查看运行状态
docker ps

# 查看实时日志
docker logs -f ha-bridge

# 停止服务
docker stop ha-bridge

# 再次启动服务
docker start ha-bridge

升级到最新版本

使用同一组 /opt/ha-bridge 目录重建容器即可保留原有仪表盘、图片和运行配置：

docker pull crpi-w1apw3w3zzp43y80.cn-shanghai.personal.cr.aliyuncs.com/weidaye1122/ha_bridge:latest
docker stop ha-bridge
docker rm ha-bridge

然后重新执行上方「启动服务」中的 docker run 命令。

不要删除 /opt/ha-bridge/data 与 /opt/ha-bridge/secrets 目录，否则原有运行数据将无法保留。

更新前先完整备份。支持独立账号文件的新版会自动迁移旧账号，原账号密码不变；正常更新应保留 data/admin-account.json。忘记凭据时查看重置本地账号与密码，更新后显示异常时查看问题排查。

使用 DockerCopilot 更新

如果不想每次手动执行拉取、停止、删除和重建命令，可以安装独立的 DockerCopilot（简称 DC）来更新 HA Bridge。DC 会按当前容器的镜像地址和原有配置重新创建容器；使用前请确认 data、secrets 挂载目录保持不变。

先创建 DockerCopilot 的持久化目录：

mkdir -p /opt/DockerCopilot/data

然后执行以下命令安装并启动 DC：

docker run -d \
  --name dockercopilot \
  --restart always \
  --privileged \
  --network bridge \
  -p 12712:12712 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/DockerCopilot/data:/data \
  -e TZ=Asia/Shanghai \
  -e DOCKER_HOST=unix:///var/run/docker.sock \
  -e 'secretKey=请替换为不少于八位且非纯数字的密码' \
  0nlylty/dockercopilot:latest

安装完成后，在浏览器打开 http://设备 IP:12712，使用上面设置的密码登录。首次使用时，在容器列表中找到 ha-bridge，执行「检查更新」并按 DC 提示更新或重新创建容器。更新完成后检查 HA Bridge 状态、日志、仪表盘和 Home Assistant 连接。

如果 12712 已被占用，将 -p 左侧改为其他未占用端口，例如 12713:12712，访问时使用对应的新端口。DC 需要访问 Docker Socket，建议只在可信局域网内使用，不要将管理端口直接暴露到公网。完整的安装和更新说明请参阅使用 DockerCopilot 更新。

Docker Hub 备用镜像

默认使用阿里云个人镜像仓库。如果所在网络无法拉取它，可将上方命令中的镜像地址替换为备用 Docker Hub 镜像：

weidaye1122/ha_bridge:latest