zhub/README.md

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）。