---
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