192 lines
3.5 KiB
Markdown
192 lines
3.5 KiB
Markdown
---
|
||
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
|