跳到主要内容
版本：4.2

MQTT 管理服务套件

一、说明​

TSMQ 是基于 TouchSocket 构建的一套完整的 MQTT 服务器管理套件，为需要在私有环境中自建、自管 MQTT Broker 的团队提供开箱即用的全栈解决方案。

它将 MQTT 服务器的创建、启停、认证、监控等能力封装成一套体系，并通过多种访问方式（Web、桌面客户端、API）暴露出来，方便运维人员和开发者进行日常管理。

下载 TSMQ

前往 下载中心 获取最新发行版。

二、整体架构​

TSMQ 由三个主要部分组成，相互配合运行：

模块说明
TSMQServer核心服务端，内置 MQTT Broker、用户/角色管理、RPC 授权、日志系统，基于 .NET 10+ 构建
TSMQClient桌面管理客户端，提供 WPF / Avalonia / WinForms 三种 UI，用于可视化管理服务端
TSMQWebWeb 管理前端，基于 Vue 3 + Vite，通过浏览器进行全功能管理

三、核心功能​

3.1 MQTT 服务器管理​

TSMQ 支持在运行时动态创建和管理多个 MQTT 服务器实例，每个实例可以独立配置：

配置项说明
服务器类型Tcp（标准 MQTT over TCP）或 WebSocket（MQTT over WebSocket）
监听地址可绑定到指定 IP，默认 0.0.0.0
监听端口自定义端口
WebSocket 路径仅 WebSocket 类型有效，默认 /mqtt
SSL 证书可关联已上传的 SSL 证书，启用 TLS 加密通信

支持的管理操作：

  • 添加 / 移除 MQTT 服务器实例
  • 启动 / 停止单个实例
  • 查看所有实例及运行状态

3.2 MQTT 连接认证​

TSMQ 维护一套独立的 MQTT 连接授权用户表，MQTT 客户端在连接时需要提供用户名/密码通过认证后才能接入。

支持：

  • 添加 / 更新 / 删除授权用户
  • 为用户设置备注信息
  • 独立于系统管理账号，专用于 MQTT 客户端认证

3.3 已连接客户端管理​

实时查看当前所有已连接到 MQTT Broker 的客户端列表，支持强制踢除指定客户端。

3.4 主题管理与统计​

实时查看当前活跃的 MQTT 主题订阅关系，并提供消息统计能力：

  • 查看所有已订阅的主题列表
  • 获取指定主题的消息收发统计数据
  • 重置主题统计计数器

3.5 用户与角色管理​

TSMQ 内置了一套完整的 RBAC（基于角色的访问控制） 体系，用于管理对 TSMQ 管理接口本身的访问权限：

  • 用户管理：注册/删除管理账号、修改密码、为用户分配角色
  • 角色管理：创建/更新/删除角色、管理角色成员
  • RPC 授权：动态配置每个 RPC 接口方法允许访问的角色，无需重启服务即可生效

3.6 日志管理​

服务端通过 NLog 记录运行日志，并持久化到 SQLite 数据库。在管理界面中可以按条件（时间、级别等）查询历史日志。

四、访问方式​

TSMQServer 同时支持三种 RPC 调用协议，管理客户端可按需选择：

协议适用场景
WebApi（HTTP）Web 前端、浏览器直接调用、Swagger 调试
DmtpRpc桌面客户端，基于 TouchSocket Dmtp 长连接，低延迟
JsonRpc通用 JSON-RPC 场景

服务端默认监听 7789 端口，Swagger 文档地址：http://localhost:7789/swagger（仅 Debug 模式可用）。

【Swagger 页面截图占位】

五、快速开始​

5.1 前置要求​

使用发布包（推荐）无需安装 .NET 运行时，开箱即用。若需要从源码构建，则需要：

5.2 启动服务端​

从 下载中心 获取对应平台的发布包，按平台选择启动方式：

  1. 解压 tsmq-server-win-x64-x.x.x.zip
  2. 直接运行：双击 TSMQServer.App.exe 即可启动，关闭窗口即停止服务

或安装为 Windows 服务（后台常驻，开机自启）：

:: 以管理员身份运行命令提示符，路径替换为实际解压位置
sc create TSMQServer binPath="C:\TSMQServer\TSMQServer.App.exe" start=auto
sc start TSMQServer

停止 / 卸载服务：

sc stop TSMQServer
sc delete TSMQServer

启动成功后终端输出类似：

info: TouchSocket.Sockets.HttpDmtpService[0]
      The server is listening on port: 7789

首次启动会自动创建 SQLite 数据库并初始化默认管理员账号：
账号：admin　密码：admin123

5.3 启动桌面客户端​

cd TSMQClient
dotnet run --project UI/TSMQClient.Wpf

5.4 启动 Web 前端​

cd TSMQWeb
npm install      # 首次运行需要安装依赖
npm run dev

浏览器访问http://localhost:3000，使用默认管理员账号登录。

【Web 管理界面截图占位 - 登录页】

【Web 管理界面截图占位 - 主界面/仪表盘】

六、项目结构说明​

6.1 TSMQServer 结构​

TSMQServer/
├── TSMQServer.App/          # 启动入口，依赖注入组装，HTTP/Dmtp 服务配置
├── TSMQServer.Core/         # 核心业务接口层
│   ├── Models/              # 公共请求/响应基类（RequestBase、LoginedRequest、ResponseBase 等）
│   └── Services/
│       ├── MqttServerManager/   # MQTT 服务器实例管理接口及 DTO
│       ├── MqttClientManager/   # 已连接 MQTT 客户端管理接口
│       ├── MqttTopicManager/    # MQTT 主题管理与统计接口
│       ├── UserManager/         # 用户管理接口
│       ├── RoleManager/         # 角色管理接口
│       ├── RpcAuthorization/    # RPC 动态角色授权接口
│       └── LogManager/          # 日志查询接口
├── TSMQServer.Core.Imp/     # 核心业务实现层
├── TSMQServer.Db/           # 数据库抽象层
├── TSMQServer.Db.Sqlite/    # SQLite 数据库实现
└── TSMQServer.Web/          # WebApi 扩展注册

6.2 TSMQClient 结构​

TSMQClient/
├── Core/                    # 业务逻辑与远程服务调用
├── Modules/                 # 功能模块（Remote 代理等）
└── UI/
    ├── TSMQClient.Wpf/      # WPF 桌面端 UI
    ├── TSMQClient.Avalonia/ # Avalonia 跨平台 UI
    └── TSMQClient.Winform/  # WinForms UI

七、扩展开发​

TSMQ 设计上充分考虑了扩展性，在不改动框架代码的情况下，可以按照以下步骤新增自定义业务接口：

  1. 定义 DTO：在 TSMQServer.Core/Models/ 下新建请求/响应模型
  2. 注册 JSON 序列化：在 TSMQServerCoreJsonSerializerContext 中注册新类型
  3. 定义 RPC 接口：在 TSMQServer.Core/Services/ 下新建接口，标注 [WebApi]、[DmtpRpc]、[JsonRpc] 特性
  4. 实现服务：在 TSMQServer.Core.Imp/ 下实现接口
  5. 扩展客户端：在 TSMQClient 中扩展 IRemoteService 接口并添加调用实现
  6. 扩展前端：在 TSMQWeb 中添加对应的 API 调用和页面

详细步骤请参考项目附带的《如何新增一个接口》文档。

八、常见问题​

Q：端口 7789 已被占用怎么办？

打开 TSMQServer/TSMQServer.App/appsettings.json，修改 Server.Port 字段为其他端口号。

Q：桌面客户端连不上服务端？

检查服务端是否在运行，以及客户端是否配置了正确的服务器地址（默认 127.0.0.1:7789）。

Q：Web 前端登录报错？

确认服务端已启动，并检查浏览器控制台（F12）中的错误信息。Web 前端通过 Vite 代理将 /api 请求转发到 7789 端口。

Q：如何发布到生产环境？

# 发布服务端
cd TSMQServer
dotnet publish TSMQServer.App -c Release -o ../publish/server

# 构建 Web 前端静态文件
cd TSMQWeb
npm run build

九、相关源码链接​

TSMQ

GitHub
编辑此页
最后由 若汝棋茗 于 更新