203 lines
7.1 KiB
Markdown
203 lines
7.1 KiB
Markdown
# ZHub 工程项目文档
|
||
|
||
## 1. 概述
|
||
ZHub 是一个基于 Go 的高性能分布式消息中间件，支持发布/订阅模式、定时任务、延时消息、分布式锁等功能。它适用于需要高并发、低延迟的消息传递场景。
|
||
|
||
---
|
||
|
||
## 2. 技术栈
|
||
- **语言**: Go (Golang)
|
||
- **网络库**: `net`, `bufio`
|
||
- **并发模型**: 使用 goroutines 和 channels 实现并发处理。
|
||
- **持久化**: 使用文件存储（如延时任务和锁信息）。
|
||
- **配置管理**: 使用 Viper 读取 INI 格式的配置文件。
|
||
- **权限控制**: 基于 YAML 的用户、组、Token 和频道权限管理。
|
||
- **监控界面**: 使用 Gin 提供 HTTP 接口用于监控和服务管理。
|
||
- **数据库支持**: 支持 MySQL 和 PostgreSQL 用于定时任务的配置。
|
||
|
||
---
|
||
|
||
## 3. 核心功能模块
|
||
|
||
### 3.1 消息总线 (`zbus`)
|
||
- **主题管理**: 支持多主题订阅与发布。
|
||
- **组订阅**: 每个主题可以有多个消费组，组内客户端共享消息。
|
||
- **延时消息**: 支持延时发送消息，使用 `time.Timer` 实现。
|
||
- **定时任务**: 支持 cron 表达式或固定时间间隔的任务调度。
|
||
- **分布式锁**: 提供互斥锁机制，支持重入和自动释放。
|
||
- **持久化**: 使用文件保存延时任务和锁的状态，确保服务重启后数据不丢失。
|
||
|
||
### 3.2 权限管理 ([auth](file://D:\wk-go\zhub\cmd\client.go#L37-L37))
|
||
- **用户认证**: 支持基于 Token 的认证。
|
||
- **角色授权**: 用户分属不同组，组内定义读写权限。
|
||
- **频道访问控制**: 频道可设置为公开或私有，私有频道需授权访问。
|
||
- **配置热加载**: 支持运行时重新加载权限配置。
|
||
|
||
### 3.3 客户端 (`client`)
|
||
- **连接管理**: 支持自动重连机制。
|
||
- **订阅与发布**: 提供 API 订阅主题并接收消息。
|
||
- **RPC 调用**: 支持远程过程调用，并处理超时和返回结果。
|
||
- **锁机制**: 支持获取和释放分布式锁。
|
||
|
||
### 3.4 监控 (`monitor`)
|
||
- **HTTP 接口**: 提供 `/_/info`, `/_/cleanup`, `/timer/reload` 等接口。
|
||
- **可视化界面**: 提供简单的 HTML 页面展示系统状态。
|
||
- **版本信息**: 显示当前运行的 ZHub 版本。
|
||
|
||
---
|
||
|
||
## 4. 架构设计
|
||
|
||
### 4.1 总体架构
|
||
ZHub 采用经典的 C/S 架构，包含以下主要组件：
|
||
- **服务端 ([main.go](file://D:\wk-go\zhub\main.go))**
|
||
- 启动 TCP 服务器监听客户端连接。
|
||
- 加载配置文件并初始化日志。
|
||
- 启动监控服务（Gin）。
|
||
- **客户端 ([client.go](file://D:\wk-go\zhub\cmd\client.go))**
|
||
- 提供连接、订阅、发布、RPC 调用等 API。
|
||
- 自动重连机制保证连接稳定性。
|
||
- **消息总线 (`zbus`)**
|
||
- 处理消息的发布、订阅、延时、定时等核心逻辑。
|
||
- **权限管理 ([auth](file://D:\wk-go\zhub\cmd\client.go#L37-L37))**
|
||
- 管理用户、组、Token 和频道权限。
|
||
- **监控 (`monitor`)**
|
||
- 提供 HTTP 接口和 Web 界面用于管理和监控。
|
||
|
||
### 4.2 数据流图
|
||
```plaintext
|
||
+-------------------+ +------------------+ +------------------+
|
||
| Client (Go) |<--->| ZHub Server |<--->| Monitor (Gin) |
|
||
+-------------------+ +------------------+ +------------------+
|
||
|
|
||
v
|
||
+------------------+
|
||
| Persistence |
|
||
| (File, DB) |
|
||
+------------------+
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## 5. 配置说明
|
||
|
||
### 5.1 配置文件 ([app.ini](file://D:\wk-go\zhub\app.ini))
|
||
- **[service]**: 服务相关配置。
|
||
- `watch`: 监控服务地址。
|
||
- [addr](file://D:\wk-go\zhub\cmd\client.go#L25-L25): 主服务监听地址。
|
||
- [auth](file://D:\wk-go\zhub\cmd\client.go#L37-L37): 是否启用认证（0 不启用，1 启用）。
|
||
- **[data]**: 数据目录配置。
|
||
- **[log]**: 日志配置。
|
||
- `handlers`: 输出方式（console/file）。
|
||
- `level`: 日志级别（info/debug/error）。
|
||
- [file](file://D:\wk-go\zhub\Dockerfile): 日志文件路径。
|
||
- **[ztimer]**: 定时任务数据库配置。
|
||
- `db.addr`, `db.user`, `db.password`, `db.database`, `db.schema`, `db.type`.
|
||
|
||
### 5.2 权限配置 ([auth.yml](file://D:\wk-go\zhub\auth.yml))
|
||
- **users**: 用户列表，包含 ID、用户名、密码、状态、所属组、读写权限。
|
||
- **groups**: 用户组列表，包含名称、描述、读写权限。
|
||
- **tokens**: Token 列表，包含 ID、用户 ID、Token 值、过期时间和状态。
|
||
- **channels**: 频道列表，包含名称、描述、是否为公开频道。
|
||
|
||
---
|
||
|
||
## 6. 部署与构建
|
||
|
||
### 6.1 构建脚本 ([build.bat](file://D:\wk-go\zhub\build.bat))
|
||
- 支持跨平台编译（Linux、Windows、Mac）。
|
||
- 使用 UPX 压缩生成的二进制文件。
|
||
- 自动生成版本号并嵌入到程序中。
|
||
|
||
### 6.2 启动命令
|
||
- **服务端启动**:
|
||
```bash
|
||
go run main.go
|
||
```
|
||
|
||
- **客户端启动**:
|
||
```bash
|
||
go run cmd/client.go -cli -r <command>
|
||
```
|
||
|
||
|
||
### 6.3 监控服务
|
||
- 默认监听地址：`http://<host>:<port>/`
|
||
- 支持的接口：
|
||
- `/_/info`: 获取系统信息。
|
||
- `/_/cleanup`: 清理无订阅的主题。
|
||
- `/timer/reload`: 重新加载定时任务。
|
||
- `/topic/publish`: 发布主题消息。
|
||
- `/topic/delay`: 发送延时消息。
|
||
- `/auth/reload`: 重新加载权限配置。
|
||
|
||
---
|
||
|
||
## 7. 安全性设计
|
||
|
||
### 7.1 认证机制
|
||
- 所有客户端必须通过 Token 认证才能进行操作。
|
||
- Token 具有过期时间和状态管理。
|
||
|
||
### 7.2 授权机制
|
||
- 用户分属不同组，组内定义读写权限。
|
||
- 频道可设置为公开或私有，私有频道需授权访问。
|
||
- 支持正则表达式匹配主题名，实现细粒度的权限控制。
|
||
|
||
### 7.3 分布式锁
|
||
- 使用互斥锁机制防止多个客户端同时执行关键操作。
|
||
- 锁具有超时机制，避免死锁。
|
||
|
||
---
|
||
|
||
## 8. 性能优化
|
||
|
||
### 8.1 并发处理
|
||
- 使用 goroutines 和 channels 实现高效的并发处理。
|
||
- 所有 I/O 操作异步化，减少阻塞。
|
||
|
||
### 8.2 内存管理
|
||
- 使用缓冲区池化技术减少内存分配。
|
||
- 对频繁使用的结构体进行复用。
|
||
|
||
### 8.3 日志优化
|
||
- 支持日志级别控制，减少不必要的日志输出。
|
||
- 日志输出格式化，便于调试和分析。
|
||
|
||
---
|
||
|
||
## 9. 测试与验证
|
||
|
||
### 9.1 单元测试
|
||
- 覆盖所有核心模块的功能测试。
|
||
- 使用 Go 的 testing 包编写测试用例。
|
||
|
||
### 9.2 集成测试
|
||
- 模拟多个客户端并发操作，验证系统的稳定性和一致性。
|
||
- 测试定时任务、延时消息、锁机制等复杂场景。
|
||
|
||
### 9.3 压力测试
|
||
- 使用基准测试工具评估系统的吞吐量和响应时间。
|
||
- 优化瓶颈部分，提升整体性能。
|
||
|
||
---
|
||
|
||
## 10. 未来规划
|
||
|
||
### 10.1 功能增强
|
||
- 支持更多类型的数据库（如 MongoDB、Redis）。
|
||
- 增加消息持久化支持（如 Kafka、RabbitMQ）。
|
||
- 提供更丰富的监控指标和告警机制。
|
||
|
||
### 10.2 性能优化
|
||
- 引入零拷贝技术减少内存复制。
|
||
- 进一步优化 goroutine 调度策略。
|
||
|
||
### 10.3 安全加固
|
||
- 增加 TLS 加密通信支持。
|
||
- 支持更复杂的权限策略（如 RBAC、ABAC）。
|
||
|
||
### 10.4 用户体验
|
||
- 开发图形化管理界面，简化配置和监控操作。
|
||
- 提供 SDK 支持多种编程语言（如 Python、Java）。 |