lsiodev/habridge

linuxserver/habridge

镜像概述

Habridge 是一款家庭自动化网关，通过模拟Philips Hue API，使Amazon Echo/Dot（第1代）等支持Philips Hue协议的设备能够控制其他智能家居系统。该网关支持"开"、"关"、"亮度调节"等基本命令，并可集成多种智能家居设备和平台，如Logitech Harmony Hub、Vera、Nest、Home Assistant、Domoticz、MQTT等，实现跨系统设备的统一管理。

核心功能与特性

• 协议模拟：模拟Philips Hue API，使非Hue设备兼容Hue协议控制系统
• 多平台集成：支持Logitech Harmony Hub、Vera、Nest、Somfy Tahoma、Home Assistant、Domoticz、MQTT等多种系统
• 设备控制：处理"开"、"关"、"亮度调节"等基本命令
• 安全通信：支持通过加密密钥（SEC_KEY）保护通信安全
• 代理功能：可将真实Hue桥接器代理到该网关下统一管理

支持的架构

该镜像利用Docker manifest实现多平台支持，拉取lscr.io/linuxserver/habridge:latest即可自动获取适合当前架构的镜像，也可通过标签指定特定架构：

应用设置

1. 启动容器后，通过 http://localhost:8080 访问Web管理界面
2. 在Web界面中添加设备并配置集成参数
3. 详细配置指南请参考官方Wiki：https://github.com/bwssytems/ha-bridge/wiki

使用方法

Docker Compose（推荐）

yaml
---
version: "2.1"
services:
  habridge:
    image: lscr.io/linuxserver/habridge:latest
    container_name: habridge
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - "SEC_KEY=<Your Key To Encrypt Security Data>"
    volumes:
      - <path to data>:/config
    ports:
      - 8080:8080
      - 50000:50000
    restart: unless-stopped

Docker CLI

bash
docker run -d \
  --name=habridge \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e SEC_KEY="<Your Key To Encrypt Security Data>" \
  -p 8080:8080 \
  -p 50000:50000 \
  -v <path to data>:/config \
  --restart unless-stopped \
  lscr.io/linuxserver/habridge:latest

参数说明

容器运行时通过参数进行配置，格式为<外部>:<内部>：

环境变量文件（Docker Secrets）

可通过FILE__前缀从文件中读取环境变量，例如：

bash
-e FILE__PASSWORD=/run/secrets/mysecretpassword

上述命令会将/run/secrets/mysecretpassword文件内容作为PASSWORD环境变量的值。

应用运行的Umask设置

可通过-e UMASK=022覆盖容器内服务的默认umask设置。注意umask是权限掩码，用于限制新文件的权限，而非直接设置权限，详情参考umask说明。

用户/组ID

使用卷挂载（-v参数）时，主机与容器可能出现权限问题。通过指定PUID（用户ID）和PGID（组ID）可避免此问题。确保主机上的卷目录归属于指定的用户/组。

查看当前用户的ID：

bash
id username

输出示例：

uid=1000(dockeruser) gid=1000(dockergroup) groups=1000(dockergroup)

Docker模块

LinuxServer提供多种https://github.com/linuxserver/docker-mods%E4%BB%A5%E6%89%A9%E5%B1%95%E5%AE%B9%E5%99%A8%E5%8A%9F%E8%83%BD%EF%BC%8C%E4%B8%8A%E8%BF%B0%E5%BE%BD%E7%AB%A0%E9%93%BE%E6%8E%A5%E5%8F%AF%E6%9F%A5%E7%9C%8B%E9%80%82%E7%94%A8%E4%BA%8E%E6%AD%A4%E9%95%9C%E5%83%8F%E7%9A%84%E6%A8%A1%E5%9D%97%E5%8F%8A%E9%80%9A%E7%94%A8%E6%A8%A1%E5%9D%97%E3%80%82

支持信息

• 容器运行时进入Shell：docker exec -it habridge /bin/bash
• 实时查看容器日志：docker logs -f habridge
• 查看容器版本号：docker inspect -f '{{ index .Config.Labels "build_version" }}' habridge
• 查看镜像版本号：docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/habridge:latest

更新信息

大部分LinuxServer镜像为静态版本，需通过更新镜像并重建容器来更新应用。不建议在容器内直接更新应用。

通过Docker Compose更新

• 更新所有镜像：docker-compose pull
• 更新单个镜像：docker-compose pull habridge
• 重建并启动容器：docker-compose up -d
• 清理旧镜像：docker image prune

通过Docker Run更新

• 更新镜像：docker pull lscr.io/linuxserver/habridge:latest
• 停止容器：docker stop habridge
• 删除容器：docker rm habridge
• 使用原参数重建容器（配置文件位于/config目录将被保留）
• 清理旧镜像：docker image prune

通过Watchtower自动更新（仅推荐用于忘记原始参数时）

bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once habridge

注意：不推荐使用Watchtower作为自动化更新工具，长期建议使用Docker Compose。

镜像更新通知 - Diun

推荐使用Diun接收镜像更新通知，不建议使用自动更新容器的工具。

本地构建

如需修改镜像进行开发或自定义：

bash
git clone https://github.com/linuxserver/docker-habridge.git
cd docker-habridge
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/habridge:latest .

在x86_64硬件上构建ARM变体需使用multiarch/qemu-user-static：

bash
docker run --rm --privileged multiarch/qemu-user-static:register --reset

然后使用对应架构的Dockerfile，如：-f Dockerfile.aarch64

版本历史

• 07.07.23：弃用armhf架构（公告：[***]
• 11.12.22：基于Alpine 3.17重建
• 23.01.21：基于Alpine 3.13重建
• 01.06.20：基于Alpine 3.12重建
• 19.12.19：基于Alpine 3.11重建
• 28.06.19：基于Alpine 3.10重建
• 23.03.19：切换到新基础镜像，迁移至arm32v7标签
• 22.02.19：基于Alpine 3.9重建
• 11.02.19：添加流水线逻辑和多架构支持
• 28.08.18：基于Alpine 3.8重建
• 12.04.18：添加绑定80端口的解决方法
• 08.04.18：初始发布