z-docs/docs/tutorial-extras/auth-config.md

sidebar_position, title, description

sidebar_position	title	description
5	权限配置	ZHub 权限配置和认证管理

ZHub 权限配置

配置方式

• app.ini: 开启/关闭权限验证
• auth.yml: 详细权限配置

权限控制

• 连接认证：通过Token验证客户端身份
• 主题权限：控制对特定主题的读写权限
• 操作类型：区分读取(r)和写入(w)操作

基础配置

开启权限验证：

[service]
auth=1    # 开启连接授权

关闭权限验证：

[service]
auth=0    # 关闭连接授权（内网环境）

---

auth.yml 配置文件

配置文件结构

# 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 项目

// 带认证的连接
ZHubClient zhub = new ZHubClient(
    "127.0.0.1:1216",    // 服务地址
    "groupid-x",         // 消费者组
    "appid-unique-001",  // 应用ID（必须唯一）
    "token-12345"        // 认证令牌
);

SpringBoot 项目

# 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 消息回复失败 :::

权限管理

# 重新加载权限配置
curl http://127.0.0.1:711/auth/reload

内网环境

# app.ini - 关闭权限验证（仅内网环境）
[service]
auth=0

权限配置示例

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: ["*"]

---

管理接口

# 重新加载权限配置
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

权限最小化

# 只给必要的权限
- id: 1
  username: "order-service"
  reads: ["order.*", "user.basic.*"]
  writes: ["order.*"]

环境配置

• 开发环境: 可关闭权限验证 (auth=0)
• 生产环境: 必须开启权限验证 (auth=1)
• 使用强随机 Token
• 定期轮换 Token