289 lines
7.3 KiB
Markdown
289 lines
7.3 KiB
Markdown
---
|
||
title: 快速上手
|
||
description: ZHub 轻量级消息中间件快速入门指南，包含安装配置、基础使用和功能特性介绍
|
||
sidebar_position: 1
|
||
---
|
||
|
||
# ZHub 快速上手
|
||
|
||
## 概述
|
||
ZHub 是一个轻量级消息中间件，支持发布订阅、广播消息、延时消息、RPC调用等功能。运行包仅1M+，启动内存10M-。
|
||
|
||
**核心特性**：
|
||
- 消息顺序保证：单个主题内严格按发送顺序处理
|
||
- 高性能：内存处理，支持高并发
|
||
- 轻量级：运行包1M+，启动内存10M-
|
||
|
||
|
||
|
||
---
|
||
|
||
## 搭建 ZHub 服务
|
||
|
||
### 下载软件包
|
||
|
||
**下载地址**: [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
|
||
|
||
```ini
|
||
[service]
|
||
watch=0.0.0.0:711 # 管理端口
|
||
addr=0.0.0.0:1216 # 服务端口
|
||
auth=0 # 权限验证 0关闭/1开启
|
||
|
||
[data]
|
||
dir=./data # 数据目录
|
||
|
||
[log]
|
||
handlers=console # 日志输出
|
||
level=debug # 日志级别
|
||
```
|
||
|
||
**重要**：
|
||
- 客户端 `appid` 必须唯一
|
||
- 生产环境建议开启权限验证
|
||
|
||
**性能注意事项**：
|
||
- 服务端通道容量500条，满时消息会被丢弃
|
||
- 定期执行内存清理：`curl http://127.0.0.1:711/_/cleanup`
|
||
- 监控服务状态：`curl http://127.0.0.1:711/_/info`
|
||
|
||
---
|
||
|
||
### 初始化数据库（可选, 定时调度调度任务配置）
|
||
|
||
**MySQL**：
|
||
```sql
|
||
CREATE DATABASE zhub;
|
||
CREATE TABLE `zhub`.`tasktimer` (
|
||
`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
|
||
# Linux/Mac
|
||
chmod +x ./zhub.sh && ./zhub.sh
|
||
|
||
# Windows
|
||
# 解压后直接运行
|
||
```
|
||
|
||
**端口**：管理端口 711，服务端口 1216
|
||
---
|
||
|
||
## 连接使用
|
||
### 导入依赖
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
<Tabs>
|
||
<TabItem value="apple" label="普通Java项目" default>
|
||
|
||
```xml
|
||
<!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-0.1.0424.dev.jar ） -->
|
||
<repositories>
|
||
<repository>
|
||
<id>maven-nexus</id>
|
||
<name>maven-nexus</name>
|
||
<url>https://nexus.1216.top/repository/maven-public/</url>
|
||
</repository>
|
||
</repositories>
|
||
|
||
<dependencies>
|
||
<!-- 常规Java项目 -->
|
||
<dependency>
|
||
<groupId>dev.zhub</groupId>
|
||
<artifactId>zhub-client</artifactId>
|
||
<version>0.1.0424.dev</version>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="orange" label="SpringBoot 项目">
|
||
|
||
```xml
|
||
<!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-spring-0.1.0424.dev.jar ） -->
|
||
<repositories>
|
||
<repository>
|
||
<id>maven-nexus</id>
|
||
<name>maven-nexus</name>
|
||
<url>https://nexus.1216.top/repository/maven-public/</url>
|
||
</repository>
|
||
</repositories>
|
||
|
||
<dependencies>
|
||
<!-- SpringBoot项目 -->
|
||
<dependency>
|
||
<groupId>dev.zhub</groupId>
|
||
<artifactId>zhub-client-spring</artifactId>
|
||
<version>0.1.0424.dev</version>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="banana" label="Redkale项目">
|
||
|
||
```xml
|
||
<!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-redkale-0.1.0424.dev.jar ） -->
|
||
<repositories>
|
||
<repository>
|
||
<id>maven-nexus</id>
|
||
<name>maven-nexus</name>
|
||
<url>https://nexus.1216.top/repository/maven-public/</url>
|
||
</repository>
|
||
</repositories>
|
||
|
||
<dependencies>
|
||
<!-- Redkale项目 -->
|
||
<dependency>
|
||
<groupId>dev.zhub</groupId>
|
||
<artifactId>zhub-client-redkale</artifactId>
|
||
<version>0.1.0424.dev</version>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 配置初始化
|
||
<Tabs>
|
||
<TabItem value="apple" label="普通Java项目" default>
|
||
|
||
```
|
||
// 参数说明：①连接地址ip+端口， ②消费者组名称，③连接APPID (接入的多个客户端使用不同的连接APPID)
|
||
// 开启权限验证时添加第四个参数：授权码
|
||
ZHubClient zhub = new ZHubClient("127.0.0.1:1216", "groupid-x", "appid-x", "token-12345");
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="orange" label="SpringBoot 项目">
|
||
|
||
```yaml
|
||
# application.yml
|
||
zhub:
|
||
addr: 127.0.0.1:1216
|
||
groupid: groupid-x
|
||
appid: zhub_demo_1
|
||
auth: token-12345 # 开启权限验证时配置授权码
|
||
```
|
||
```java
|
||
// 自动注入连接对象
|
||
@Autowired
|
||
protected ZHubClient zhub;
|
||
```
|
||
</TabItem>
|
||
<TabItem value="banana" label="Redkale项目">
|
||
|
||
```properties
|
||
# source.properties
|
||
redkale.cluster.zhub[zhub].addr = 127.0.0.1:1216
|
||
redkale.cluster.zhub[zhub].auth = token-12345 # 开启权限验证时配置授权码
|
||
redkale.cluster.zhub[zhub].groupid = zcore-zhub
|
||
# redkale.cluster.zhub[zhub].appid = zhub_demo_1 # (无需配置，取 redklae 配置的 appname)
|
||
```
|
||
```java
|
||
// 自动注入连接对象
|
||
@Resource(name = "zhub")
|
||
protected ZHubClient zhub;
|
||
```
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
---
|
||
|
||
### 快速体验
|
||
|
||
#### 1. 消息发布订阅
|
||
```java
|
||
// 订阅消息
|
||
zhub.subscribe("topic-a", x -> {
|
||
System.out.println("接收到消息：" + x);
|
||
});
|
||
|
||
// 发布消息
|
||
zhub.publish("topic-a", "Hello ZHub!");
|
||
```
|
||
|
||
#### 2. RPC 远程调用
|
||
```java
|
||
// 服务端：提供 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());
|
||
```
|
||
|
||
#### 3. 其他功能
|
||
```java
|
||
// 广播消息
|
||
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) |