HA Bridge

Appearance

使用 DockerCopilot 更新 ​

DockerCopilot（以下简称 DC）会检查 HA Bridge 当前使用的完整镜像；有新版本时，拉取镜像并按原配置重建容器，同时保留数据目录、密钥目录、网络、端口、环境变量和重启策略。完成后按 DC 提示清理旧容器，并检查容器状态、日志、仪表盘和 Home Assistant 连接。

说明：DC 是独立的容器更新工具，不属于 HA Bridge 项目。本页只介绍使用 DC 更新 HA Bridge。

DC 不会自动更换镜像来源，也不会删除 data、secrets 数据。旧 Docker Hub 容器如需切换到阿里云镜像，请先按部署教程重建一次；之后 DC 会继续跟踪当前镜像地址。

更新前确认版本和数据 ​

日常正式版使用 latest；固定版本标签会停留在指定版本，beta 则用于测试。DC 按当前完整镜像地址检查，不会自动把 beta 改成 latest。Home Assistant Add-on 应在 Add-on 页面更新，而不是用 DC 替换镜像。

本轮 v0.4.5 之后的待发布更新包含独立账号文件。首次升级到支持版本时原账号密码不变，系统会自动生成 data/admin-account.json；日常更新请将它与整个 data、secrets 一起保留。只有忘记凭据并主动重置本地账号时才删除该文件。

更新前创建完整备份。更新后先检查运行版本、原项目和 HA 连接，再测试新功能；页面仍是旧样式或模型一直加载时，参考问题排查。

1. 安装 DockerCopilot ​

使用前修改密码

请把配置中的 secretKey 替换为自己的登录密码。密码需要不少于 8 位且不能是纯数字。如果宿主机的 12712 已被占用，将 ports 或 -p 左侧改为其他未占用端口，例如 12713:12712，访问时使用对应的新端口。

群晖 Container Manager ​

在群晖中创建 docker/DockerCopilot 文件夹，在其中新建 compose.yaml：

yaml
name: docker-copilot

services:
  dockercopilot:
    container_name: dockercopilot
    restart: always
    privileged: true
    network_mode: bridge
    ports:
      - "12712:12712"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /volume1/docker/DockerCopilot:/data
    environment:
      - TZ=Asia/Shanghai
      - DOCKER_HOST=unix:///var/run/docker.sock
      - secretKey=请替换为不少于八位且非纯数字的密码
    image: 0nlylty/dockercopilot:latest

在 Container Manager 的「项目」中选择该文件夹并启动，启动后访问 http://群晖 IP:12712。

威联通 ​

在威联通的 Container 共享文件夹中创建 DockerCopilot 文件夹，并在其中新建 compose.yaml：

yaml
name: docker-copilot

services:
  dockercopilot:
    container_name: dockercopilot
    restart: always
    privileged: true
    network_mode: bridge
    ports:
      - "12712:12712"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /share/Container/DockerCopilot:/data
    environment:
      - TZ=Asia/Shanghai
      - DOCKER_HOST=unix:///var/run/docker.sock
      - secretKey=请替换为不少于八位且非纯数字的密码
    image: 0nlylty/dockercopilot:latest

在 Container Station 的「应用程序」或「Compose」中创建并启动应用，启动后访问 http://威联通 IP:12712。

飞牛 ​

在飞牛中创建 /vol1/1000/docker/DockerCopilot 文件夹，在其中新建 compose.yaml：

yaml
name: docker-copilot

services:
  dockercopilot:
    container_name: dockercopilot
    restart: always
    privileged: true
    network_mode: bridge
    ports:
      - "12712:12712"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /vol1/1000/docker/DockerCopilot:/data
    environment:
      - TZ=Asia/Shanghai
      - DOCKER_HOST=unix:///var/run/docker.sock
      - secretKey=请替换为不少于八位且非纯数字的密码
    image: 0nlylty/dockercopilot:latest

在飞牛的 Docker / Compose 页面创建并启动项目，启动后访问 http://飞牛 IP:12712。

极空间 ​

在极空间的 Docker 应用文件夹中创建 DockerCopilot 文件夹，并在其中新建 compose.yaml：

yaml
name: docker-copilot

services:
  dockercopilot:
    container_name: dockercopilot
    restart: always
    privileged: true
    network_mode: bridge
    ports:
      - "12712:12712"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      - DOCKER_HOST=unix:///var/run/docker.sock
      - secretKey=请替换为不少于八位且非纯数字的密码
    image: 0nlylty/dockercopilot:latest

在极空间 Docker / Compose 中选择该文件夹并启动，启动后访问 http://极空间 IP:12712。

绿联云 UGOS Pro ​

在绿联云 Docker 数据目录中创建 DockerCopilot 文件夹，并在其中新建 compose.yaml：

yaml
name: docker-copilot

services:
  dockercopilot:
    container_name: dockercopilot
    restart: always
    privileged: true
    network_mode: bridge
    ports:
      - "12712:12712"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      - DOCKER_HOST=unix:///var/run/docker.sock
      - secretKey=请替换为不少于八位且非纯数字的密码
    image: 0nlylty/dockercopilot:latest

在绿联云 Docker 的「项目」或「Compose」页面选择该文件夹并启动，启动后访问 http://绿联云 IP:12712。

通用 Docker 部署与更新 ​

适用于已安装 Docker 的 Linux 主机、NAS 或小主机。先创建 DockerCopilot 数据目录：

bash
mkdir -p /opt/DockerCopilot/data

执行以下命令启动 DockerCopilot：

bash
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。如果宿主机的 12712 已被占用，将 -p 左侧改为其他未占用端口，例如 -p 12713:12712，然后通过 设备 IP:12713 访问。

2. 执行更新 ​

首次登录 DC 时，使用 Compose 中设置的 secretKey。然后按以下顺序操作：

  1. 在容器列表中找到 HaBridge；
  2. 执行「检查更新」「更新镜像」或名称相近的功能；
  3. 确认默认镜像 crpi-w1apw3w3zzp43y80.cn-shanghai.personal.cr.aliyuncs.com/weidaye1122/ha_bridge:latest 有更新后，执行「更新容器」或「重新创建」；
  4. 等待镜像拉取、新容器启动以及 DC 界面提示的清理步骤完成；
  5. 检查 HaBridge 状态、日志、仪表盘和 Home Assistant 连接。

没有更新提示时手动拉取 ​

即使容器列表显示「已是最新」，也可以手动拉取一次最新镜像：

  1. 在容器列表勾选或选中 HaBridge，打开容器管理；
  2. 确认当前镜像为 crpi-w1apw3w3zzp43y80.cn-shanghai.personal.cr.aliyuncs.com/weidaye1122/ha_bridge:latest；如果你此前已改用备用 Docker Hub 镜像，则继续使用 weidaye1122/ha_bridge:latest；
  3. 在「目标版本」保持 latest，点击右侧「更新」按钮；
  4. 等待 DC 完成拉取和重新创建，再检查容器状态与日志。

在 DC 容器列表中选中 HaBridge

在容器管理中点击 latest 旁的更新按钮

如果远端镜像没有新的版本，强制拉取后内容可能不会发生变化；这不代表操作失败。

更新前请确认 HA Bridge 原有的 data、secrets 挂载目录、网络模式、端口配置和重启策略保持不变。DC 会按原配置重新创建 HA Bridge 容器，更新前必须确认持久化目录已经正确挂载并完成备份。容器清理不应替代 data 和 secrets 的备份。

示例没有默认填写 HTTP_PROXY 和 HTTPS_PROXY。只有 NAS 上确实运行了可用代理时，才应将这两个变量添加到 environment，并改为实际代理地址和端口。

DockerCopilot 需要访问 Docker Socket，权限较高。不要把 DC 管理端口直接暴露到公网，只在可信局域网内使用，并保留 DC 自身的数据目录。

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

HA Bridge