# mica-mqtt-admin

**Repository Path**: asurplus_admin/mica-mqtt-admin

## Basic Information

- **Project Name**: mica-mqtt-admin
- **Description**: 基于 Spring Boot + Thymeleaf 的 MQTT 服务端可视化管理后台，通过 HTTP API 对接 mica-mqtt-server，提供仪表盘、客户端管理、消息发布、主题订阅等功能的 Web 界面。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mica-mqtt-admin

基于 Spring Boot + Thymeleaf 的 MQTT 服务端可视化管理后台，通过 HTTP API 对接 [mica-mqtt-server](https://gitee.com/596392912/mica-mqtt)，提供仪表盘、客户端管理、消息发布、主题订阅等功能的 Web 界面。

## 功能特性
- **仪表盘** — 实时显示服务器统计信息，在线客户端数量，总消息数和订阅数，最近连接的客户端列表
- **客户端管理** — 分页浏览所有 MQTT 客户端连接，查看详情（ClientID / 用户名 / 状态 / IP / 端口 / 协议 / 连接时间），踢出客户端
- **消息发布** — 单条发布或批量发布，支持 Topic、Payload、编码方式、QoS、保留消息等配置
- **主题订阅** — 单条 / 批量订阅与取消订阅，客户端详情页内直接管理订阅关系
- **自动刷新** — 客户端列表和详情页支持 3 / 5 / 10 / 30 秒自动刷新，设置持久化到 localStorage
- **可选认证** — 支持密码登录认证，可配置固定密码或自动生成随机密码

## 界面预览

| 登录 |             仪表盘              | 客户端列表 |
|:---:|:----------------------------:|:---:|
| ![登录](images/login.png) | ![仪表盘](images/dashboard.png) | ![客户端列表](images/clients.png) |

| 客户端详情 | 消息发布 | 主题订阅 |
|:---:|:---:|:---:|
| ![客户端详情](images/client-detail.png) | ![消息发布](images/publish.png) | ![主题订阅](images/subscribe.png) |

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Java 8 |
| 框架 | Spring Boot 2.7.14 |
| 模板引擎 | Thymeleaf |
| 前端 UI | Bootstrap 5（本地静态资源） |
| 构建工具 | Maven |
| 后端服务 | mica-mqtt-server（通过 HTTP API + Basic Auth 对接） |

## 项目结构

```
src/main/java/com/biz/admin/
├── MicaMqttAdminApplication.java          # 启动类
├── config/
│   ├── AppPasswordHolder.java           # 密码管理（配置或自动生成）
│   ├── AuthInterceptor.java             # 认证拦截器
│   ├── GlobalModelConfig.java           # 全局 Model 属性
│   ├── RestTemplateConfig.java          # RestTemplate + Basic Auth
│   └── WebMvcConfig.java                # 拦截器注册
├── controller/
│   ├── LoginController.java             # 登录 / 退出
│   └── MqttController.java             # 客户端、发布、订阅管理
├── model/
│   ├── ApiResult.java                   # 通用响应包装
│   ├── ClientInfo.java                  # 客户端详情
│   ├── ClientPage.java                  # 客户端分页
│   ├── ClientSubscription.java          # 订阅关系
│   ├── Endpoint.java                    # API 端点
│   ├── PublishRequest.java              # 发布请求
│   ├── SubscribeRequest.java            # 订阅请求
│   └── UnsubscribeRequest.java          # 取消订阅请求
└── service/
    └── MqttApiService.java              # MQTT HTTP API 服务层

src/main/resources/
├── application.yml                      # 应用配置
├── static/                              # 静态资源（Bootstrap / Logo / Favicon）
└── templates/
    ├── fragments/common.html            # 公共片段（CSS / JS / 导航栏 / Toast）
    ├── login.html                       # 登录页
    ├── clients.html                     # 客户端列表
    ├── client-detail.html               # 客户端详情
    ├── publish.html                     # 消息发布
    └── subscribe.html                   # 主题订阅
```

## 快速开始

### 前置条件

- JDK 8+
- Maven 3.6+
- 运行中的 [mica-mqtt-server](https://gitee.com/596392912/mica-mqtt)（默认 HTTP API 端口 `18083`）

### 配置说明

编辑 `src/main/resources/application.yml`，或通过环境变量覆盖：

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| `server.port` | — | `28083` | 本服务端口 |
| `auth.enabled` | `AUTH_ENABLED` | `false` | 是否启用登录认证 |
| `auth.password` | `AUTH_PASSWORD` | 空（自动生成） | 登录密码，为空时启动日志中打印随机密码 |
| `mqtt.http.api-url` | `HTTP_API_URL` | `http://127.0.0.1:18083` | mica-mqtt-server HTTP API 地址 |
| `mqtt.http.username` | `HTTP_USERNAME` | `mica` | HTTP Basic Auth 用户名 |
| `mqtt.http.password` | `HTTP_PASSWORD` | `mica` | HTTP Basic Auth 密码 |

### 启动方式

**Maven 直接运行：**

```bash
mvn spring-boot:run
```

**打包运行：**

```bash
mvn clean package -DskipTests
java -jar target/mica-mqtt-admin-1.0.0.jar
```

**带环境变量启动：**

```bash
java -jar target/mica-mqtt-admin-1.0.0.jar \
  --AUTH_ENABLED=true \
  --AUTH_PASSWORD=mysecret \
  --HTTP_API_URL=http://192.168.1.100:18083
```

**IDE 运行：** 直接运行 `com.biz.admin.MicaMqttAdminApplication.main()`

启动后访问 [http://localhost:28083](http://localhost:28083)

## 架构说明

```
浏览器 ──▶ Spring Boot (Thymeleaf) ──▶ RestTemplate (Basic Auth) ──▶ mica-mqtt-server HTTP API
  │                                         │
  ├── 服务端页面渲染                          ├── 纯 HTTP 代理转发
  └── 客户端 AJAX 交互                       └── 无本地数据存储
```

本系统不直接处理 MQTT 协议，所有 MQTT 操作通过 mica-mqtt-server 暴露的 HTTP API 完成，本系统仅作为可视化管理代理层。

## API 端点一览

| 端点 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 重定向到客户端列表 |
| `/clients` | GET | 客户端列表（分页） |
| `/client/detail` | GET | 客户端详情 |
| `/client/delete` | POST | 踢出客户端 |
| `/publish` | GET / POST | 消息发布页面 / 单条发布 |
| `/publish/batch` | POST | 批量消息发布 |
| `/subscribe` | GET / POST | 主题订阅页面 / 单条订阅 |
| `/subscribe/batch` | POST | 批量订阅 |
| `/unsubscribe` | POST | 取消订阅 |
| `/unsubscribe/batch` | POST | 批量取消订阅 |
| `/login` | GET | 登录页面 |
| `/login/do` | POST | 执行登录 |
| `/logout` | GET | 退出登录 |