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)
- 用户认证: 支持基于 Token 的认证。
- 角色授权: 用户分属不同组，组内定义读写权限。
- 频道访问控制: 频道可设置为公开或私有，私有频道需授权访问。
- 配置热加载: 支持运行时重新加载权限配置。
3.3 客户端 (client)
- 连接管理: 支持自动重连机制。
- 订阅与发布: 提供 API 订阅主题并接收消息。
- RPC 调用: 支持远程过程调用，并处理超时和返回结果。
- 锁机制: 支持获取和释放分布式锁。
3.4 监控 (monitor)
- HTTP 接口: 提供
/_/info,/_/cleanup,/timer/reload等接口。 - 可视化界面: 提供简单的 HTML 页面展示系统状态。
- 版本信息: 显示当前运行的 ZHub 版本。
4. 架构设计
4.1 总体架构
ZHub 采用经典的 C/S 架构，包含以下主要组件：
- 服务端 (main.go)
- 启动 TCP 服务器监听客户端连接。
- 加载配置文件并初始化日志。
- 启动监控服务（Gin）。
- 客户端 (client.go)
- 提供连接、订阅、发布、RPC 调用等 API。
- 自动重连机制保证连接稳定性。
- 消息总线 (
zbus)- 处理消息的发布、订阅、延时、定时等核心逻辑。
- 权限管理 (auth)
- 管理用户、组、Token 和频道权限。
- 监控 (
monitor)- 提供 HTTP 接口和 Web 界面用于管理和监控。
4.2 数据流图
+-------------------+ +------------------+ +------------------+
| Client (Go) |<--->| ZHub Server |<--->| Monitor (Gin) |
+-------------------+ +------------------+ +------------------+
|
v
+------------------+
| Persistence |
| (File, DB) |
+------------------+
5. 配置说明
5.1 配置文件 (app.ini)
- [service]: 服务相关配置。
watch: 监控服务地址。- addr: 主服务监听地址。
- auth: 是否启用认证（0 不启用，1 启用）。
- [data]: 数据目录配置。
- [log]: 日志配置。
handlers: 输出方式（console/file）。level: 日志级别（info/debug/error）。- file: 日志文件路径。
- [ztimer]: 定时任务数据库配置。
db.addr,db.user,db.password,db.database,db.schema,db.type.
5.2 权限配置 (auth.yml)
- users: 用户列表，包含 ID、用户名、密码、状态、所属组、读写权限。
- groups: 用户组列表，包含名称、描述、读写权限。
- tokens: Token 列表，包含 ID、用户 ID、Token 值、过期时间和状态。
- channels: 频道列表，包含名称、描述、是否为公开频道。
6. 部署与构建
6.1 构建脚本 (build.bat)
- 支持跨平台编译（Linux、Windows、Mac）。
- 使用 UPX 压缩生成的二进制文件。
- 自动生成版本号并嵌入到程序中。
6.2 启动命令
-
服务端启动:
go run main.go -
客户端启动:
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）。