RAGFlow 0.25.6 独立权限代理服务设计

01设计目标与约束

在不触碰 RAGFlow 任何一张表、任何一行业务逻辑的前提下，外挂一个独立的权限代理服务，把企业级的细粒度权限模型「翻译」成 RAGFlow 能理解的原生原语。

02RAGFlow 原生权限模型源码分析

先把 RAGFlow 现状摸清——这是「不改原逻辑」的前提。以下均为 0.25.6 实际源码。

2.1 角色枚举：仅租户级四角色

class UserTenantRole(StrEnum):
    OWNER  = 'owner'    # 租户所有者（创建者）
    ADMIN  = 'admin'    # 租户管理员
    NORMAL = 'normal'   # 普通成员
    INVITE = 'invite'   # 已邀请未接受

class TenantPermission(StrEnum):
    ME   = 'me'         # 仅自己可见
    TEAM = 'team'       # 团队可见

2.2 数据表：权限相关字段

permission = CharField(max_length=16, null=False, help_text="me|team",
                       default="me", index=True)   # ← 知识库可见性，仅二态

2.3 知识库可见性的实际判定逻辑

这是 RAGFlow 决定「谁能看到哪个 KB」的全部逻辑——只有两条规则：① 是我建的；② 团队共享且我在该租户里。

# 列表过滤（构造 Peewee 查询条件）
def _visibility_and_status_filter(cls, joined_tenant_ids, user_id):
    return (
        ( (cls.model.tenant_id.in_(joined_tenant_ids)
              & (cls.model.permission == TenantPermission.TEAM.value))   # 团队共享
          | (cls.model.tenant_id == user_id) )                          # 自己的工作区
        & (cls.model.status == StatusEnum.VALID.value)
    )

# 单个 KB 访问判定
def accessible(cls, kb_id, user_id):
    e, kb = cls.get_by_id(kb_id)
    if kb.tenant_id == user_id:                  return True   # 创建者
    if kb.permission != TenantPermission.TEAM.value: return False
    joined = TenantService.get_joined_tenants_by_user_id(user_id)
    return any(t["tenant_id"] == kb.tenant_id for t in joined)  # 同团队 + team 可见

2.4 鉴权入口：双令牌加载

RAGFlow 所有请求经 _load_user 解析身份，它同时支持 JWT(access_token) 和 APIToken 两条路径——这是代理服务最理想的「挂载缝隙」。

def _load_user():
    authorization = request.headers.get("Authorization")
    # 路径①：JWT 解出 access_token → 查 user 表
    access_token = str(jwt.loads(auth_token))
    user = UserService.query(access_token=access_token, status=VALID)
    ...
    # 路径②：当作 APIToken → 用 tenant_id 反查 user（系统应用走这里）
    objs = APIToken.query(token=auth_token)
    user = UserService.query(id=objs[0].tenant_id, status=VALID)
    g.auth_via_api_token = True

2.5 唯一的原生配额：环境变量级文件数上限

MAX_FILE_NUM_PER_USER = int(os.environ.get("MAX_FILE_NUM_PER_USER", 0))
if 0 < MAX_FILE_NUM_PER_USER <= DocumentService.get_doc_count(tenant_id):
    raise RuntimeError("Exceed the maximum file number of a free user!")

全局一刀切，无法按角色/机构/KB 分级——配额管控需要在代理层重做。

03差距分析：原生能力 vs 需求

04总体架构：代理服务的位置

代理服务作为反向代理 + 策略决策点（PDP/PEP）置于客户端与 RAGFlow 之间。所有流量先过代理，鉴权/配额/审批判定后再转发给原生 RAGFlow。

┌────────────┐   ①携带代理签发的Token    ┌──────────────────────────────┐
│  前端 / SDK │ ─────────────────────────► │   权限代理服务 (Auth Proxy)    │
│  系统应用   │                            │  ┌────────────────────────┐  │
└────────────┘                            │  │ PEP 拦截器 (Gateway)    │  │
                                          │  │  · 身份认证             │  │
       ┌──────────────────────────────┐  │  │  · 五级RBAC判定         │  │
       │   独立权限数据库 (proxy_db)    │◄─┤  │  · KB四模式ACL判定      │  │
       │  role / org / kb_acl          │  │  │  · 配额/频率校验        │  │
       │  quota / approval / audit_log │  │  │  · 模型白名单           │  │
       └──────────────────────────────┘  │  │  · 版本审批闸门         │  │
                                          │  └───────────┬────────────┘  │
                                          └──────────────┼───────────────┘
                                          ②注入RAGFlow原生Token, 透传
                                                         ▼
                                          ┌──────────────────────────────┐
                                          │   RAGFlow 0.25.6 (原封不动)    │
                                          │   api/apps/*  +  原数据库      │
                                          └──────────────────────────────┘

05五级角色体系设计

在代理层定义五级角色，每级是上一级权限的子集。角色存于代理库，与 RAGFlow 的 owner/normal 解耦。

5.1 角色 → RAGFlow 原生身份映射表

06知识库四种访问控制模式

代理在 RAGFlow 的 me|team 二态之上，叠加四种语义化模式。每次 KB 访问由代理先算「有效可见集」，再决定是否转发。

★ 模式②③的关键技巧见下方 6.2「动态授权」。

6.1 有效可见集计算（代理 PDP 伪代码）

def visible_kb_ids(subject):
    ids = set()
    # ① 创建者
    ids |= proxy_db.kb.where(created_by == subject.user_id)
    # ② 机构自动共享：主体所属机构(含上级分行/总行继承)绑定的 KB
    org_ids = org_tree.ancestors_and_self(subject.org_id)   # 支行→分行→总行
    ids |= proxy_db.kb_share.where(mode=='ORG', org_id in org_ids)
    # ③ 指定用户共享
    ids |= proxy_db.kb_acl.where(user_id == subject.user_id)
    # ④ 团队共享（直接信任 RAGFlow 原生 team）
    ids |= proxy_db.kb.where(mode=='TEAM', tenant_id in subject.joined_tenants)
    return ids - revoked(subject)        # 减去已撤销/审批未通过

6.2 模式②③如何在「不改 team 广播」下实现精准共享

方案：KB 保持 permission=me（归属"机构服务账号"租户），代理用 Token Broker 动态代理访问。

07配额管控设计

四类配额均在代理 PEP 层「请求前置」校验，超限直接拒绝，不转发。计数维度可按用户/机构/系统应用配置。

7.1 配额校验流程

def enforce_quota(subject, action, payload):
    q = proxy_db.quota_policy.resolve(subject)     # 角色/机构/个体逐级覆盖
    match action:
      case "kb.create":
          assert proxy_db.count_kb(subject) < q.max_kb,            DENY(403)
      case "doc.upload":
          assert proxy_db.count_doc(subject) + payload.n <= q.max_doc, DENY(403)
          assert payload.size <= q.max_file_size,                  DENY(413)
      case "api.call":
          assert rate_limiter.allow(subject.id, q.qps),            DENY(429)
      case "chat.completion":
          assert payload.model in q.model_whitelist,               DENY(403)
    return ALLOW

08版本审批流程

面向金融合规——KB 内容发布须经审批留痕。代理维护版本状态机；只有「已发布」版本对检索用户/系统应用可见。

8.1 状态机与角色权限

8.2 「发布闸门」如何在不改 RAGFlow 下生效

方案：双 KB 影子机制（草稿 KB / 发布 KB）。

09代理服务表结构（独立库）

全部新增表落在 proxy_db，与 RAGFlow 库物理隔离。仅通过 ragflow_user_id / ragflow_kb_id 等外部主键引用原生实体，不加任何外键约束到 RAGFlow。

10请求拦截与鉴权流程

单个请求在代理内的完整生命周期——这是整套设计的执行主干。

11映射策略：如何落到原生 me|team

把细粒度模型「投影」到 RAGFlow 二态权限的完整对照——这是「零侵入」成立的技术保证。

12实施路线图