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

2025-09-23 21:48:31 +08:00
parent 88011cf20b
commit 5af775e525
35 changed files with 4133 additions and 412 deletions
--- a/docs/tutorial-extras/zhub-log.md
+++ b/docs/tutorial-extras/zhub-log.md
@@ -0,0 +1,278 @@
+---
+sidebar_position: 11
+title: 日志管理
+description: ZHub 日志配置、格式分析、故障排查和监控指南
+keywords: [ZHub日志, 日志管理, 日志分析, 故障排查, 监控]
+---
+
+# 日志管理
+
+ZHub 日志文件配置、分析和故障排查指南。
+
+## 目录
+
+- [日志配置](#日志配置)
+- [日志文件位置](#日志文件位置)
+- [服务端日志](#日志内容分析)
+- [Java客户端日志](#java-客户端日志)
+- [日志分析](#日志分析)
+- [日志轮转](#日志轮转)
+- [故障排查](#故障排查)
+
+## 日志配置
+
+### 基础配置
+
+**app.ini 配置**：
+```ini
+[log]
+level=info          # 日志级别: debug, info, error
+handlers=console    # 日志处理器: console, file
+file=zhub.log       # 日志文件名
+```
+
+### 日志级别说明
+
+| 级别 | 说明 | 使用场景 |
+|------|------|----------|
+| debug | 调试信息 | 开发调试，包含详细的执行流程 |
+| info | 一般信息 | 生产环境，记录重要操作 |
+| error | 错误信息 | 严重错误，需要关注 |
+
+## 日志文件位置
+
+### 默认位置
+```bash
+# 当前目录下的日志文件
+./zhub.log
+```
+
+### 自定义位置
+```ini
+# app.ini 中指定日志目录
+[log]
+file=/var/log/zhub/zhub.log
+```
+
+## 日志内容分析
+
+### 连接接入日志
+
+**连接建立**：
+```
+2024/01/15 10:30:15.123456 zbus.go:291: [Info] conn start: 127.0.0.1:12345 [1]
+```
+- 格式：`[Info] conn start: IP:端口 [连接序号]`
+- 连接序号：每个新连接递增的数字标识
+
+**连接断开**：
+```
+2024/01/15 10:30:20.123456 zbus.go:302: [Info] conn closed: 127.0.0.1:12345 [ 1 ]
+```
+- 格式：`[Info] conn closed: IP:端口 [ 连接序号 ]`
+- 包含正常断开和异常断开
+
+**认证过程**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:84: [Info] [1] -Auth: publish [user-login]
+2024/01/15 10:30:15.123456 zbus-message-handler.go:122: [Info] [1] cmd: publish, auth [OK]
+```
+- `-Auth:` 表示权限不足
+- `auth [OK]` 表示认证成功
+
+### 消息收发日志
+
+**消息发布**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: publish user-login {"userId":"12345"}
+```
+- 格式：`[连接序号] cmd: publish 主题名 消息内容`（debug级别）
+- 仅在debug级别下显示
+
+**消息订阅**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: subscribe user-login order-create
+2024/01/15 10:30:15.123456 zbus-message-handler.go:122: [Info] [1] cmd: subscribe, auth [OK]
+```
+- 格式：`[连接序号] cmd: subscribe 主题列表`（debug级别）
+- 支持多主题订阅，空格分隔
+
+**广播消息**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: broadcast topic-abc hello!
+```
+- 格式：`[连接序号] cmd: broadcast 主题名 消息内容`（debug级别）
+
+**延时消息**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: delay order-timeout 30s 订单超时
+```
+- 格式：`[连接序号] cmd: delay 主题名 延时时间 消息内容`（debug级别）
+
+### RPC 调用日志
+
+**RPC 调用**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: rpc user-get-info {"ruk":"app1::12345"}
+```
+- 格式：`[连接序号] cmd: rpc 服务名 RPC参数`（debug级别）
+- RPC参数包含ruk（回复标识）
+
+**RPC 服务离线**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:132: [1] : rpc user-get-info no subscribe
+```
+- 格式：`[连接序号] : rpc 服务名 no subscribe`
+- 表示没有客户端订阅该RPC服务
+
+**RPC 权限不足**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:84: [Info] [1] -Auth: rpc [user-get-info]
+```
+- 格式：`[Info] [连接序号] -Auth: rpc [服务名]`
+
+### 定时任务日志
+
+**定时任务执行**：
+```
+2024/01/15 10:30:00.123456 monitor.go:56: [Info] broadcast timer T:A 执行
+2024/01/15 10:30:05.123456 monitor.go:56: [Info] broadcast timer T:B 执行
+```
+- 格式：`[Info] broadcast timer 任务名 执行`
+- 来自monitor模块的定时任务执行日志
+
+**定时任务订阅**：
+```
+2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: timer T:A T:B
+```
+- 格式：`[连接序号] cmd: timer 任务列表`（debug级别）
+- 客户端订阅定时任务时记录
+
+## Java 客户端日志
+
+### 消息接收日志
+
+**订阅消息**：
+```
+FINEST: topic[user.login]: {"userId":"12345","username":"张三"}
+```
+- 格式：`FINEST: topic[主题名]: 消息内容`
+- 记录接收到的订阅消息
+
+**广播消息**：
+```
+FINEST: topic[topic-abc]: hello!
+```
+- 格式：`FINEST: topic[主题名]: 消息内容`
+
+### 定时任务日志
+
+**任务触发**：
+```
+FINEST: timer[T:A]: 
+```
+- 格式：`FINEST: timer[任务名]: `
+
+**任务执行完成**：
+```
+FINEST: timer [T:A] : elapsed time 15 ms
+```
+- 格式：`FINEST: timer [任务名] : elapsed time 耗时 ms`
+
+### RPC 调用日志
+
+**RPC响应**：
+```
+FINEST: rpc-back:[user.getInfo]: {"retcode":0,"result":"用户信息"}
+```
+- 格式：`FINEST: rpc-back:[服务名]: 响应内容`
+
+**RPC错误**：
+```
+WARNING: rpc-back[user.getInfo] event accept error :{"retcode":500,"result":"服务错误"}
+```
+- 格式：`WARNING: rpc-back[服务名] event accept error :响应内容`
+
+### 错误日志
+
+**超时错误**：
+```
+SEVERE: timer [T:A] time out: 5 S
+```
+- 格式：`SEVERE: timer [任务名] time out: 超时时间 S`
+
+**处理异常**：
+```
+WARNING: topic[user.login] event accept error :{"userId":"12345"}
+SEVERE: topic[user.login] event deal time out: 5 S, value: {"userId":"12345"}
+```
+- 格式：`WARNING: topic[主题名] event accept error :消息内容`
+- 格式：`SEVERE: topic[主题名] event deal time out: 超时时间 S, value: 消息内容`
+
+## 日志分析
+
+### 关键日志识别
+
+**连接状态监控**：
+- `conn start:` - 新连接建立
+- `conn closed:` - 连接断开
+- `-Auth:` - 权限认证失败
+
+**消息处理监控**：
+- `cmd: publish` - 消息发布（debug级别）
+- `cmd: subscribe` - 消息订阅
+- `cmd: rpc` - RPC调用
+- `no subscribe` - 服务离线
+
+**Java客户端监控**：
+- `topic[主题名]:` - 消息接收
+- `timer[任务名]:` - 定时任务触发
+- `rpc-back:[服务名]:` - RPC响应
+- `time out:` - 超时错误
+- `event accept error` - 处理异常
+- `event deal time out` - 处理超时
+
+**错误信息识别**：
+- `-Error:` - 系统错误
+- `Recovered:` - 异常恢复
+- `-Auth:` - 权限不足
+
+### 监控要点
+
+1. **连接稳定性**：关注连接建立和断开的频率
+2. **权限问题**：监控`-Auth:`日志，排查权限配置
+3. **服务可用性**：关注`no subscribe`日志，确保RPC服务正常
+4. **系统健康**：检查`-Error:`和`Recovered:`日志
+5. **客户端性能**：监控`time out:`日志，关注处理超时
+6. **消息处理**：观察`topic[主题名]:`日志，确保消息正常接收
+
+## 日志轮转
+
+### 手动轮转
+```bash
+# 重命名当前日志文件
+mv zhub.log zhub.log.$(date +%Y%m%d)
+
+# 重启服务
+./zhub.sh restart
+```
+
+## 故障排查
+
+### 常见问题
+
+**1. 日志文件过大**
+- 定期清理旧日志文件
+- 调整日志级别为info
+
+**2. 日志级别过高**
+- 生产环境建议使用info级别
+- 开发环境可使用debug级别
+
+### 最佳实践
+
+1. **定期检查**：关注错误和权限相关日志
+2. **监控连接**：观察连接建立和断开情况
+3. **服务状态**：确保RPC服务正常运行
+4. **日志轮转**：定期清理旧日志文件
+5. **级别设置**：生产环境使用info级别