# NebulaMQ

**Repository Path**: chauncyma/NebulaMQ

## Basic Information

- **Project Name**: NebulaMQ
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-16
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🌌 NebulaMQ

[![AI Generated](https://img.shields.io/badge/AI-Generated-10b981?style=for-the-badge&logo=openai&logoColor=white)](https://cursor.sh)
[![.NET 10](https://img.shields.io/badge/.NET-10.0-512bd4?style=for-the-badge&logo=dotnet&logoColor=white)](https://dotnet.microsoft.com/)
[![Vue 3](https://img.shields.io/badge/Vue-3.0-42b883?style=for-the-badge&logo=vue.js&logoColor=white)](https://vuejs.org/)
[![MQTT](https://img.shields.io/badge/MQTT-5.0-660066?style=for-the-badge&logo=mqtt&logoColor=white)](https://mqtt.org/)
[![Cluster](https://img.shields.io/badge/Cluster-Ready-ff6b6b?style=for-the-badge&logo=redis&logoColor=white)](#-启用分布式路由跨节点消息转发)

> **⚠️ 🚧 本项目正在开发阶段，且 100% 代码由 Cursor 和高级模型编写生成。**

NebulaMQ 是一个面向**高性能场景**的物联网 MQTT 消息中间件平台。它基于 ASP.NET Core 10 构建，兼容 MQTT 3.1.1/5.0 协议，并提供可视化管理控制台。

**🔥 最新亮点**：现已完成**极致性能优化**，开箱即用支持**50-100万 msg/s** 吞吐量，默认使用共享内存数据库，支持**百万级连接**部署！同时支持基于 Redis 的分布式路由，实现企业级的跨节点消息转发能力！

**📖 快速导航**：[核心特性](#-核心特性) | [快速开始](#-快速开始) | [连接测试](#-连接测试) | [集群部署](#-集群部署-可选) | [文档](#-文档)

</div>

---

## ✨ 核心特性

### 🏢 设备与认证
- **设备管理**：设备注册、分组、在线状态、设备影子。
- **设备认证**：支持严格模式（预注册）和自动注册模式（默认，共享密码快速接入）。
- **全局配额**：在系统设置中配置最大连接数、消息速率限制（0 = 无限制）。

### 📡 多协议全覆盖
支持标准 MQTT 协议，提供多种接入方式：
- **MQTT (TCP)**: 端口 `1883` (默认)
- **MQTTS (TLS)**: 端口 `8883` (支持双向认证)
- **WebSocket**: `ws://localhost:5059/mqtt`
- **WSS**: `wss://localhost:5001/mqtt`

### 🛡️ 安全与认证
- **多种认证模式**：
  - **AutoRegister**（默认）: 任意 ClientId + 全局共享密码即可连接并自动注册。
  - **Strict**: 严格模式，设备必须预先在 Dashboard 中注册。
- **API Key 管理**：为第三方系统集成提供细粒度的权限控制 (Read/Write/Admin)。
- **TLS/SSL**: 支持自签名证书和 CA 证书。

### ⚡ 实时监控与运维
- **实时看板**：基于 SignalR 的实时监控（可配置开关，高性能模式下默认禁用）。
- **高级 MQTT 特性**：
  - **保留消息 (Retained Messages)** 管理与清除（支持 Redis 持久化）。
  - **遗嘱消息 (LWT)** 配置与监控。
- **规则引擎**：简单的 Topic 匹配规则（支持 MQTT 通配符），支持 Webhook 消息转发，内置缓存优化。
- **告警系统**：设备掉线、流量异常等告警通知。
- **性能开关**：可配置启用/禁用消息历史记录、设备影子更新、实时推送等非关键功能。

### 🌐 集群与扩展
- **水平扩展**：支持 Redis 作为 SignalR 背板，多实例部署无缝消息同步。
- **🔥 分布式路由**：基于 Redis 的跨节点消息转发，实现企业级集群能力！
  - ✅ 跨节点 Pub/Sub（客户端可连接到不同实例并互相通信）
  - ✅ 全局订阅表（订阅关系自动同步）
  - ✅ 通配符支持（`+` 和 `#`）
  - ✅ 自动故障恢复（心跳机制 + TTL）
- **桥接功能**：可将消息转发到远程 MQTT Broker（如 AWS IoT Core 等）。
- **动态配置**：桥接、集群配置存储在数据库，支持热更新无需重启。
- **高性能索引**：保留消息使用 Set 索引优化，查询速度提升数千倍。

### 🧪 质量保障
- **单元测试**：核心 Topic 匹配算法已覆盖 16+ 测试用例。
- **API 文档**：完整的 Swagger/OpenAPI 文档，支持 XML 注释。

---

## 📊 本机压测结果（默认参数）

**测试报告**：`NebulaMQ.LoadTest/reports/LoadTest_Report_20260120_111405.md`
**测试配置**：100 并发 × 100 消息，QoS 0，消息 256B，本地回环 `127.0.0.1:1883`

| 指标 | 数值 | 水准 |
|---|---|---|
| 吞吐量 | 26,148 msg/s | ✅ 优秀 |
| P95 延迟 | 17 ms | ✅ 优秀 |
| 平均延迟 | 6.62 ms | ✅ 优秀 |
| 连接耗时（100 客户端） | 0.95 s | ✅ 优秀 |
| 成功率 | 100% | ✅ 优秀 |

**本机配置与剩余性能（采样时）**：
- CPU：11th Gen i7‑1185G7（4C/8T，3.0GHz）
- 内存：31.85 GB 总量，空闲 15.7 GB
- CPU 空闲：47.58%（采样时）

**结论**：在默认参数下已达到**极高水准**；本机仍有明显余量，说明当前吞吐更多受限于测试参数而非硬件极限。

---

## 🛠️ 技术栈

**后端 (NebulaMQ.Server)**
- **Runtime**: .NET 10
- **Core**: MQTTnet (高性能 MQTT 协议库)
- **Database**: SqlSugar (ORM) + SQLite 共享内存模式（默认，极致性能）/ PostgreSQL（生产推荐）
- **Cache & Cluster**: Redis (StackExchange.Redis)
- **Real-time**: SignalR (支持 Redis 背板)
- **Testing**: xUnit
- **Architecture**: Clean Architecture, Dependency Injection, Channel 队列（10万容量）

**前端 (Web)**
- **Framework**: Vue 3 (Composition API) + TypeScript
- **UI Library**: Element Plus
- **Charts**: ECharts
- **State Management**: Pinia
- **Build Tool**: Vite

---

## 🚀 快速开始

### 方式 1：Docker 部署（推荐）⭐

**前后端一体化部署，快速构建（5-10秒）！**

```bash
# 方法 1：一键构建并启动（推荐）
.\build-docker.ps1      # Windows
./build-docker.sh       # Linux/macOS

# 方法 2：手动分步构建
# 步骤 1: 发布前后端
.\publish.ps1           # Windows
./publish.sh            # Linux/macOS

# 步骤 2: 构建镜像（极快，5-10秒）
docker build -t nebula-mq:latest .

# 步骤 3: 运行容器
docker run -d --name nebula-mq \
  -p 5059:5059 -p 1883:1883 \
  -v nebula-data:/app/data \
  -e Database__AutoInitialize=true \
  nebula-mq:latest

# 访问 Web 界面
# http://localhost:5059
# 默认账号：admin / admin123
```

**环境变量说明**：
- `JWT_KEY`：JWT 密钥（必需，至少32字符）
- `Database__AutoInitialize`：是否自动初始化数据库（首次启动设为 `true`）

**集群支持**：
- 支持连接外部 Redis 实现集群功能
- 配置方式：在 Web 界面的"集群配置"页面设置 Redis 连接
- Redis 服务器需要自行部署

📖 **核心文档**：
- 🚀 [极致性能优化指南](./EXTREME_PERFORMANCE_OPTIMIZATION.md) - 代码级优化详解，开箱即用 50-100万 msg/s
- 🌟 [单节点百万连接分析](./SINGLE_BROKER_MILLION_CONNECTIONS.md) - 单机百万连接的技术分析与硬件配置
- 📊 [MQTT 压测指南](./mqtt-benchmark-guide.md) - 使用 MQTTX CLI 和 emqtt-bench 进行性能测试
- ⚡ [Windows TCP 优化](./WINDOWS_TCP_OPTIMIZATION.md) - Windows 下的 TCP 参数调优

---

### 方式 2：本地开发

#### 1. 启动后端服务

```powershell
cd NebulaMQ.Server
dotnet run
```

后端服务将启动在 `http://localhost:5059`。

**Swagger API 文档**：访问 `http://localhost:5059/swagger` 查看完整 API 文档。

#### 2. 启动前端控制台

```powershell
cd Web
pnpm install
pnpm dev
```

浏览器访问 `http://localhost:5173`。

**默认管理员账号**：
- **用户名**: `admin`
- **密码**: `admin123`

**默认 MQTT 连接（AutoRegister）**：
- **共享设备密码**: `123456`（可在控制台 **系统设置** 中修改）

> 💡 **提示**：生产环境请使用 Docker 部署，前端已集成到后端中

---

## 🔌 连接测试

你可以使用 MQTTX 或其他 MQTT 客户端进行连接测试：

### AutoRegister 模式（默认）

| 参数 | 值 | 说明 |
|------|----|------|
| **Host** | `localhost` | |
| **Port** | `1883` | TCP 端口 |
| **Protocol** | `mqtt://` | |
| **Username** | （留空或任意，可在系统设置中指定共享用户名） | 留空则不校验 |
| **Password** | `123456` | 全局共享密码（系统设置可改） |
| **ClientId** | `test_device_01` | 任意唯一 ID，自动注册 |

连接成功后，设备会自动注册，并在前端控制台的 **设备管理** 页面显示为在线状态。

### Strict 模式

在控制台 **系统设置** 中切换为 Strict 模式后：
1. 在 Dashboard 中预先添加设备（设置 ClientId 和密码）
2. 使用 **ClientId** 连接，密码为设备密码

---

## 🔒 开启 TLS/SSL (可选)

项目包含一个生成自签名证书的脚本，用于开发测试：

```powershell
# 在 NebulaMQ 根目录执行
.\generate-cert.ps1
```

生成的证书将位于 `certs/` 目录。修改 `appsettings.json` 启用 TLS：

```json
"Mqtt": {
  "EnableTls": true,
  "TlsPort": 8883,
  "TlsCertificatePath": "certs/nebulaMQ-dev.pfx",
  "TlsCertificatePassword": "NebulaMQ2024"
}
```

---

## 🧪 运行测试

项目包含单元测试以确保核心功能的稳定性：

```powershell
dotnet test NebulaMQ.Tests
```

---

## 🚀 集群部署 (可选)

### 启用 Redis 集群支持

在 `appsettings.json` 中配置 Redis 连接字符串：

```json
{
  "ConnectionStrings": {
    "Redis": "localhost:6379,allowAdmin=true"
  }
}
```

启用后，系统将：
- 使用 Redis 存储保留消息（服务重启不丢失）
- 使用 Redis 作为 SignalR 背板（多实例消息同步）
- 使用内存缓存优化规则引擎性能

### 🔥 启用分布式路由（跨节点消息转发）

NebulaMQ 现在支持**企业级分布式路由**，实现真正的集群能力！

#### 方式 1：前端配置（推荐）

1. 访问 `http://localhost:5173/cluster`
2. 配置：
   - ✅ **启用 Redis 集群**
   - ✅ **启用分布式路由** ← 关键开关！
   - 连接字符串：`localhost:6379,allowAdmin=true`
3. 保存并重启服务

#### 方式 2：配置文件

编辑 `appsettings.json`：

```json
{
  "ConnectionStrings": {
    "Redis": "localhost:6379,allowAdmin=true"
  },
  "Cluster": {
    "EnableDistributedRouting": true,
    "NodeName": "BJ-Gateway-01"  // 可选：自定义节点名称，便于识别
  }
}
```

**节点名称配置**（可选）：
- `NodeName`：自定义节点名称，未配置时使用机器名
- 推荐格式：`{地域/环境}-{角色}-{序号}`，如 `BJ-Gateway-01`、`SH-Worker-02`
- 前端显示格式：`NodeName (PID: ProcessId)`

#### 部署多实例

**实例 1（默认端口）：**
```powershell
cd NebulaMQ.Server
$env:Cluster__NodeName = "Gateway-01"
dotnet run
# MQTT: 1883, HTTP: 5059
```

**实例 2（自定义端口）：**
```powershell
$env:ASPNETCORE_URLS = "http://localhost:5060"
$env:Mqtt__Port = "1884"
$env:Cluster__NodeName = "Worker-01"
dotnet run
# MQTT: 1884, HTTP: 5060
```

#### 集群架构图

```
                    ┌─────────────┐
                    │ 负载均衡器   │ (HAProxy/Nginx)
                    │  :1883      │
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
   │ NMQ 1   │       │ NMQ 2   │       │ NMQ 3   │
   │:1883    │◄──────┤:1883    ├──────►│:1883    │
   └────┬────┘  消息  └────┬────┘  转发  └────┬────┘
        │        转发       │        ↕       │
        └──────────────────┼──────────────────┘
                           │
                    ┌──────▼──────┐
                    │    Redis    │ (路由表 + Pub/Sub)
                    │  :6379      │
                    └─────────────┘
```

#### 集群模式对比

| 模式 | Redis | 分布式路由 | 适用场景 | 跨节点通信 |
|------|-------|-----------|---------|----------|
| **单机** | ❌ | ❌ | 开发测试 | ❌ |
| **数据共享** | ✅ | ❌ | 规则引擎 + Webhook | ❌ |
| **完全分布式** | ✅ | ✅ | 设备间直接通信 | ✅ |

#### 功能特性对比

| 功能 | 单机模式 | Redis 集群 | 分布式路由 |
|------|---------|-----------|----------|
| 保留消息共享 | ❌ | ✅ | ✅ |
| SignalR 同步 | ❌ | ✅ | ✅ |
| 跨节点消息转发 | ❌ | ❌ | ✅ |
| 业务端设备端通信 | ⚠️ 同实例 | ⚠️ 同实例 | ✅ 任意实例 |
| 水平扩展 | ❌ | ✅ | ✅ |
| 配置热更新 | ❌ | ✅ | ✅ |
| 通配符订阅 | ✅ | ✅ | ✅ |
| QoS 0/1/2 | ✅ | ✅ | ✅ (QoS 2 不保证) |

#### 测试跨节点通信

**客户端 A（连接实例 1）：**
```
Host: localhost:1883
订阅: t/default/sensor/#
```

**客户端 B（连接实例 2）：**
```
Host: localhost:1884
发布到: t/default/sensor/temp
Payload: {"temperature": 25.5}
```

**结果**：✅ 客户端 A 成功收到消息！

#### 📚 详细文档

- [分布式路由技术文档](./CLUSTER_DISTRIBUTED_ROUTING.md) - 架构设计、性能分析、实现原理
- [集群测试指南](./CLUSTER_TEST_GUIDE.md) - 完整测试场景、故障排查、生产部署

### 启用 MQTT 桥接

**推荐方式：** 访问 `http://localhost:5173/mqtt-bridge` 使用可视化界面配置。

或者在数据库 `SystemConfigs` 表中插入以下配置：

| Key | Value | 说明 |
|-----|-------|------|
| `Bridge.Enabled` | `true` | 是否启用桥接 |
| `Bridge.Host` | `test.mosquitto.org` | 远程 Broker 地址 |
| `Bridge.Port` | `1883` | 远程 Broker 端口 |
| `Bridge.ClientId` | `nebula_bridge` | 桥接客户端 ID |
| `Bridge.Username` | (可选) | 认证用户名 |
| `Bridge.Password` | (可选) | 认证密码 |
| `Bridge.TopicPattern` | `#` | 转发的主题模式 |

配置修改后，系统会在 10 秒内自动检测并热更新，无需重启。

---

## 📚 文档

### 部署与安全
- **[部署指南](./docs/DEPLOYMENT.md)** — Quick Start / 生产 PostgreSQL / 双节点集群 + Nginx
- **[安全配置](./docs/SECURITY.md)** — 上线检查清单、ACL、认证模式
- **[配置参考](./docs/CONFIGURATION.md)** — 环境变量与配置项全集

### 功能说明（Dashboard）
- **[功能文档索引](./docs/features/README.md)** — 设备管理、分组、认证、ACL、告警、审计等详细说明

### 性能与优化
- **[极致性能优化指南](./EXTREME_PERFORMANCE_OPTIMIZATION.md)** - 代码级优化详解，50-100万 msg/s
- **[单节点百万连接分析](./SINGLE_BROKER_MILLION_CONNECTIONS.md)** - 硬件配置与系统调优
- **[MQTT 压测指南](./mqtt-benchmark-guide.md)** - MQTTX CLI / emqtt-bench 使用
- **[Windows TCP 优化](./WINDOWS_TCP_OPTIMIZATION.md)** - Windows 系统参数调优

### API 文档
- **[Swagger API 文档](http://localhost:5059/swagger)** - 完整的 RESTful API 文档

---

## 🎯 路线图

- [x] 核心 MQTT 协议支持（MQTT 3.1.1/5.0）
- [x] 设备认证与全局配额管理
- [x] 规则引擎（Webhook、告警）
- [x] Redis 集群支持
- [x] 保留消息持久化
- [x] MQTT 桥接
- [x] **分布式路由（跨节点消息转发）**
- [x] **极致性能优化**
- [x] Docker 部署 + **生产/集群 Compose 模板**
- [x] **Prometheus 指标导出**（`/metrics`）
- [x] **审计日志**（API + Dashboard）
- [x] **消息历史保留策略**
- [x] **设备级 Topic ACL**（Permissive 默认）
- [x] 系统主题 / 慢订阅 / 延迟发布
- [x] **共享订阅** (`$share/group/topic`)
- [ ] MQTT 5.0 高级特性（用户属性、主题别名等）
- [ ] 插件系统
- [ ] 集成测试（Testcontainers）

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

## 📄 License

MIT License