lxy/z-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
绝尘
2025-09-23 21:48:31 +08:00
parent 88011cf20b
commit 5af775e525
35 changed files with 4133 additions and 412 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/admin-apis/_category_.json Normal file
View File

@@ -0,0 +1,8 @@
{
"label": "管理接口 API",
"position": 2,
"link": {
"type": "generated-index",
"description": "ZHub 服务管理接口详细说明，包括服务监控、配置重载、资源清理等功能。"
}
}

141
docs/admin-apis/auth-reload-api.md Normal file
View File

@@ -0,0 +1,141 @@
---
sidebar_position: 4
title: 重新加载权限配置接口
description: ZHub 权限配置重新加载接口
---
# 重新加载权限配置接口
## 接口说明
- **路径**: `GET /auth/reload`
- **功能**: 重新加载 `auth.yml` 权限配置文件
- **用途**: 修改权限配置后无需重启服务即可生效
## 使用示例
```bash
# 重新加载权限配置
curl http://127.0.0.1:711/auth/reload
```
## 使用场景
- 修改了 `auth.yml` 文件中的权限配置
- 添加或删除了用户权限
- 修改了连接授权规则
- 更新了角色权限设置
## 操作步骤
1. **修改配置**: 编辑 `auth.yml` 配置文件
2. **执行重载**: 调用 `/auth/reload` 接口
3. **验证生效**: 新的权限配置立即生效
## 权限配置文件
### auth.yml 结构
权限配置存储在 `auth.yml` 文件中，主要包含以下配置：
```yaml
# 用户权限配置
users:
- username: admin
password: admin123
roles: [admin]
- username: user1
password: user123
roles: [user]
# 角色权限配置
roles:
admin:
permissions:
- "topic:read"
- "topic:write"
- "admin:*"
user:
permissions:
- "topic:read"
# 连接授权规则
connection_rules:
- pattern: "admin.*"
required_roles: [admin]
- pattern: "user.*"
required_roles: [user]
```
### 配置示例
```yaml
# 添加新用户
users:
- username: newuser
password: newpass123
roles: [operator]
# 添加新角色
roles:
operator:
permissions:
- "topic:read"
- "topic:write"
- "monitor:*"
```
## 应用场景
1. **用户管理**: 添加或删除系统用户
2. **权限调整**: 修改用户或角色的权限设置
3. **安全策略**: 更新连接授权规则
4. **临时权限**: 为特定操作临时调整权限
## 权限类型
### 主题权限
- `topic:read`: 读取主题消息权限
- `topic:write`: 发布主题消息权限
- `topic:subscribe`: 订阅主题权限
### 管理权限
- `admin:*`: 所有管理权限
- `admin:config`: 配置管理权限
- `admin:monitor`: 监控管理权限
### 系统权限
- `system:*`: 系统级权限
- `system:shutdown`: 系统关闭权限
- `system:restart`: 系统重启权限
## 注意事项
:::warning 安全提醒
- 权限配置重载会立即生效，请谨慎操作
- 建议在非业务高峰期执行重载操作
- 重载前请备份当前的权限配置
- 确保不会意外撤销重要权限
:::
## 错误处理
如果重载过程中出现错误：
1. **配置检查**: 验证 `auth.yml` 文件格式是否正确
2. **权限验证**: 确保配置的权限和角色有效
3. **日志查看**: 检查服务日志中的错误信息
4. **配置恢复**: 如有必要，恢复之前的配置文件
## 安全建议
1. **定期审核**: 定期审核用户权限配置
2. **最小权限**: 遵循最小权限原则
3. **密码策略**: 使用强密码策略
4. **访问日志**: 记录权限相关的访问日志

53
docs/admin-apis/cleanup-api.md Normal file
View File

@@ -0,0 +1,53 @@
---
sidebar_position: 2
title: 清理内存接口
description: ZHub 服务内存清理接口
---
# 清理内存接口
## 接口说明
- **路径**: `GET /_/cleanup`
- **功能**: 清理可回收的内存资源
- **用途**: 释放无用的主题和消息，优化内存使用
## 清理条件
清理满足以下条件的主题：
- `subsize = 0` - 没有订阅者
- `mcount = offset` - 没有待消费的消息
## 使用示例
```bash
# 手动触发内存清理
curl http://127.0.0.1:711/_/cleanup
```
## 返回信息
接口返回清理操作的结果：
- **成功**: 返回 `"+OK"`
- **失败**: 返回错误信息
**响应示例**：
```json
"+OK"
```
## 清理机制
**手动清理**：通过调用此接口立即触发清理操作
- 清理所有符合条件的主题
- 释放相关内存资源
## 应用场景
1. **内存优化**: 当发现内存占用过高时手动清理
2. **性能调优**: 在性能测试后清理测试数据
3. **资源回收**: 清理不再使用的主题和消息

70
docs/admin-apis/info-api.md Normal file
View File

@@ -0,0 +1,70 @@
---
sidebar_position: 1
title: 查看注册情况接口
description: ZHub 服务注册情况查询接口
---
# 查看注册情况接口
## 接口说明
- **路径**: `GET /_/info`
- **功能**: 查看当前服务的注册情况，包括主题订阅、连接状态等信息
- **用途**: 监控服务运行状态，排查问题
## 使用示例
```bash
# 查看服务注册情况
curl http://127.0.0.1:711/_/info
```
## 返回信息
接口返回当前服务的详细状态信息，包括：
- **topics**: 主题详细信息，包含每个主题的组信息
- **topicsize**: 当前活跃的主题数量
- **timersize**: 定时任务数量
- **conns**: 连接信息列表，包含远程地址、组ID、订阅主题等
- **connsize**: 当前连接数
**响应示例**：
```json
{
"topics": {
"user.login": [
{
"name": "group1",
"subsize": 3,
"offset": 100,
"mcount": 120
}
]
},
"topicsize": 25,
"timersize": 10,
"conns": [
{
"remoteaddr": "127.0.0.1:12345",
"groupid": "test-group",
"topics": ["user.*"],
"timers": ["timer1"],
"user": "admin"
}
],
"connsize": 5
}
```
## 应用场景
1. **服务监控**: 定期检查服务运行状态
2. **问题排查**: 当服务出现异常时查看详细信息
3. **性能分析**: 了解当前的主题和连接数量
4. **运维管理**: 评估服务负载和资源使用情况
## 注意事项
- 该接口为只读操作，不会修改服务状态
- 返回的信息实时反映当前服务状态

34
docs/admin-apis/other-apis.md Normal file
View File

@@ -0,0 +1,34 @@
---
sidebar_position: 5
title: 其他管理接口
description: ZHub 其他管理接口说明
---
# 其他管理接口
除了核心的管理接口外，ZHub 还提供了其他有用的管理接口，用于版本查询、消息发送和延时消息管理等功能。
---
## 版本信息接口
### 接口说明
- **路径**: `GET /_/version`
- **功能**: 查看服务版本信息
- **用途**: 确认服务版本，进行版本管理
### 使用示例
```bash
# 查看服务版本
curl http://127.0.0.1:711/_/version
```
### 返回信息
返回当前 ZHub 服务的版本信息，包括：
- 服务版本号
- 构建时间
---

61
docs/admin-apis/overview.md Normal file
View File

@@ -0,0 +1,61 @@
---
sidebar_position: 0
title: 管理接口概览
description: ZHub 服务管理接口总览
---
# ZHub 管理接口概览
管理接口通过 HTTP 访问，默认端口 `711`。
**配置**：在 `app.ini` 中修改 `[service]` 部分的 `watch` 参数
## 接口列表
**核心接口**：
- `GET /_/info` - 查看服务状态
- `GET /_/cleanup` - 清理内存
- `GET /timer/reload` - 重载定时配置
- `GET /auth/reload` - 重载权限配置
**辅助接口**：
- `GET /_/version` - 查看版本信息
- `POST /message/send` - HTTP 发送消息
- `GET /topic/delay` - 查看延时消息状态
## 使用示例
```bash
# 查看服务状态
curl http://127.0.0.1:711/_/info
# 清理内存
curl http://127.0.0.1:711/_/cleanup
# 重载配置
curl http://127.0.0.1:711/timer/reload
curl http://127.0.0.1:711/auth/reload
# 查看版本
curl http://127.0.0.1:711/_/version
```
## 配置管理
**端口配置**：
```ini
[service]
watch = 0.0.0.0:711 # 管理端口
```
## 安全注意事项
- 管理接口默认监听所有网络接口
- 生产环境建议添加认证机制
- 避免在公网环境暴露管理接口
## 监控建议
- 定期检查服务状态：`/_/info`
- 监控内存使用，必要时执行清理
- 修改配置后及时执行 reload 接口

51
docs/admin-apis/timer-reload-api.md Normal file
View File

@@ -0,0 +1,51 @@
---
sidebar_position: 3
title: 重新加载定时调度配置接口
description: ZHub 定时调度配置重新加载接口
---
# 重新加载定时调度配置接口
## 接口说明
- **路径**: `GET /timer/reload`
- **功能**: 重新加载数据库中的定时调度配置
- **用途**: 当修改了数据库中的 timer 配置后，无需重启服务即可生效
## 使用示例
```bash
# 重新加载定时调度配置
curl http://127.0.0.1:711/timer/reload
```
## 使用场景
- 修改了 `tasktimer` 表中的定时任务配置
- 添加或删除了定时任务
- 修改了定时任务的执行表达式
- 更新了定时任务的执行参数
## 操作步骤
1. **修改配置**: 在数据库中修改 `zhub.tasktimer` 表
2. **执行重载**: 调用 `/timer/reload` 接口
3. **验证生效**: 新的定时配置立即生效
## 数据库配置
### tasktimer 表结构
定时任务配置存储在 `zhub.tasktimer` 表中，包含以下关键字段：
- `task_name`: 任务名称
- `cron_expression`: Cron 表达式
- `task_class`: 任务执行类
- `enabled`: 是否启用
- `parameters`: 任务参数
## 注意事项
:::info 重要提醒
- 重载操作会立即生效，请确保配置正确
:::