Skip to content

Commit 394f71e

Browse files
smthingsmthing
committed
docs(plugin): 添加插件运行流程图和序列图说明
- 为集群插件添加节点注册和消息转发的Mermaid序列图 - 为内存会话插件添加会话管理的流程图说明 - 为MQTTS插件添加TLS握手和加密通信的序列图 - 为Redis桥接插件添加消息桥接的流程图 - 为简单认证插件添加认证流程的序列图 - 为WebSocket插件添加协议升级和通信流程图 - 补充各个插件的流程说明文档
1 parent b397275 commit 394f71e

6 files changed

Lines changed: 414 additions & 2 deletions

File tree

‎pages/src/content/docs/plugins/cluster-plugin.mdx‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,109 @@ clusters: # 集群节点地址列表
4646
- 各节点 `plugin.yaml` 配置需根据实际角色（核心/工作）分别设置
4747
- 启动顺序建议先启动核心节点，再启动工作节点
4848

49+
## 运行流程图
50+
51+
### 集群节点注册泳道图
52+
53+
```mermaid
54+
sequenceDiagram
55+
autonumber
56+
participant WorkerN as 工作节点N
57+
participant Cluster as 集群插件
58+
participant Core as 核心节点<br/>(Coordinator)
59+
60+
rect rgb(230, 245, 255)
61+
Note over WorkerN,Core: 节点注册阶段
62+
WorkerN->>Cluster: 1. 节点启动
63+
Cluster->>Cluster: 2. 加载配置<br/>(clusters地址列表)
64+
65+
Cluster->>Core: 3. HTTP POST /register<br/>(节点信息+认证凭证)
66+
67+
Core->>Core: 4. 验证节点身份
68+
alt 验证通过
69+
Core->>Core: 5a. 注册到节点列表<br/>分配NodeID
70+
Core-->>Cluster: 6a. HTTP 200 OK<br/>(集群配置+节点列表)
71+
Cluster->>Cluster: 7a. 更新本地状态表
72+
Note over WorkerN,Core: 节点加入集群成功
73+
else 验证失败
74+
Core-->>Cluster: 6b. HTTP 403 Forbidden
75+
Cluster->>WorkerN: 7b. 注册失败，服务退出
76+
end
77+
end
78+
79+
rect rgb(255, 245, 230)
80+
Note over WorkerN,Core: 状态同步阶段
81+
Core->>Cluster: 8. 状态广播<br/>(节点加入事件)
82+
Cluster->>Cluster: 9. 更新集群拓扑
83+
84+
WorkerN->>Core: 10. 心跳检测
85+
Core-->>WorkerN: 11. 心跳响应
86+
end
87+
```
88+
89+
### 跨节点消息转发泳道图
90+
91+
```mermaid
92+
sequenceDiagram
93+
autonumber
94+
participant PubClient as 发布者(节点1)
95+
participant Worker1 as 工作节点1
96+
participant Cluster1 as 集群插件(节点1)
97+
participant Core as 核心节点
98+
participant Cluster2 as 集群插件(节点2)
99+
participant Worker2 as 工作节点2
100+
participant SubClient as 订阅者(节点2)
101+
102+
rect rgb(230, 245, 255)
103+
Note over PubClient,SubClient: 消息发布阶段
104+
PubClient->>Worker1: 1. PUBLISH消息<br/>(topic: sensors/temp)
105+
Worker1->>Cluster1: 2. 消息路由请求
106+
107+
Cluster1->>Cluster1: 3. 目标节点判断<br/>(根据topic路由表)
108+
end
109+
110+
rect rgb(255, 245, 230)
111+
Note over Core,Worker2: 跨节点转发
112+
113+
alt 目标在本地
114+
Cluster1->>Worker1: 4a. 本地转发
115+
Worker1->>PubClient: 4b. 确认接收
116+
else 目标在远程节点
117+
Cluster1->>Core: 4c. HTTP POST /forward<br/>(消息+目标节点)
118+
119+
Core->>Core: 5. 路由决策
120+
Core->>Cluster2: 6. HTTP转发消息
121+
122+
Cluster2->>Worker2: 7. 本地投递
123+
Worker2->>SubClient: 8. 推送消息
124+
125+
SubClient-->>Worker2: 9. 确认接收
126+
Worker2-->>Cluster2: 10. 转发确认
127+
Cluster2-->>Core: 11. 返回确认
128+
Core-->>Cluster1: 12. 转发完成
129+
end
130+
end
131+
132+
rect rgb(255, 255, 230)
133+
Note over PubClient,SubClient: 队列策略处理
134+
135+
alt 队列策略=丢弃最新(queuePolicy=0)
136+
Cluster1->>Cluster1: 队列满时丢弃新消息
137+
else 队列策略=丢弃最旧(queuePolicy=1)
138+
Cluster1->>Cluster1: 队列满时丢弃旧消息
139+
end
140+
end
141+
```
142+
143+
### 流程说明
144+
1. **核心节点启动**: 核心节点启动HTTP服务，等待工作节点连接
145+
2. **工作节点注册**: 工作节点根据配置的clusters地址连接到核心节点并完成注册
146+
3. **消息路由**:
147+
- 本地客户端直接转发
148+
- 远程客户端通过HTTP转发到对应节点
149+
4. **状态同步**: Coordinator维护集群节点状态，处理节点加入/退出事件
150+
5. **分布式分发**: Distributor根据队列策略管理消息分发
151+
49152
## 技术支持
50153
- 作者：三刀（zhengjunweimail@163.com）
51154
- 供应商：smart-mqtt

‎pages/src/content/docs/plugins/memory-session-plugin.mdx‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,69 @@ sidebar:
2323
- 单机部署环境
2424

2525
## 配置说明
26-
无需额外配置，引入插件后自动生效。
26+
无需额外配置，引入插件后自动生效。
27+
28+
## 运行流程图
29+
30+
### 会话管理泳道图
31+
32+
```mermaid
33+
sequenceDiagram
34+
autonumber
35+
participant Client as MQTT客户端
36+
participant Broker as MQTT Broker
37+
participant Plugin as 内存会话插件
38+
participant Store as ConcurrentHashMap<br/>(会话存储)
39+
40+
%% 连接阶段
41+
rect rgb(230, 245, 255)
42+
Note over Client,Store: 连接阶段 - 会话建立
43+
Client->>Broker: 1. CONNECT<br/>(cleanSession=0/1)
44+
Broker->>Plugin: 2. 创建/恢复会话请求
45+
46+
alt cleanSession=1 或 新会话
47+
Plugin->>Store: 3a. 创建新会话<br/>(SessionState)
48+
else cleanSession=0 且 会话存在
49+
Plugin->>Store: 3b. 查找已有会话
50+
Store-->>Plugin: 返回会话状态
51+
Plugin->>Plugin: 恢复会话状态<br/>(未确认消息/订阅)
52+
end
53+
54+
Plugin-->>Broker: 4. 会话就绪
55+
Broker-->>Client: 5. CONNACK<br/>(sessionPresent)
56+
end
57+
58+
%% 消息处理阶段
59+
rect rgb(255, 245, 230)
60+
Note over Client,Store: 消息处理阶段 - 状态更新
61+
Client->>Broker: 6. PUBLISH QoS>0
62+
Broker->>Plugin: 7. 更新会话状态
63+
Plugin->>Store: 8. 更新inflight队列<br/>存储消息ID
64+
Store-->>Plugin: 确认存储
65+
Plugin-->>Broker: 9. 状态更新完成
66+
67+
Broker-->>Client: 10. PUBACK/PUBREC
68+
end
69+
70+
%% 断开连接阶段
71+
rect rgb(255, 230, 230)
72+
Note over Client,Store: 断开阶段 - 资源管理
73+
Client->>Broker: 11. DISCONNECT 或 连接丢失
74+
Broker->>Plugin: 12. 处理断开事件
75+
76+
alt cleanSession=1
77+
Plugin->>Store: 13a. 从Map移除会话
78+
Store->>Store: 释放内存资源
79+
else cleanSession=0
80+
Plugin->>Store: 13b. 保留会话状态<br/>(等待重连)
81+
end
82+
83+
Plugin-->>Broker: 14. 断开处理完成
84+
end
85+
```
86+
87+
### 流程说明
88+
1. **会话存储**: 根据cleanSession标志决定创建新会话或恢复已有会话
89+
2. **内存管理**: 使用ConcurrentHashMap实现线程安全的会话数据存储
90+
3. **状态持久**: 对于QoS>0的消息，更新inflight队列并持久化会话状态
91+
4. **资源释放**: cleanSession=1时完全清理会话，否则保留以供重连恢复

‎pages/src/content/docs/plugins/mqtts-plugin.mdx‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,78 @@ pem: |
3131
...
3232
-----END PRIVATE KEY-----
3333
```
34+
35+
## 运行流程图
36+
37+
### TLS 握手与加密通信泳道图
38+
39+
```mermaid
40+
sequenceDiagram
41+
autonumber
42+
participant Client as MQTT客户端
43+
participant TLSPlugin as TLS/SSL插件<br/>(安全传输层)
44+
participant Broker as MQTT Broker
45+
participant Config as PEM证书配置
46+
47+
%% TLS握手阶段
48+
rect rgb(230, 245, 255)
49+
Note over Client,Broker: TLS 握手阶段
50+
Client->>TLSPlugin: 1. ClientHello<br/>(支持的加密套件)
51+
52+
TLSPlugin->>Config: 2. 加载PEM证书<br/>(证书+私钥)
53+
Config-->>TLSPlugin: 返回证书内容
54+
55+
TLSPlugin-->>Client: 3. ServerHello + Certificate<br/>(服务器证书)
56+
57+
Client->>Client: 4. 验证服务器证书<br/>(检查签名/有效期/域名)
58+
59+
alt 证书验证通过
60+
Client->>TLSPlugin: 5. ClientKeyExchange<br/>(预主密钥 - 公钥加密)
61+
Client->>TLSPlugin: 6. ChangeCipherSpec + Finished
62+
63+
TLSPlugin->>TLSPlugin: 7. 使用私钥解密<br/>生成会话密钥
64+
65+
TLSPlugin-->>Client: 8. ChangeCipherSpec + Finished
66+
Note over Client,TLSPlugin: 加密隧道建立完成<br/>(对称加密通信)
67+
else 证书验证失败
68+
Client->>Client: 终止连接
69+
end
70+
end
71+
72+
%% MQTT加密通信阶段
73+
rect rgb(255, 245, 230)
74+
Note over Client,Broker: 加密 MQTT 通信阶段
75+
76+
Client->>TLSPlugin: 9. 加密数据<br/>MQTT CONNECT
77+
TLSPlugin->>TLSPlugin: 10. TLS解密
78+
TLSPlugin->>Broker: 11. 明文 MQTT CONNECT
79+
80+
Broker->>Broker: 12. 处理认证
81+
Broker-->>TLSPlugin: 13. MQTT CONNACK
82+
83+
TLSPlugin->>TLSPlugin: 14. TLS加密
84+
TLSPlugin-->>Client: 15. 加密数据
85+
86+
Note over Client,Broker: 后续所有MQTT报文<br/>均在加密隧道中传输
87+
88+
Client->>TLSPlugin: 16. 加密 PUBLISH
89+
TLSPlugin->>Broker: 17. 解密后转发
90+
Broker->>TLSPlugin: 18. 加密响应
91+
TLSPlugin-->>Client: 19. 加密数据
92+
end
93+
94+
%% 连接关闭阶段
95+
rect rgb(255, 230, 230)
96+
Note over Client,Broker: 连接关闭阶段
97+
Client->>TLSPlugin: 20. 加密 Close Notify
98+
TLSPlugin->>Broker: 21. 通知连接关闭
99+
TLSPlugin->>TLSPlugin: 22. 释放TLS会话资源
100+
end
101+
```
102+
103+
### 流程说明
104+
1. **TLS握手**: 基于配置的PEM证书进行双向/单向TLS握手
105+
2. **证书验证**: 客户端验证服务器证书合法性
106+
3. **密钥协商**: 通过非对称加密协商会话密钥
107+
4. **加密隧道**: 握手完成后建立加密通道
108+
5. **MQTT通信**: 在加密隧道中传输MQTT协议数据

‎pages/src/content/docs/plugins/redis-bridge-plugin.mdx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,73 @@ redis:
4545
2. 避免重复配置相同的Redis地址
4646
3. 建议根据实际需求选择合适的消息编码格式
4747
4. 注意监控Redis存储容量，适时清理历史数据
48+
49+
## 运行流程图
50+
51+
### 消息桥接泳道图
52+
53+
```mermaid
54+
sequenceDiagram
55+
autonumber
56+
participant Client as MQTT发布者
57+
participant Broker as MQTT Broker
58+
participant Bridge as Redis桥接插件
59+
participant Subscribers as MQTT订阅者
60+
participant Redis as Redis实例集群
61+
62+
%% MQTT消息接收
63+
rect rgb(230, 245, 255)
64+
Note over Client,Subscribers: MQTT消息流转
65+
Client->>Broker: 1. PUBLISH 消息<br/>(topic: sensors/temp)
66+
Broker->>Broker: 2. Topic匹配检查
67+
68+
par 正常消息路由
69+
Broker->>Subscribers: 3a. 转发给订阅者
70+
and 触发桥接
71+
Broker->>Bridge: 3b. 触发Redis桥接<br/>(匹配topic规则)
72+
end
73+
end
74+
75+
%% 消息处理与编码
76+
rect rgb(255, 245, 230)
77+
Note over Bridge,Redis: 桥接消息处理
78+
Bridge->>Bridge: 4. 提取消息内容<br/>(topic + payload + timestamp)
79+
80+
Bridge->>Bridge: 5. 格式转换
81+
alt encode=STRING
82+
Bridge->>Bridge: 字符串编码
83+
else encode=JSON
84+
Bridge->>Bridge: JSON序列化
85+
else encode=HEX
86+
Bridge->>Bridge: 十六进制编码
87+
end
88+
89+
Bridge->>Bridge: 6. 生成SortedSet Key<br/>(格式: mqtt:topic)
90+
Bridge->>Bridge: 7. 获取时间戳<br/>(作为SortedSet score)
91+
end
92+
93+
%% Redis写入
94+
rect rgb(255, 255, 230)
95+
Note over Bridge,Redis: 并行写入Redis集群
96+
97+
par 并发写入多实例
98+
Bridge->>Redis: 8a. ZADD mqtt:sensors/temp<br/>score=timestamp value=message
99+
and
100+
Bridge->>Redis: 8b. ZADD mqtt:sensors/temp<br/>score=timestamp value=message
101+
and
102+
Bridge->>Redis: 8c. ZADD mqtt:sensors/temp<br/>score=timestamp value=message
103+
end
104+
105+
Redis-->>Bridge: 9. 存储确认响应
106+
end
107+
108+
Bridge->>Broker: 10. 桥接处理完成
109+
Note over Client,Redis: 消息同时完成<br/>MQTT路由 + Redis持久化
110+
```
111+
112+
### 流程说明
113+
1. **消息捕获**: 拦截匹配指定Topic规则的MQTT消息
114+
2. **格式转换**: 根据配置的encode参数对消息进行编码
115+
3. **时间戳标记**: 使用当前时间作为SortedSet的分数(score)
116+
4. **多实例写入**: 异步并行写入所有配置的Redis实例
117+
5. **有序存储**: 利用Redis SortedSet特性实现按时间排序的消息存储

‎pages/src/content/docs/plugins/simple-auth-plugin.mdx‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,40 @@ accounts:
3131
## 注意事项
3232

3333
- 密码以明文形式存储，请妥善保管配置文件
34-
- 建议在生产环境中使用更安全的认证方式
34+
- 建议在生产环境中使用更安全的认证方式
35+
36+
## 运行流程图
37+
38+
### 认证泳道图
39+
40+
```mermaid
41+
sequenceDiagram
42+
autonumber
43+
participant Client as MQTT客户端
44+
participant Broker as MQTT Broker
45+
participant Plugin as 简单认证插件
46+
participant Config as plugin.yaml配置
47+
48+
Client->>Broker: 1. CONNECT报文<br/>(username + password)
49+
Broker->>Plugin: 2. 转发认证请求<br/>(extract credentials)
50+
Plugin->>Config: 3. 查询账户列表
51+
Config-->>Plugin: 4. 返回匹配账户
52+
53+
alt 账户存在且密码匹配
54+
Plugin-->>Broker: 5. 返回认证成功
55+
Broker-->>Client: 6. CONNACK(返回码0)<br/>连接成功
56+
Note over Client,Broker: 后续MQTT通信
57+
else 账户不存在或密码错误
58+
Plugin-->>Broker: 5. 返回认证失败
59+
Broker-->>Client: 6. CONNACK(返回码4)<br/>认证失败
60+
Broker->>Client: 7. 断开TCP连接
61+
end
62+
```
63+
64+
### 流程说明
65+
1. **CONNECT报文**: 客户端向Broker发送连接请求，携带用户名和密码
66+
2. **账户查找**: 插件从`plugin.yaml`配置中查找匹配的账户
67+
3. **身份验证**: 对比请求中的用户名密码与配置的账户信息
68+
4. **结果处理**:
69+
- 验证通过：返回连接成功，允许客户端后续通信
70+
- 验证失败：拒绝连接并断开客户端

0 commit comments

Comments
 (0)