更新：1、依赖升级
2、module 名称地址
This commit is contained in:
264
README.md
264
README.md
@@ -1,85 +1,203 @@
|
||||
# ZHub 快速上手
|
||||
# ZHub 工程项目文档
|
||||
|
||||
[ZHub 快速上手：https://docs.1216.top](https://docs.1216.top)
|
||||
|
||||
## 概述
|
||||
> zhub是⼀个⾼性能事件发布订阅服务组件，功能丰富，包含发布-订阅、⼴播消息、延时消息、
|
||||
Rpc调⽤、分布式定时调度、分布式锁，运⾏包仅有1M+；低服务资源消费，初始启动内存 10M-。
|
||||
|
||||
|
||||
## 1. 概述
|
||||
ZHub 是一个基于 Go 的高性能分布式消息中间件，支持发布/订阅模式、定时任务、延时消息、分布式锁等功能。它适用于需要高并发、低延迟的消息传递场景。
|
||||
|
||||
---
|
||||
|
||||
## 开始 搭建 zhub 服务
|
||||
> 让我们在 **5到10分钟内完成 zhub 中间件安装、集成、测试**.
|
||||
|
||||
### 下载软件包
|
||||
|
||||
- [zhub.zip (点击下载)](https://img.1216.top/docs/zhub/zhub.zip) 包含以下内容:
|
||||
- `zhub-client-0.1.1.dev.jar` 常规Java 项目驱动包
|
||||
- `zhub-client-spring-0.1.1.jar` springboot 项目驱动包
|
||||
- `zhub.exe` Window 运行包
|
||||
- `zhub.sh` Linux 运行包
|
||||
- `zhub` Mac 运行包
|
||||
- `app.ini` 配置文件
|
||||
|
||||
|
||||
### 配置 app.ini
|
||||
|
||||
```bash
|
||||
# app.ini
|
||||
[service]
|
||||
watch=0.0.0.0:711 # 服务管理端口
|
||||
addr=0.0.0.0:1216 # 服务端口
|
||||
auth=0 # 是否开启连接授权 0不开启、1开启
|
||||
|
||||
[data]
|
||||
dir=./data # 数据目录
|
||||
|
||||
[log]
|
||||
handlers=console # console|file
|
||||
level=debug # info|debug|error
|
||||
file=zhub.log
|
||||
|
||||
[ztimer] # ztimer 配置 (可选，如果不使用定时调度则可不配置)
|
||||
# db.addr=127.0.0.1:3306 # timer 使用的MySql数据库配置
|
||||
# db.user=root
|
||||
# db.password=123456
|
||||
# db.database=zhub
|
||||
```
|
||||
## 2. 技术栈
|
||||
- **语言**: Go (Golang)
|
||||
- **网络库**: `net`, `bufio`
|
||||
- **并发模型**: 使用 goroutines 和 channels 实现并发处理。
|
||||
- **持久化**: 使用文件存储（如延时任务和锁信息）。
|
||||
- **配置管理**: 使用 Viper 读取 INI 格式的配置文件。
|
||||
- **权限控制**: 基于 YAML 的用户、组、Token 和频道权限管理。
|
||||
- **监控界面**: 使用 Gin 提供 HTTP 接口用于监控和服务管理。
|
||||
- **数据库支持**: 支持 MySQL 和 PostgreSQL 用于定时任务的配置。
|
||||
|
||||
---
|
||||
|
||||
### 初始化 ztimer 数据库 (可选，如果不使用定时调度则不需要配置)
|
||||
## 3. 核心功能模块
|
||||
|
||||
```sql
|
||||
CREATE DATABASE zhub;
|
||||
CREATE TABLE `zhub`.`tasktimer` (
|
||||
`timerid` varchar(64) NOT NULL DEFAULT '' COMMENT '[主键]UUID',
|
||||
`name` varchar(32) NOT NULL DEFAULT '' COMMENT '[任务名称]',
|
||||
`expr` varchar(32) NOT NULL DEFAULT '' COMMENT '[时间表达式]',
|
||||
`single` int NOT NULL DEFAULT '1' COMMENT '[单实例消费]1单对象，0不限',
|
||||
`remark` varchar(128) NOT NULL DEFAULT '' COMMENT '[备注]',
|
||||
`status` smallint NOT NULL DEFAULT '10' COMMENT '[状态]10启用,60停用',
|
||||
PRIMARY KEY (`timerid`) USING BTREE
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
|
||||
# 初始化 四个定时任务配置, 订阅名称分别为 T:A、T:B、T:C、T:D
|
||||
INSERT INTO `zhub`.`tasktimer` (`timerid`, `name`, `expr`, `single`, `remark`, `status`) VALUES
|
||||
('T1', 'T:A', '*/5 * * * * ?', 1, '每5秒执行一次', 10),
|
||||
('T2', 'T:B', '15s', 1, '每15秒执行一次', 10),
|
||||
('T3', 'T:C', '0 0 0 * * 1', 0, '每周一00:00执行', 10),
|
||||
('T4', 'T:D', '0 0 24 * * ?', 1, '每天00:00执行', 10);
|
||||
```
|
||||
### 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 版本。
|
||||
|
||||
```bash
|
||||
# window
|
||||
./zhub.exe
|
||||
# linux (添加执行权限 chmod +x ./zhub.sh)
|
||||
./zhub.sh
|
||||
```
|
||||
---
|
||||
### 使用 zhub 收发消息
|
||||
|
||||
[使用 zhub 收发消息 https://docs.1216.top](https://docs.1216.top)
|
||||
## 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）。
|
||||
Reference in New Issue
Block a user