添加：ZHub 管理接口文档和客户端使用指南

2025-09-23 21:48:31 +08:00
parent 88011cf20b
commit 5af775e525
35 changed files with 4133 additions and 412 deletions
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -1,90 +1,121 @@
 ---
+title: 快速上手
+description: ZHub 轻量级消息中间件快速入门指南，包含安装配置、基础使用和功能特性介绍
 sidebar_position: 1
 ---

 # ZHub 快速上手

 ## 概述
-> zhub是⼀个⾼性能事件发布订阅服务组件，功能丰富，包含发布-订阅、⼴播消息、延时消息、
-Rpc调⽤、分布式定时调度、分布式锁，运⾏包仅有1M+；低服务资源消费，初始启动内存 10M-。
+ZHub 是一个轻量级消息中间件，支持发布订阅、广播消息、延时消息、RPC调用等功能。运行包仅1M+，启动内存10M-。
+
+**核心特性**：
+- 消息顺序保证：单个主题内严格按发送顺序处理
+- 高性能：内存处理，支持高并发
+- 轻量级：运行包1M+，启动内存10M-

  ![zhub-fun.png](https://img.1216.top/docs/zhub/zhub-fun.png)

 ---

-## 开始 搭建 zhub 服务
-> 让我们在 **5到10分钟内完成 zhub 中间件安装、集成、测试**.
+## 搭建 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` 配置文件
-      ![zhub-zip.png](https://img.1216.top/docs/zhub/dist-zip.png)
+**下载地址**: [https://zhub.dev/release/latest/](https://zhub.dev/release/latest/)
+
+**支持平台**：
+- `zhub-linux-amd64.tar` - Linux AMD64
+- `zhub-linux-arm64.tar` - Linux ARM64  
+- `zhub-win-amd64.tar` - Windows AMD64
+
+**目录结构**：
+```
+zhub/
+├── zhub.sh      # 可执行文件
+├── app.ini      # 服务配置
+└── auth.yml     # 权限配置（可选）
+```

 ### 配置 app.ini

-```bash
-# app.ini
+```ini
 [service]
-watch=0.0.0.0:711           # 服务管理端口
+watch=0.0.0.0:711           # 管理端口
 addr=0.0.0.0:1216           # 服务端口
-auth=0                      # 是否开启连接授权 0不开启、1开启
+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
+handlers=console            # 日志输出
+level=debug                 # 日志级别
 ```

+**重要**：
+- 客户端 `appid` 必须唯一
+- 生产环境建议开启权限验证
+
+**性能注意事项**：
+- 服务端通道容量500条，满时消息会被丢弃
+- 定期执行内存清理：`curl http://127.0.0.1:711/_/cleanup`
+- 监控服务状态：`curl http://127.0.0.1:711/_/info`
+
 ---

-### 初始化 ztimer 数据库 (可选，如果不使用定时调度则不需要配置)
+### 初始化数据库（可选, 定时调度调度任务配置）

+**MySQL**：
 ```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);
+  `timerid` varchar(64) NOT NULL DEFAULT '' PRIMARY KEY COMMENT '任务ID',
+  `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停用'
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='定时任务表';
+```
+
+**PostgreSQL**：
+```sql
+CREATE DATABASE zhub;
+CREATE TABLE tasktimer (
+  timerid varchar(64) NOT NULL DEFAULT '' PRIMARY KEY,
+  name varchar(32) NOT NULL DEFAULT '',
+  expr varchar(32) NOT NULL DEFAULT '',
+  single int NOT NULL DEFAULT 1,
+  remark varchar(128) NOT NULL DEFAULT '',
+  status smallint NOT NULL DEFAULT 10
+);
+
+-- 添加表和字段注释
+COMMENT ON TABLE tasktimer IS '定时任务表';
+COMMENT ON COLUMN tasktimer.timerid IS '任务ID';
+COMMENT ON COLUMN tasktimer.name IS '任务名称';
+COMMENT ON COLUMN tasktimer.expr IS '时间表达式';
+COMMENT ON COLUMN tasktimer.single IS '单实例：1是，0否';
+COMMENT ON COLUMN tasktimer.remark IS '备注';
+COMMENT ON COLUMN tasktimer.status IS '状态：10启用，60停用';
 ```

 ### 启动服务

 ```bash
-# window 
-./zhub.exe
-# linux (添加执行权限 chmod +x ./zhub.sh)
-./zhub.sh
+# Linux/Mac
+chmod +x ./zhub.sh && ./zhub.sh
+
+# Windows
+# 解压后直接运行
 ```
+
+**端口**：管理端口 711，服务端口 1216
 ---

 ## 连接使用
-### 导入连接驱动 (根据不同的项目选择不同的导入方式)
+### 导入依赖

 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -93,7 +124,7 @@ import TabItem from '@theme/TabItem';
 <TabItem value="apple" label="普通Java项目" default>

  ```xml
-  <!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-0.1.1.dev.jar ） -->
+  <!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-0.1.0424.dev.jar ） -->
  <repositories>
      <repository>
          <id>maven-nexus</id>
@@ -105,9 +136,9 @@ import TabItem from '@theme/TabItem';
  <dependencies>
  <!-- 常规Java项目 -->
  <dependency>
-      <groupId>net.tccn</groupId>
+      <groupId>dev.zhub</groupId>
      <artifactId>zhub-client</artifactId>
-      <version>0.1.1.dev</version>
+      <version>0.1.0424.dev</version>
  </dependency>
  </dependencies>
  ```
@@ -116,7 +147,7 @@ import TabItem from '@theme/TabItem';
 <TabItem value="orange" label="SpringBoot 项目">

  ```xml
-  <!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-spring-0.1.1.jar ） -->
+  <!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-spring-0.1.0424.dev.jar ） -->
  <repositories>
      <repository>
          <id>maven-nexus</id>
@@ -126,11 +157,11 @@ import TabItem from '@theme/TabItem';
  </repositories>
  
  <dependencies>
-  <!-- 常规Java项目 -->
+  <!-- SpringBoot项目 -->
  <dependency>
-      <groupId>net.tccn</groupId>
+      <groupId>dev.zhub</groupId>
      <artifactId>zhub-client-spring</artifactId>
-      <version>0.1.1.dev</version>
+      <version>0.1.0424.dev</version>
  </dependency>
  </dependencies>
  ```
@@ -139,7 +170,7 @@ import TabItem from '@theme/TabItem';
 <TabItem value="banana" label="Redkale项目">

  ```xml
-  <!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-redkale-0.1.1.jar ） -->
+  <!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-redkale-0.1.0424.dev.jar ） -->
  <repositories>
      <repository>
          <id>maven-nexus</id>
@@ -149,11 +180,11 @@ import TabItem from '@theme/TabItem';
  </repositories>
  
  <dependencies>
-  <!-- 常规Java项目 -->
+  <!-- Redkale项目 -->
  <dependency>
-      <groupId>net.tccn</groupId>
+      <groupId>dev.zhub</groupId>
      <artifactId>zhub-client-redkale</artifactId>
-      <version>0.1.1.dev</version>
+      <version>0.1.0424.dev</version>
  </dependency>
  </dependencies>
  ```
@@ -167,19 +198,20 @@ import TabItem from '@theme/TabItem';

 ```
  // 参数说明：①连接地址ip+端口， ②消费者组名称，③连接APPID (接入的多个客户端使用不同的连接APPID)
-  ZHubClient zhub = new ZHubClient("127.0.0.1:1216", "groupid-x", "appid-x");
+  // 开启权限验证时添加第四个参数：授权码
+  ZHubClient zhub = new ZHubClient("127.0.0.1:1216", "groupid-x", "appid-x", "token-12345");
 ```

 </TabItem>
 <TabItem value="orange" label="SpringBoot 项目">

-```yml
+```yaml
 # application.yml
 zhub:
-  addr: 47.107.112.45:1216
+  addr: 127.0.0.1:1216
  groupid: groupid-x
  appid: zhub_demo_1
-  # auth: token-12345 # 启用 auth情况下接入验权配置
+  auth: token-12345  # 开启权限验证时配置授权码
 ```
 ```java
  // 自动注入连接对象
@@ -189,10 +221,10 @@ zhub:
 </TabItem>
 <TabItem value="banana" label="Redkale项目">

-```yaml
+```properties
 # source.properties
 redkale.cluster.zhub[zhub].addr = 127.0.0.1:1216
-redkale.cluster.zhub[zhub].auth = token-12345
+redkale.cluster.zhub[zhub].auth = token-12345  # 开启权限验证时配置授权码
 redkale.cluster.zhub[zhub].groupid = zcore-zhub
 # redkale.cluster.zhub[zhub].appid = zhub_demo_1 # (无需配置，取 redklae 配置的 appname)
 ```
@@ -206,68 +238,52 @@ redkale.cluster.zhub[zhub].groupid = zcore-zhub

 ---

-### 使用 zhub 收发消息
-> 通过上面的操作，我们已经得到了一个 zhub 的连接实例，下面来看看具体的使用
-> 
+### 快速体验

-1、消息的发布-订阅
+#### 1. 消息发布订阅
 ```java
-  zhub.subscribe("topic-a", x -> {
-      System.out.println("接收到 a 事件：" + x);
-  });
+// 订阅消息
+zhub.subscribe("topic-a", x -> {
+    System.out.println("接收到消息：" + x);
+});
+
+// 发布消息
+zhub.publish("topic-a", "Hello ZHub!");
 ```
+
+#### 2. RPC 远程调用
 ```java
-  zhub.publish("topic-a", "123");
+// 服务端：提供 RPC 服务
+zhub.rpcSubscribe("user.getInfo", IType.STRING, request -> {
+    String userId = request.getValue();
+    return request.render("用户信息: " + userId);
+});
+
+// 客户端：调用 RPC 服务
+RpcResult<String> result = zhub.rpc("user.getInfo", "user123", IType.STRING);
+System.out.println("RPC 结果: " + result.getResult());
 ```
-2、rpc的订阅-调用
+
+#### 3. 其他功能
 ```java
-  zhub.rpcSubscribe("rpc-b", IType.STRING, r -> {
-      String str = r.getValue();
-      System.out.println("接收到 b 事件：" + str);
-      return r.render("接收到 b 事件：" + str);
-  });
-```
-```java
-  RpcResult<String> rpcResult = zhub.rpc("rpc-b", "hello rpc", IType.STRING);
-  String result = rpcResult.getResult();
-  System.out.println("rpc result:" + result);
-```
-3、广播消息
-```java
-  zhub.broadcast("topic-a", "123");
-```
-4、延时消息
-```java
-  zhub.delay("topic-a", "123", 1000 * 60 * 5);
-```
-5、定时调度
-```java
-  zhub.timer("T:A", () -> {
-      System.out.println("收到定时调度事件：T:A");
-  });
-```
-6、分布式锁
-```java
-  // 获取锁，直到索取到锁后返回
-  Lock lock = zhub.lock("lock-a", 5);
-  try {
-      System.out.println("获取到锁");
-  } finally {
-      lock.unLock();
-  }
-```
-```java
-  // 尝试获取锁，立即返回
-  Lock lock = zhub.tryLock("lock-a", 5);
-  if (!lock.success()) {
-    System.out.println("未获取到锁");
-    return;
-  }
-  
-  // 获取到锁
-  try {
-      System.out.println("获取到锁");
-  } finally {
-      lock.unLock();
-  }
+// 广播消息
+zhub.broadcast("topic", "message");
+
+// 延时消息
+zhub.delay("topic", "message", 5000);
 ```
+**详细文档**：
+- [发布订阅](./tutorial-basics/pub-sub.md)
+- [广播与延时消息](./tutorial-basics/broadcast-delay.md)
+- [RPC 远程调用](./tutorial-basics/rpc.md)
+
+---
+
+## 管理接口
+
+- `GET /_/info` - 查看服务状态
+- `GET /_/cleanup` - 清理内存
+- `GET /timer/reload` - 重载定时配置
+- `GET /auth/reload` - 重载权限配置
+
+详细说明：[管理接口 API](./admin-apis/overview.md)