dersimn/mqtt-smarthome-webui

!https://raw.githubusercontent.com/dersimn/mqtt-smarthome-webui/master/docs/title.png

镜像概述

dersimn/mqtt-smarthome-webui 是一个用于构建智能家居Web界面的Docker镜像，通过WebSocket与MQTT broker通信，支持自定义页面结构配置，提供安全访问控制及日志功能，适用于智能家居系统的设备监控与控制场景。

支持的标签

• 标签基于SemVer规范，例如：2、2.1、2.1.6 指向同一镜像（至少在某一时间点）。
• 简单版本标签会在基础镜像更新时同步更新，因此例如 2.1.6 在Docker Hub上基础镜像更新后会有不同的SHA值。
• 若需固定使用同一镜像且不接收更新，可使用时间戳标签，例如：2.1.6-build20230915T0815。

核心功能与特性

• 自定义页面结构：通过data.yaml配置文件定义Web界面布局
• MQTT WebSocket代理：支持通过环境变量WS_PROXY代理MQTT broker的WebSocket连接
• SSL/HTTPS支持：可通过提供SSL证书启用HTTPS加密访问
• 客户端认证：支持基于SSL证书的客户端身份验证
• 访问控制：内置本地IP白名单，可自定义IP范围
• 详细日志：支持启用详细访问日志，兼容logfmt格式

使用场景

• 智能家居系统的Web监控面板
• MQTT设备状态可视化与控制界面
• 本地或远程访问的智能家居控制中心

配置与使用方法

基础配置

需提供data.yaml文件定义页面结构，参考https://github.com/dersimn/mqtt-smarthome-webui/blob/master/www/data.yaml%E3%80%82

通过环境变量WS_PROXY设置MQTT broker的WebSocket代理，需先在broker上启用WebSocket（参考https://hub.docker.com/_/eclipse-mosquitto%E7%9A%84https://github.com/dersimn/mqtt-smarthome-webui/tree/master/contrib%EF%BC%89%E3%80%82

基础启动命令：

bash
docker run -d --restart=always \
    -v $(pwd)/yourconfig.yaml:/www/data.yaml:ro \
    --add-host=host.docker.internal:host-gateway \
    -e "WS_PROXY=host.docker.internal:9001" \
    -p 80:80 \
    dersimn/mqtt-smarthome-webui

SSL / HTTPS 配置

通过挂载/ssl目录提供SSL证书对可启用HTTPS：

• /ssl/nginx.key：SSL私钥
• /ssl/nginx.crt：SSL证书

如需启用客户端证书认证，需额外提供：

• /ssl/client.crt：客户端CA证书

若需吊销客户端，可提供：

• /ssl/client.crl：证书吊销列表

生成自签名证书可参考教程。

启用HTTPS的启动命令：

bash
docker run -d --restart=always \
    -v $(pwd)/yourconfig.yaml:/www/data.yaml:ro \
    -v $(pwd)/ssl:/ssl:ro \
    --add-host=host.docker.internal:host-gateway \
    -e "WS_PROXY=host.docker.internal:9001" \
    -p 80:80 \
    -p 443:443 \
    dersimn/mqtt-smarthome-webui

如需修改默认端口：

bash
-p 8001:80 -p 8443:443 -e "HTTPS_REDIRECT_PORT=8443"

IP白名单设置

本地IP（以下范围）默认可不强制SSL和客户端认证：

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16

环境变量配置：

• WHITELIST_LOCAL_IP=false：强制所有客户端使用SSL和客户端认证
• WHITELIST_IP="10.1.1.0/24 192.168.1.0/24"：添加自定义IP白名单范围

详细访问日志

提供/nginx.log文件可启用logfmt格式的详细访问日志，支持常规文件或FIFO（可配合Telegraf等工具处理日志数据）。

源码地址

https://github.com/dersimn/mqtt-smarthome-webui