# zhub

**Repository Path**: tc608/zhub

## Basic Information

- **Project Name**: zhub
- **Description**: zhub 轻量级消息中间件：golang 实现 高性能发布-订阅、广播消息、延时消息、定时消息、RPC、分布式锁
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://zhub.dev
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2021-02-12
- **Last Updated**: 2025-12-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Go语言, 消息中间件, zhub

## README

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