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

docs/tutorial-extras/auth-config.md

@@ -0,0 +1,191 @@
+---
+sidebar_position: 5
+title: 权限配置
+description: ZHub 权限配置和认证管理
+---
+
+# ZHub 权限配置
+
+## 配置方式
+
+- **app.ini**: 开启/关闭权限验证
+- **auth.yml**: 详细权限配置
+
+## 权限控制
+
+- **连接认证**：通过Token验证客户端身份
+- **主题权限**：控制对特定主题的读写权限
+- **操作类型**：区分读取(r)和写入(w)操作
+
+## 基础配置
+
+**开启权限验证**：
+```ini
+[service]
+auth=1    # 开启连接授权
+```
+
+**关闭权限验证**：
+```ini
+[service]
+auth=0    # 关闭连接授权（内网环境）
+```
+
+---
+
+## auth.yml 配置文件
+
+### 配置文件结构
+
+```yaml
+# auth.yml 权限配置文件
+users:
+  - id: 1
+    username: "admin"
+    password: "admin123"
+    status: "active"
+    groups: ["admin"]
+    reads: ["*"]      # 读取权限
+    writes: ["*"]     # 写入权限
+
+  - id: 2
+    username: "client-001"
+    password: "client123"
+    status: "active"
+    groups: ["client"]
+    reads: ["user.*", "order.*"]    # 可读取 user.* 和 order.* 主题
+    writes: ["user.*"]              # 可写入 user.* 主题
+
+groups:
+  - name: "admin"
+    description: "管理员组"
+    reads: ["*"]
+    writes: ["*"]
+
+  - name: "client"
+    description: "客户端组"
+    reads: ["user.*", "order.*"]
+    writes: ["user.*"]
+```
+
+### 配置说明
+
+#### 用户配置 (users)
+- **id**: 用户唯一标识
+- **username**: 用户名
+- **password**: 密码
+- **status**: 用户状态 (active/inactive)
+- **groups**: 所属用户组列表
+- **reads**: 读取权限列表，支持正则表达式
+- **writes**: 写入权限列表，支持正则表达式
+
+#### 用户组配置 (groups)
+- **name**: 组名
+- **description**: 组描述
+- **reads**: 组读取权限
+- **writes**: 组写入权限
+
+---
+
+## 客户端连接配置
+
+### Java 项目
+```java
+// 带认证的连接
+ZHubClient zhub = new ZHubClient(
+    "127.0.0.1:1216",    // 服务地址
+    "groupid-x",         // 消费者组
+    "appid-unique-001",  // 应用ID（必须唯一）
+    "token-12345"        // 认证令牌
+);
+```
+
+### SpringBoot 项目
+```yaml
+# application.yml
+zhub:
+  addr: 127.0.0.1:1216
+  groupid: groupid-x
+  appid: appid-unique-002
+  auth: token-12345
+```
+
+---
+
+## 重要注意事项
+
+### AppID 唯一性
+:::warning 关键要求
+- **每个客户端必须使用不同的 appid**
+- RPC 消息回复使用 appid 标识
+- 相同 appid 会导致 RPC 消息回复失败
+:::
+
+### 权限管理
+```bash
+# 重新加载权限配置
+curl http://127.0.0.1:711/auth/reload
+```
+
+### 内网环境
+```ini
+# app.ini - 关闭权限验证（仅内网环境）
+[service]
+auth=0
+```
+
+### 权限配置示例
+```yaml
+users:
+  - id: 1
+    username: "user-service"
+    reads: ["user.*"]           # 匹配 user.login, user.profile 等
+    writes: ["user.*"]
+  
+  - id: 2
+    username: "order-service"
+    reads: ["order.*", "user.basic.*"]
+    writes: ["order.*"]
+  
+  - id: 3
+    username: "admin-service"
+    reads: ["*"]                # 匹配所有主题
+    writes: ["*"]
+```
+
+---
+
+## 管理接口
+
+```bash
+# 重新加载权限配置
+curl http://127.0.0.1:711/auth/reload
+
+# 查看服务状态
+curl http://127.0.0.1:711/_/info
+```
+
+## 最佳实践
+
+### Topic 命名规范
+```
+team.service.action
+# 示例：
+user.profile.update
+order.payment.process
+```
+
+### 权限最小化
+```yaml
+# 只给必要的权限
+- id: 1
+  username: "order-service"
+  reads: ["order.*", "user.basic.*"]
+  writes: ["order.*"]
+```
+
+### 环境配置
+- **开发环境**: 可关闭权限验证 (`auth=0`)
+- **生产环境**: 必须开启权限验证 (`auth=1`)
+- 使用强随机 Token
+- 定期轮换 Token