🚀 RAGFlow 知识库权限系统扩展设计

一、原始表结构分析

基于 api/db/db_models.py 中 Peewee ORM 模型提取的核心表结构。

1.1 核心实体关系概览

┌──────────────┐       ┌──────────────────┐       ┌──────────────┐
│    User      │       │   UserTenant     │       │   Tenant     │
├──────────────┤       ├──────────────────┤       ├──────────────┤
│ id (PK)      │──1:N──│ user_id (FK)     │──N:1──│ id (PK)      │
│ access_token │       │ tenant_id (FK)   │       │ name         │
│ nickname     │       │ role: owner|     │       │ llm_id       │
│ email        │       │   admin|normal|  │       │ embd_id      │
│ password     │       │   invite         │       │ credit       │
│ is_superuser │       │ invited_by       │       │ status       │
│ status       │       │ status           │       │ ...          │
└──────────────┘       └──────────────────┘       └──────┬───────┘
                                                          │
                     ┌────────────────────────────────────┤
                     │ 1:N                                │ 1:N
                     ▼                                    ▼
          ┌──────────────────┐              ┌──────────────────────┐
          │  Knowledgebase   │              │      Dialog          │
          ├──────────────────┤              ├──────────────────────┤
          │ id (PK)          │              │ id (PK)              │
          │ tenant_id (FK)   │              │ tenant_id (FK)       │
          │ name             │              │ name                 │
          │ permission:      │              │ kb_ids (JSON) ───────│── 引用多个 KB
          │   me | team      │◄─────────────│ llm_setting          │
          │ created_by       │              │ prompt_config        │
          │ embd_id          │              │ ...                  │
          │ parser_id        │              └──────────────────────┘
          │ doc_num          │
          │ status           │
          └───────┬──────────┘
                  │ 1:N
                  ▼
          ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
          │   Document   │     │    File      │     │    Task      │
          ├──────────────┤     ├──────────────┤     ├──────────────┤
          │ id (PK)      │     │ id (PK)      │     │ id (PK)      │
          │ kb_id (FK)   │     │ parent_id    │     │ doc_id (FK)  │
          │ parser_id    │     │ tenant_id    │     │ task_type    │
          │ name         │     │ name         │     │ progress     │
          │ size         │     │ size         │     │ ...          │
          │ token_num    │     │ type         │     └──────────────┘
          │ chunk_num    │     └──────────────┘
          │ status       │
          └──────────────┘

1.2 用户与租户相关表

1.3 知识库与文档相关表

1.4 应用相关表（Dialog / Search / Agent）

1.5 Token 与会话表

1.6 其余辅助表

二、现有权限模型分析

当前 RAGFlow 的权限控制粒度及其局限性。

2.1 现有权限层级

2.2 关键权限检查代码路径

知识库列表可见性过滤

# api/db/services/knowledgebase_service.py - _visibility_and_status_filter
def _visibility_and_status_filter(cls, joined_tenant_ids, user_id):
    return (
        (
            # Team KBs: 租户内所有成员可见
            (cls.model.tenant_id.in_(joined_tenant_ids)
             & (cls.model.permission == 'team'))
            # 或 KB 创建者自己
            | (cls.model.tenant_id == user_id)
        )
        & (cls.model.status == StatusEnum.VALID.value)
    )

知识库访问检查

# api/db/services/knowledgebase_service.py - accessible
def accessible(cls, kb_id, user_id):
    e, kb = cls.get_by_id(kb_id)
    if not e: return False
    if kb.status != StatusEnum.VALID.value: return False
    # 创建者始终可访问
    if kb.tenant_id == user_id: return True
    # 仅 Team KB 允许同租户成员访问
    if kb.permission != 'team': return False
    joined_tenants = TenantService.get_joined_tenants_by_user_id(user_id)
    return any(tenant["tenant_id"] == kb.tenant_id
               for tenant in joined_tenants)

删除权限检查

# api/db/services/knowledgebase_service.py - accessible4deletion
def accessible4deletion(cls, kb_id, user_id):
    # 仅 KB 创建者可以删除
    docs = cls.model.select(cls.model.id).where(
        cls.model.id == kb_id,
        cls.model.created_by == user_id
    ).paginate(0, 1)
    return bool(list(docs.dicts()))

2.3 Dialog 与 KB 关联方式

# Dialog 通过 JSON 字段直接引用 KB IDs，没有任何权限校验中间层
# api/db/db_models.py - Dialog
class Dialog(DataBaseModel):
    kb_ids = JSONField(null=False, default=[])  # 直接存 KB ID 列表

这意味着：一旦 Dialog 配置了某个 KB 的 ID，所有使用该 Dialog 的用户都可以通过它检索该 KB 的内容。没有对 谁能用哪个 Dialog 访问哪个 KB 的精细化控制。

三、需求与差距分析

目标权限能力 vs 现状能力矩阵。

核心用例场景

四、扩展设计总体方案

采用 RBAC（基于角色的访问控制）+ ABAC（基于属性的访问控制）混合模型，分层设计。

4.1 设计原则

4.2 扩展架构总览

                    ┌──────────────────────────────────────────────────────┐
                    │              ★ 新增层: 权限控制中心 ★                 │
                    └──────────────────────────────────────────────────────┘

 ┌──────────────┐    ┌─────────────────┐    ┌──────────────────────┐
 │  user_group  │    │     role        │    │  role_permission     │
 ├──────────────┤    ├─────────────────┤    ├──────────────────────┤
 │ id (PK)      │    │ id (PK)         │    │ id (PK)              │
 │ tenant_id    │    │ tenant_id       │    │ role_id (FK)         │
 │ name         │    │ name            │    │ resource_type        │
 │ description  │    │ description     │    │ permission           │
 │ created_by   │    │ is_system       │    │ effect: allow|deny   │
 │ status       │    │ parent_role_id  │    │ conditions (JSON)    │
 └──────┬───────┘    │ status          │    └──────────┬───────────┘
        │ N:M        └────────┬────────┘               │ N:1
        ▼                     │                        │
 ┌──────────────┐             │                        │
 │user_group_   │             │                        │
 │  member      │             │                        │
 ├──────────────┤             │                        │
 │ group_id(FK) │             │                        │
 │ user_id (FK) │             │                        │
 └──────────────┘             │                        │
                              ▼                        ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │                        kb_permission                                   │
 ├────────────────────────────────────────────────────────────────────────┤
 │ id (PK), kb_id (FK), grantee_type, grantee_id, role_id (FK)           │
 │ operations (JSON), data_scope (JSON), effect: allow|deny              │
 │ expires_at, priority, created_by, status                              │
 └────────────────────────────────────────────────────────────────────────┘

 ┌────────────────────────────────────────────────────────────────────────┐
 │                        kb_rate_limit                                   │
 ├────────────────────────────────────────────────────────────────────────┤
 │ id (PK), kb_id (FK), scope_type, scope_id, limit_type                │
 │ max_qps, max_tokens_per_day, max_concurrent, max_requests_per_day     │
 │ window_seconds, enabled, status                                       │
 └────────────────────────────────────────────────────────────────────────┘

 ┌────────────────────────────────────────────────────────────────────────┐
 │                        app_kb_binding                                  │
 ├────────────────────────────────────────────────────────────────────────┤
 │ id (PK), app_type, app_id, kb_id (FK)                                │
 │ operations (JSON), rate_limit_id (FK)                                │
 │ created_by, status                                                    │
 └────────────────────────────────────────────────────────────────────────┘

 ┌────────────────────────────────────────────────────────────────────────┐
 │                        kb_audit_log                                    │
 ├────────────────────────────────────────────────────────────────────────┤
 │ id (PK), kb_id, user_id, app_id, operation, resource                │
 │ result: allow|deny, reason, ip_address, user_agent                   │
 │ created_at                                                           │
 └────────────────────────────────────────────────────────────────────────┘

五、新增表详细设计

5.1 user_group — 用户组 NEW

支持将多个用户组织成组，方便批量授权。组内可包含用户和其他子组（通过 parent_group_id 实现嵌套）。

5.2 user_group_member — 组成员 NEW

5.3 role — 自定义角色 NEW

租户可定义自定义角色，配置一组权限。系统预设角色（admin/viewer/editor）不可删除。

5.4 role_permission — 角色权限定义 NEW

定义角色拥有的具体操作权限，支持条件表达式实现 ABAC。

操作权限码定义

5.5 kb_permission — 知识库权限策略 NEW ★核心表★

将角色与具体的知识库绑定，同时指定授权对象（用户/用户组/角色/应用），可设置数据范围和过期时间。

data_scope 数据范围示例

{
  "doc_ids": ["doc_001", "doc_002"],      // 仅限指定文档
  "exclude_doc_ids": ["doc_secret"],      // 排除特定文档
  "tags": ["public", "internal"],         // 文档标签过滤
  "meta_filter": {                          // 元数据过滤
    "security_level": ["l1", "l2"],
    "department": "engineering"
  },
  "max_token_per_query": 50000          // 单次查询最大 Token
}

5.6 kb_rate_limit — 知识库限流规则 NEW

限流规则优先级（从高到低）

1. token 级别（API Token 专属限流）
2. user 级别（用户专属限流）
3. app 级别（应用级限流）
4. group 级别（用户组限流）
5. kb 全局级别（知识库默认限流）
6. 租户全局级别

5.7 app_kb_binding — 应用-知识库绑定 NEW ★关键★

替代 Dialog 中 kb_ids JSON 字段的硬编码方式。应用必须先建立绑定关系才能检索知识库。

5.8 kb_audit_log — 审计日志 NEW

5.9 现有表字段改动

六、权限检查流程

6.1 权限检查入口——统一鉴权中间件

async def check_kb_permission(
    user_id: str,
    kb_id: str,
    operation: str,
    context: dict = {}   # {app_type, app_id, token_id, ...}
) -> PermissionResult:
    
    统一的知识库权限检查入口。
    返回 (allowed: bool, data_scope: dict, rate_limit: RateLimitConfig)
    """

    # Step 0: 超级管理员直接放行
    if is_superuser(user_id):
        return ALLOWED_WITH_FULL_SCOPE

    # Step 1: 检查知识库是否存在且有效
    kb = get_kb(kb_id)
    if not kb or kb.status != '1':
        return DENIED("KB not found or disabled")

    # Step 2: 快速模式 - me/team 权限（无 custom 配置时生效）
    if kb.permission != 'custom':
        return check_legacy_permission(kb, user_id, operation)

    # Step 3: Custom 模式 - 收集所有匹配的策略
    policies = collect_matching_policies(
        kb_id=kb_id,
        user_id=user_id,
        user_groups=get_user_groups(user_id),
        user_roles=get_user_roles(user_id, kb.tenant_id),
        app_type=context.get('app_type'),
        app_id=context.get('app_id'),
        token_id=context.get('token_id'),
        operation=operation,
    )

    # Step 4: 按优先级排序，deny 优先
    policies = sorted(policies, key=lambda p: (
        0 if p.effect == 'deny' else 1,  # deny 优先
        -p.priority                                    # 同类型内按优先级
    ))

    # Step 5: 评估第一条决定性策略
    for policy in policies:
        # ABAC 条件评估
        if policy.conditions and not evaluate_conditions(policy.conditions, context):
            continue

        if policy.effect == 'deny':
            return DENIED(f"Denied by policy {policy.id}")

        # allow 策略：合并数据范围
        data_scope = merge_data_scopes([
            p.data_scope for p in policies if p.effect == 'allow'
        ])

        # 获取对应的限流配置
        rate_limit = get_effective_rate_limit(kb_id, user_id, context)

        return ALLOWED(data_scope=data_scope, rate_limit=rate_limit)

    # Step 6: 无匹配策略 → 默认拒绝
    return DENIED("No matching permission policy")

6.2 策略匹配收集

def collect_matching_policies(kb_id, user_id, user_groups, user_roles,
                               app_type, app_id, token_id, operation):
    
    从 kb_permission 表查找所有可能匹配的策略。
    按授权对象类型分别匹配。
    """
    policies = []

    # 查询 kb_permission 表中该 KB 的所有有效策略
    all_kb_policies = KB_Permission.query(
        kb_id=kb_id,
        status='1',
        # 过滤已过期策略
        where_clause="(expires_at IS NULL OR expires_at > NOW())"
    )

    for policy in all_kb_policies:
        matched = False

        if policy.grantee_type == 'user' and policy.grantee_id == user_id:
            matched = True
        elif policy.grantee_type == 'group' and policy.grantee_id in user_groups:
            matched = True
        elif policy.grantee_type == 'role' and policy.grantee_id in user_roles:
            matched = True
        elif policy.grantee_type == 'app' and f"{app_type}:{app_id}" == policy.grantee_id:
            matched = True
        elif policy.grantee_type == 'token' and policy.grantee_id == token_id:
            matched = True

        if matched:
            # 如果策略关联了 role，从 role_permission 加载具体权限
            if policy.role_id:
                role_ops = get_role_permissions(policy.role_id, 'knowledgebase')
                if operation in role_ops['permissions']:
                    policies.append(policy)
            elif policy.operations and operation in policy.operations:
                policies.append(policy)

    return policies

6.3 限流检查流程

def check_rate_limit(kb_id, user_id, scope_type, scope_id) -> bool:
    
    检查当前请求是否超过限流阈值。
    使用 Redis 滑动窗口实现。
    """
    # 获取所有匹配的限流规则（从最特化到最通用）
    rules = get_rate_limit_rules(kb_id, scope_type, scope_id)

    for rule in rules:
        if not rule.enabled:
            continue

        # Redis 滑动窗口 Key
        window_key = f"ratelimit:{rule.id}:{scope_id}"

        if rule.limit_type == 'qps':
            current = redis_incr_window(window_key, rule.window_seconds)
            if current > rule.max_qps * rule.burst_multiplier:
                return False  # 限流触发

        elif rule.limit_type == 'tokens_per_day':
            day_key = f"ratelimit:{rule.id}:{scope_id}:tokens:{today()}"
            current = redis_get(day_key) or 0
            if current > rule.max_tokens_per_day:
                return False

        # ... 其他限流类型类似

    return True  # 未触发限流

七、迁移与兼容性策略

7.1 向后兼容保障

7.2 迁移步骤

7.3 Peewee 模型代码示例

# 新增模型定义（添加到 api/db/db_models.py）

class UserGroup(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    tenant_id = CharField(max_length=32, null=False, index=True)
    name = CharField(max_length=128, null=False, index=True)
    description = TextField(null=True)
    parent_group_id = CharField(max_length=32, null=True, index=True)
    created_by = CharField(max_length=32, null=False, index=True)
    status = CharField(max_length=1, null=True, default="1", index=True)

    class Meta:
        db_table = "user_group"
        indexes = (
            (("tenant_id", "name"), True),  # UNIQUE
        )

class UserGroupMember(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    group_id = CharField(max_length=32, null=False, index=True)
    user_id = CharField(max_length=32, null=False, index=True)
    status = CharField(max_length=1, null=True, default="1", index=True)

    class Meta:
        db_table = "user_group_member"
        indexes = (
            (("group_id", "user_id"), True),
        )

class Role(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    tenant_id = CharField(max_length=32, null=False, index=True)
    name = CharField(max_length=128, null=False, index=True)
    description = TextField(null=True)
    is_system = BooleanField(null=False, default=False)
    parent_role_id = CharField(max_length=32, null=True, index=True)
    created_by = CharField(max_length=32, null=False, index=True)
    status = CharField(max_length=1, null=True, default="1", index=True)

    class Meta:
        db_table = "role"
        indexes = (
            (("tenant_id", "name"), True),
        )

class RolePermission(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    role_id = CharField(max_length=32, null=False, index=True)
    resource_type = CharField(max_length=32, null=False, index=True)
    permission = CharField(max_length=64, null=False, index=True)
    effect = CharField(max_length=8, null=False, default="allow")
    conditions = JSONField(null=True, default={})

    class Meta:
        db_table = "role_permission"

class KBPermission(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    kb_id = CharField(max_length=32, null=False, index=True)
    grantee_type = CharField(max_length=16, null=False, index=True)
    grantee_id = CharField(max_length=32, null=False, index=True)
    role_id = CharField(max_length=32, null=True, index=True)
    operations = JSONField(null=True, default=[])
    data_scope = JSONField(null=True, default={})
    effect = CharField(max_length=8, null=False, default="allow")
    priority = IntegerField(null=False, default=0)
    expires_at = DateTimeField(null=True, index=True)
    created_by = CharField(max_length=32, null=False, index=True)
    status = CharField(max_length=1, null=True, default="1", index=True)

    class Meta:
        db_table = "kb_permission"

class KBRateLimit(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    kb_id = CharField(max_length=32, null=True, index=True)
    name = CharField(max_length=128, null=False)
    scope_type = CharField(max_length=16, null=False, default="global", index=True)
    scope_id = CharField(max_length=32, null=True, index=True)
    limit_type = CharField(max_length=32, null=False, default="qps")
    max_qps = FloatField(null=True)
    max_tokens_per_day = BigIntegerField(null=True)
    max_requests_per_day = IntegerField(null=True)
    max_concurrent = IntegerField(null=True)
    max_tokens_per_request = IntegerField(null=True)
    window_seconds = IntegerField(null=False, default=1)
    burst_multiplier = FloatField(null=False, default=1.0)
    throttle_action = CharField(max_length=16, null=False, default="reject")
    enabled = BooleanField(null=False, default=True)
    created_by = CharField(max_length=32, null=False, index=True)
    status = CharField(max_length=1, null=True, default="1", index=True)

    class Meta:
        db_table = "kb_rate_limit"

class AppKBBinding(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    app_type = CharField(max_length=16, null=False, index=True)
    app_id = CharField(max_length=32, null=False, index=True)
    kb_id = CharField(max_length=32, null=False, index=True)
    operations = JSONField(null=True, default=["kb:retrieve"])
    rate_limit_id = CharField(max_length=32, null=True, index=True)
    data_scope = JSONField(null=True, default={})
    created_by = CharField(max_length=32, null=False, index=True)
    status = CharField(max_length=1, null=True, default="1", index=True)

    class Meta:
        db_table = "app_kb_binding"
        indexes = (
            (("app_type", "app_id", "kb_id"), True),
        )

class KBAuditLog(DataBaseModel):
    id = CharField(max_length=32, primary_key=True)
    tenant_id = CharField(max_length=32, null=False, index=True)
    kb_id = CharField(max_length=32, null=True, index=True)
    user_id = CharField(max_length=32, null=True, index=True)
    app_id = CharField(max_length=32, null=True, index=True)
    app_type = CharField(max_length=16, null=True)
    operation = CharField(max_length=64, null=False, index=True)
    resource = CharField(max_length=255, null=True)
    detail = JSONField(null=True, default={})
    result = CharField(max_length=8, null=False, index=True)
    reason = CharField(max_length=255, null=True)
    ip_address = CharField(max_length=45, null=True)
    user_agent = CharField(max_length=512, null=True)
    latency_ms = IntegerField(null=True)
    token_used = IntegerField(null=True)
    created_at = DateTimeField(null=False, index=True, default=datetime.now)

    class Meta:
        db_table = "kb_audit_log"

八、实施路线图

8.1 分阶段计划

8.2 系统预设角色

8.3 性能考量

8.4 关键设计决策总结