|
|
# VBase 权限系统文档
|
|
|
|
|
|
## 1. 权限模型概述
|
|
|
|
|
|
VBase 是一个类似 **Supabase** 的 BaaS 平台，为 2C（个人开发者）和 2B（团队/企业）用户提供后端资源托管服务。权限系统采用 **RBAC + ABAC** 混合模型，支持三级权限体系：
|
|
|
|
|
|
- **平台级 (Platform)**: 用户管理自己的账号和数据
|
|
|
- **项目级 (Project)**: 项目内的成员管理和资源控制
|
|
|
- **资源级 (Resource)**: 具体资源的读写操作
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 核心概念
|
|
|
|
|
|
### 2.1 权限层级
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 平台级权限 (Platform) │
|
|
|
│ - 管理自己的用户信息 │
|
|
|
│ - 创建新项目 │
|
|
|
│ - 管理第三方账号绑定 │
|
|
|
│ - 访问被邀请的项目 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼ (进入项目上下文)
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 项目级权限 (Project) │
|
|
|
│ - 项目设置管理 (所有者/管理员) │
|
|
|
│ - 成员邀请和管理 │
|
|
|
│ - 资源创建和管理 │
|
|
|
│ - 查看项目统计信息 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼ (访问具体资源)
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 资源级权限 (Resource) │
|
|
|
│ - 数据库读写操作 │
|
|
|
│ - 存储文件上传下载 │
|
|
|
│ - 函数调用和管理 │
|
|
|
│ - API 密钥管理 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
### 2.2 实体关系
|
|
|
|
|
|
```
|
|
|
User (平台用户)
|
|
|
├── Platform Permission (平台级权限)
|
|
|
│ └── 默认: 管理自己的数据
|
|
|
│
|
|
|
└── OrgMember (项目成员关系)
|
|
|
├── Org/Project (项目)
|
|
|
│ ├── Resource (项目资源)
|
|
|
│ └── Resource (项目资源)
|
|
|
│
|
|
|
└── Role (项目角色)
|
|
|
└── Policy (策略)
|
|
|
```
|
|
|
|
|
|
### 2.3 使用场景示例
|
|
|
|
|
|
**场景1: 个人开发者 (2C)**
|
|
|
```
|
|
|
小明 (User)
|
|
|
├── 个人信息管理 (平台级)
|
|
|
├── 我的项目A (Org)
|
|
|
│ ├── 数据库资源
|
|
|
│ └── 存储资源
|
|
|
└── 我的项目B (Org)
|
|
|
└── ...
|
|
|
```
|
|
|
|
|
|
**场景2: 团队协作 (2B)**
|
|
|
```
|
|
|
CEO (User)
|
|
|
├── 拥有的项目: WebApp, MobileApp
|
|
|
└── 角色: 所有者 (Owner)
|
|
|
|
|
|
CTO (User)
|
|
|
├── 参与的项目: WebApp (Admin), MobileApp (Developer)
|
|
|
└── 角色: 管理员/开发者
|
|
|
|
|
|
员工A (User)
|
|
|
├── 参与的项目: WebApp (Developer)
|
|
|
└── 角色: 开发者
|
|
|
```
|
|
|
|
|
|
### 2.2 策略 (Policy)
|
|
|
|
|
|
策略是权限控制的最小单元，定义了对特定资源的操作权限。
|
|
|
|
|
|
**策略结构：**
|
|
|
|
|
|
```go
|
|
|
type Policy struct {
|
|
|
Code string // 策略编码，唯一标识
|
|
|
Name string // 策略名称
|
|
|
Description string // 策略描述
|
|
|
Resource string // 资源类型: user/org/member/policy/role/*
|
|
|
Action string // 操作: create/read/update/delete/*
|
|
|
Effect string // 效果: allow/deny
|
|
|
Condition string // 条件表达式
|
|
|
Priority int // 优先级: 数字越大优先级越高
|
|
|
IsSystem bool // 是否系统策略
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**策略分类：**
|
|
|
|
|
|
**平台级策略** (无 org_id 上下文)
|
|
|
| 策略 | 资源 | 操作 | 效果 | 条件 | 说明 |
|
|
|
|------|------|------|------|------|------|
|
|
|
| user:read:own | user | read | allow | owner | 读取自己的用户信息 |
|
|
|
| user:update:own | user | update | allow | owner | 更新自己的用户信息 |
|
|
|
| binding:manage | binding | * | allow | - | 管理第三方账号绑定 |
|
|
|
| org:create | org | create | allow | - | 创建新项目 |
|
|
|
|
|
|
**项目级策略** (需要 org_id 上下文)
|
|
|
| 策略 | 资源 | 操作 | 效果 | 条件 | 说明 |
|
|
|
|------|------|------|------|------|------|
|
|
|
| org:admin | * | * | allow | org_owner | 项目所有者拥有所有权限 |
|
|
|
| org:update | org | update | allow | admin | 更新项目设置 |
|
|
|
| member:read | member | read | allow | member | 读取项目成员列表 |
|
|
|
| member:manage | member | * | allow | admin | 管理项目成员 |
|
|
|
| resource:create | resource | create | allow | developer | 创建项目资源 |
|
|
|
| resource:delete | resource | delete | allow | admin | 删除项目资源 |
|
|
|
|
|
|
### 2.4 角色 (Role)
|
|
|
|
|
|
角色是一组策略的集合，在项目级别定义。
|
|
|
|
|
|
**角色结构：**
|
|
|
|
|
|
```go
|
|
|
type Role struct {
|
|
|
ID string // 角色ID
|
|
|
OrgID string // 所属项目
|
|
|
Name string // 角色名称
|
|
|
Description string // 角色描述
|
|
|
PolicyIDs []string // 关联的策略ID列表
|
|
|
Scope string // 作用域: project/resource
|
|
|
IsSystem bool // 是否系统角色
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**系统内置角色：**
|
|
|
|
|
|
| 角色 | 适用对象 | 权限范围 | 说明 |
|
|
|
|------|----------|----------|------|
|
|
|
| **owner** | 项目所有者 | 全部权限 | 项目的创建者，拥有所有权限，可删除项目 |
|
|
|
| **admin** | 管理员 | 项目级管理 | 管理项目设置、成员、资源，但不能删除项目 |
|
|
|
| **developer** | 开发者 | 资源级操作 | 创建和管理资源（数据库、存储、函数） |
|
|
|
| **viewer** | 访客 | 只读访问 | 只能查看项目和资源信息，不能修改 |
|
|
|
|
|
|
### 2.4 条件 (Condition)
|
|
|
|
|
|
条件用于实现 ABAC，支持以下类型：
|
|
|
|
|
|
| 条件 | 说明 | 使用场景 |
|
|
|
|------|------|----------|
|
|
|
| "" | 无条件，始终匹配 | 通用权限 |
|
|
|
| "owner" | 资源所有者 | 只能操作自己的数据 |
|
|
|
| "org_member" | 组织成员 | 组织内数据访问 |
|
|
|
| "org_owner" | 组织所有者 | 所有者权限判断 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 权限检查流程
|
|
|
|
|
|
### 3.1 流程图
|
|
|
|
|
|
```
|
|
|
┌─────────────────┐
|
|
|
│ 请求进入 │
|
|
|
│ user, org, │
|
|
|
│ resource, action│
|
|
|
└────────┬────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────┐ 命中 ┌─────────────────┐
|
|
|
│ 检查缓存 │────────────→│ 返回缓存结果 │
|
|
|
│ Redis │ │ allow/deny │
|
|
|
└────────┬────────┘ └─────────────────┘
|
|
|
│ 未命中
|
|
|
▼
|
|
|
┌─────────────────┐
|
|
|
│ 1. 检查组织所有者 │────────┐
|
|
|
└────────┬────────┘ │
|
|
|
│ 是 │
|
|
|
▼ │
|
|
|
┌──────────┐ │
|
|
|
│ 返回 Allow│────────────┘
|
|
|
└──────────┘
|
|
|
│ 否
|
|
|
▼
|
|
|
┌─────────────────┐
|
|
|
│ 2. 获取用户角色 │
|
|
|
│ 从 OrgMember │
|
|
|
│ 获取 role_ids │
|
|
|
└────────┬────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────┐
|
|
|
│ 3. 获取角色策略 │
|
|
|
│ 解析所有策略 │
|
|
|
│ 去重合并 │
|
|
|
└────────┬────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────┐
|
|
|
│ 4. 检查 Deny 策略│────────┐
|
|
|
│ 高优先级优先 │ │
|
|
|
└────────┬────────┘ │
|
|
|
│ 匹配 Deny │
|
|
|
▼ │
|
|
|
┌──────────┐ │
|
|
|
│返回 Deny │────────────┘
|
|
|
│ 缓存结果 │
|
|
|
└──────────┘
|
|
|
│ 无 Deny
|
|
|
▼
|
|
|
┌─────────────────┐
|
|
|
│ 5. 检查 Allow 策略│────────┐
|
|
|
└────────┬────────┘ │
|
|
|
│ 匹配 Allow │
|
|
|
▼ │
|
|
|
┌──────────┐ │
|
|
|
│返回 Allow│────────────┘
|
|
|
│ 缓存结果 │
|
|
|
└──────────┘
|
|
|
│ 无 Allow
|
|
|
▼
|
|
|
┌─────────────────┐
|
|
|
│ 6. 默认拒绝 │────────→ 返回 Deny
|
|
|
└─────────────────┘ 缓存结果
|
|
|
```
|
|
|
|
|
|
### 3.2 决策规则
|
|
|
|
|
|
1. **Deny 优先**: 如果匹配到 Deny 策略，直接拒绝
|
|
|
2. **显式 Allow**: 必须匹配到 Allow 策略才允许
|
|
|
3. **默认拒绝**: 未匹配到任何策略时拒绝
|
|
|
4. **优先级**: 高优先级策略优先匹配
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 使用指南
|
|
|
|
|
|
### 4.1 检查权限
|
|
|
|
|
|
**代码示例：**
|
|
|
|
|
|
```go
|
|
|
import "github.com/veypi/vbase/internal/service"
|
|
|
|
|
|
func SomeHandler(x *vigo.X) error {
|
|
|
userID := middleware.CurrentUser(x)
|
|
|
orgID := middleware.CurrentOrg(x)
|
|
|
|
|
|
checker := service.NewPermissionChecker()
|
|
|
result, err := checker.Check(userID, orgID, "user", "update", map[string]any{
|
|
|
"owner_id": targetUserID,
|
|
|
})
|
|
|
|
|
|
if err != nil || !result.Allowed {
|
|
|
return vigo.ErrForbidden.WithString(result.Reason)
|
|
|
}
|
|
|
|
|
|
// 继续处理...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 4.2 创建自定义策略
|
|
|
|
|
|
```go
|
|
|
policy := &model.Policy{
|
|
|
Code: "custom:resource:action",
|
|
|
Name: "自定义策略",
|
|
|
Description: "允许特定用户操作",
|
|
|
Resource: "resource_name",
|
|
|
Action: "action_name", // create/read/update/delete
|
|
|
Effect: model.EffectAllow,
|
|
|
Condition: "owner", // owner/org_member/空
|
|
|
Priority: 50,
|
|
|
}
|
|
|
|
|
|
model.DB.Create(policy)
|
|
|
```
|
|
|
|
|
|
### 4.3 创建角色并授权
|
|
|
|
|
|
```go
|
|
|
// 创建角色
|
|
|
role := &model.Role{
|
|
|
OrgID: orgID,
|
|
|
Name: "部门管理员",
|
|
|
Description: "管理部门成员",
|
|
|
PolicyIDs: "policy1,policy2,policy3",
|
|
|
}
|
|
|
model.DB.Create(role)
|
|
|
|
|
|
// 分配给用户
|
|
|
member := &model.OrgMember{
|
|
|
OrgID: orgID,
|
|
|
UserID: userID,
|
|
|
RoleIDs: role.ID,
|
|
|
}
|
|
|
model.DB.Create(member)
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 系统内置策略
|
|
|
|
|
|
### 5.1 用户相关
|
|
|
|
|
|
```go
|
|
|
// 读取自己
|
|
|
SysPolicyUserReadOwn = "sys:user:read:own"
|
|
|
Resource: "user"
|
|
|
Action: "read"
|
|
|
Condition: "owner"
|
|
|
|
|
|
// 更新自己
|
|
|
SysPolicyUserUpdateOwn = "sys:user:update:own"
|
|
|
Resource: "user"
|
|
|
Action: "update"
|
|
|
Condition: "owner"
|
|
|
|
|
|
// 删除自己
|
|
|
SysPolicyUserDeleteOwn = "sys:user:delete:own"
|
|
|
Resource: "user"
|
|
|
Action: "delete"
|
|
|
Condition: "owner"
|
|
|
```
|
|
|
|
|
|
### 5.2 组织相关
|
|
|
|
|
|
```go
|
|
|
// 组织管理员
|
|
|
SysPolicyOrgAdmin = "sys:org:admin"
|
|
|
Resource: "*"
|
|
|
Action: "*"
|
|
|
Condition: "org_owner"
|
|
|
Priority: 100
|
|
|
|
|
|
// 读取组织
|
|
|
SysPolicyOrgRead = "sys:org:read"
|
|
|
Resource: "org"
|
|
|
Action: "read"
|
|
|
Condition: "org_member"
|
|
|
```
|
|
|
|
|
|
### 5.3 成员相关
|
|
|
|
|
|
```go
|
|
|
// 读取成员
|
|
|
SysPolicyMemberRead = "sys:member:read"
|
|
|
Resource: "member"
|
|
|
Action: "read"
|
|
|
Condition: "org_member"
|
|
|
|
|
|
// 管理成员
|
|
|
SysPolicyMemberManage = "sys:member:manage"
|
|
|
Resource: "member"
|
|
|
Action: "*"
|
|
|
Condition: ""
|
|
|
```
|
|
|
|
|
|
### 5.4 角色策略相关
|
|
|
|
|
|
```go
|
|
|
// 读取角色
|
|
|
SysPolicyRoleRead = "sys:role:read"
|
|
|
Resource: "role"
|
|
|
Action: "read"
|
|
|
Condition: "org_member"
|
|
|
|
|
|
// 管理角色
|
|
|
SysPolicyRoleManage = "sys:role:manage"
|
|
|
Resource: "role"
|
|
|
Action: "*"
|
|
|
Condition: ""
|
|
|
|
|
|
// 读取策略
|
|
|
SysPolicyPolicyRead = "sys:policy:read"
|
|
|
Resource: "policy"
|
|
|
Action: "read"
|
|
|
Condition: ""
|
|
|
|
|
|
// 管理策略
|
|
|
SysPolicyPolicyManage = "sys:policy:manage"
|
|
|
Resource: "policy"
|
|
|
Action: "*"
|
|
|
Condition: ""
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 权限缓存
|
|
|
|
|
|
### 6.1 缓存机制
|
|
|
|
|
|
```
|
|
|
缓存键: perm:{user_id}:{org_id}:{resource}:{action}
|
|
|
TTL: 1分钟
|
|
|
值: "allow" 或 "deny"
|
|
|
```
|
|
|
|
|
|
### 6.2 缓存失效
|
|
|
|
|
|
以下操作会触发缓存清除：
|
|
|
|
|
|
- 用户角色变更
|
|
|
- 角色策略变更
|
|
|
- 策略内容变更
|
|
|
- 组织成员变更
|
|
|
|
|
|
```go
|
|
|
// 清除用户权限缓存
|
|
|
service.ClearUserPermissionCache(userID)
|
|
|
|
|
|
// 清除组织权限缓存
|
|
|
service.ClearOrgPermissionCache(orgID)
|
|
|
```
|
|
|
|
|
|
### 6.3 缓存命中率优化
|
|
|
|
|
|
- 权限变更频率低，1分钟 TTL 平衡了性能和实时性
|
|
|
- 批量操作时建议先清除缓存，操作完成后统一刷新
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. 最佳实践
|
|
|
|
|
|
### 7.1 策略设计
|
|
|
|
|
|
1. **最小权限原则**: 只授予完成任务所需的最小权限
|
|
|
2. **职责分离**: 敏感操作需要多个角色共同完成
|
|
|
3. **策略命名规范**: `{resource}:{action}:{condition}`
|
|
|
|
|
|
### 7.2 角色设计
|
|
|
|
|
|
```
|
|
|
组织层级角色体系:
|
|
|
├── owner (所有者)
|
|
|
│ └── 全部权限
|
|
|
├── admin (管理员)
|
|
|
│ └── 管理成员、角色、策略
|
|
|
├── manager (部门经理)
|
|
|
│ └── 管理部门成员
|
|
|
└── member (普通成员)
|
|
|
└── 基础访问权限
|
|
|
```
|
|
|
|
|
|
### 7.3 权限检查位置
|
|
|
|
|
|
**Controller 层检查:**
|
|
|
```go
|
|
|
func Handler(x *vigo.X) error {
|
|
|
// 先检查权限
|
|
|
if !hasPermission(x, "resource", "action") {
|
|
|
return vigo.ErrForbidden
|
|
|
}
|
|
|
// 执行业务逻辑
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Service 层检查（数据级）:**
|
|
|
```go
|
|
|
func UpdateUser(userID string, data map[string]any) error {
|
|
|
// 检查是否是本人或管理员
|
|
|
if !isOwner(userID) && !hasAdminRole() {
|
|
|
return ErrForbidden
|
|
|
}
|
|
|
// 执行更新
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 7.4 权限测试
|
|
|
|
|
|
```go
|
|
|
func TestPermissionCheck(t *testing.T) {
|
|
|
tests := []struct {
|
|
|
name string
|
|
|
userID string
|
|
|
orgID string
|
|
|
resource string
|
|
|
action string
|
|
|
data map[string]any
|
|
|
want bool
|
|
|
}{
|
|
|
{
|
|
|
name: "owner can update own profile",
|
|
|
userID: "user1",
|
|
|
orgID: "",
|
|
|
resource: "user",
|
|
|
action: "update",
|
|
|
data: map[string]any{"owner_id": "user1"},
|
|
|
want: true,
|
|
|
},
|
|
|
{
|
|
|
name: "user cannot update others profile",
|
|
|
userID: "user1",
|
|
|
orgID: "",
|
|
|
resource: "user",
|
|
|
action: "update",
|
|
|
data: map[string]any{"owner_id": "user2"},
|
|
|
want: false,
|
|
|
},
|
|
|
}
|
|
|
|
|
|
checker := service.NewPermissionChecker()
|
|
|
for _, tt := range tests {
|
|
|
t.Run(tt.name, func(t *testing.T) {
|
|
|
result, _ := checker.Check(tt.userID, tt.orgID, tt.resource, tt.action, tt.data)
|
|
|
if result.Allowed != tt.want {
|
|
|
t.Errorf("Check() = %v, want %v", result.Allowed, tt.want)
|
|
|
}
|
|
|
})
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 8. 故障排查
|
|
|
|
|
|
### 8.1 权限检查失败
|
|
|
|
|
|
**检查步骤：**
|
|
|
|
|
|
1. 确认用户已登录
|
|
|
2. 确认用户是组织成员
|
|
|
3. 检查用户角色
|
|
|
4. 检查角色绑定的策略
|
|
|
5. 检查策略的 Effect 和 Condition
|
|
|
|
|
|
**调试日志：**
|
|
|
|
|
|
```go
|
|
|
// 开启调试日志
|
|
|
checker := service.NewPermissionChecker()
|
|
|
result, err := checker.Check(userID, orgID, resource, action, data)
|
|
|
log.Printf("Permission check: user=%s, resource=%s, action=%s, allowed=%v, reason=%s",
|
|
|
userID, resource, action, result.Allowed, result.Reason)
|
|
|
```
|
|
|
|
|
|
### 8.2 缓存问题
|
|
|
|
|
|
```bash
|
|
|
# 清除 Redis 权限缓存
|
|
|
redis-cli KEYS "perm:*" | xargs redis-cli DEL
|
|
|
|
|
|
# 或重启应用（开发环境）
|
|
|
```
|
|
|
|
|
|
### 8.3 权限不生效
|
|
|
|
|
|
1. 检查策略是否保存成功
|
|
|
2. 检查角色是否正确绑定策略
|
|
|
3. 检查用户是否正确分配角色
|
|
|
4. 检查缓存是否已清除
|
|
|
|
|
|
---
|
|
|
|
|
|
## 9. 扩展开发
|
|
|
|
|
|
### 9.1 添加自定义条件
|
|
|
|
|
|
```go
|
|
|
// 在 permission.go 中扩展 evaluateCondition
|
|
|
func (pc *PermissionChecker) evaluateCondition(p *model.Policy, userID, orgID string, resourceData map[string]any) bool {
|
|
|
switch p.Condition {
|
|
|
case "owner":
|
|
|
// 现有逻辑...
|
|
|
case "custom_condition":
|
|
|
// 自定义条件逻辑
|
|
|
return checkCustomCondition(userID, orgID, resourceData)
|
|
|
default:
|
|
|
return true
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 9.2 添加资源类型
|
|
|
|
|
|
```go
|
|
|
// 在 policy.go 中添加资源常量
|
|
|
const (
|
|
|
ResourceUser = "user"
|
|
|
ResourceOrg = "org"
|
|
|
ResourceMember = "member"
|
|
|
ResourceCustom = "custom_resource" // 新增
|
|
|
)
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 10. 参考
|
|
|
|
|
|
- [RBAC 模型](https://en.wikipedia.org/wiki/Role-based_access_control)
|
|
|
- [ABAC 模型](https://en.wikipedia.org/wiki/Attribute-based_access_control)
|
|
|
- [NIST RBAC 标准](https://csrc.nist.gov/projects/role-based-access-control)
|