11.4 · 访问控制与 RBAC（Access Control and RBAC）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节11.4 状态全文译文模块工具、记忆与模型调用、界面与交互、认证、权限与安全、接口与服务契约

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节Access Control and RBAC 上一章11.3 下一章11.5

源码线索

backend/open_webui/functions.py
backend/open_webui/migrations/versions/b2c3d4e5f6a7_add_scim_column_to_user_table.py
backend/open_webui/migrations/versions/c1d2e3f4a5b6_add_shared_chat_table.py
backend/open_webui/models/auths.py
backend/open_webui/models/groups.py
backend/open_webui/models/shared_chats.py
backend/open_webui/models/users.py
backend/open_webui/routers/groups.py
backend/open_webui/routers/scim.py
backend/open_webui/routers/users.py

模块标签

工具、记忆与模型调用
界面与交互
认证、权限与安全
接口与服务契约
可观测性与治理

中文译文

访问控制与 RBAC（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/11.4-access-control-and-rbac

翻译时间：2026-06-09T16:10:39.496Z

翻译模型：deepseek-chat

原文字符数：10880

项目：Open WebUI (open-webui)

---

访问控制与基于角色的访问控制（RBAC）

用户角色

Open WebUI 实现了一套角色系统，用于控制对管理功能和系统特性的访问。

角色定义

角色	描述	访问级别
`admin`	完全系统访问权限	可访问所有端点、管理用户、配置系统设置。
`user`	标准已验证用户	可使用聊天功能、访问允许的模型、管理个人设置。
`pending`	未验证用户	新注册用户的默认状态；等待管理员批准，访问受限或无访问权限。

用户由 SQLAlchemy 模型 User 和 Pydantic 模型 UserModel 表示 backend/open_webui/models/users.py:41-105。

角色分配与保护

系统使用 FastAPI 依赖项在端点级别强制实施角色要求 backend/open_webui/utils/auth.py:400-415。

标题：用户角色验证流程

graph TD
    Request["HTTP 请求"] --> Auth["get_current_user()<br/>auth.py:269"]
    Auth --> RoleCheck{检查用户角色}

    RoleCheck -->|"Depends(get_admin_user)"| AdminOnly["验证 role == 'admin'<br/>auth.py:409"]
    RoleCheck -->|"Depends(get_verified_user)"| VerifiedOnly["验证 role in ['user', 'admin']<br/>auth.py:400"]

    AdminOnly -->|"成功"| AdminEndpoint["仅管理员路由器<br/>(例如 /api/v1/users)"]
    VerifiedOnly -->|"成功"| UserEndpoint["标准路由器<br/>(例如 /api/v1/chats)"]

    AdminOnly -->|"失败"| Reject401["HTTP 401 未授权"]
    VerifiedOnly -->|"失败"| Reject401

来源：backend/open_webui/utils/auth.py:400-415，backend/open_webui/models/users.py:41-105

---

细粒度权限系统

除了静态角色外，Open WebUI 还提供了在 UserPermissions 中定义的细粒度权限系统 backend/open_webui/routers/users.py:244-250。

权限类别

权限组织为多个子模型：

工作区：访问模型、知识库、提示词、工具和技能 backend/open_webui/routers/users.py:169-181。
共享：共享资源并使其公开的能力 backend/open_webui/routers/users.py:184-197。
访问授权：控制用户是否可以向其他用户授予访问权限 backend/open_webui/routers/users.py:198-201。
聊天：控制 UI 元素，如文件上传、消息编辑和模型参数 backend/open_webui/routers/users.py:202-223。
特性：访问 API 密钥、网络搜索、图像生成和代码执行 backend/open_webui/routers/users.py:225-237。
设置：控制对界面设置的访问 backend/open_webui/routers/users.py:239-240。

实现逻辑

函数 has_permission 检查特定权限键是否对用户启用 backend/open_webui/utils/access_control/__init__.py。管理员可以通过 /default/permissions 端点为所有新用户配置默认权限 backend/open_webui/routers/users.py:252-272。

来源：backend/open_webui/routers/users.py:169-250，backend/open_webui/utils/access_control/__init__.py

---

组管理

组允许管理员组织用户并批量应用权限或资源访问（如工具或知识库）。

组数据模型

组通过 Group 表管理 backend/open_webui/models/groups.py:33-49，成员关系在 GroupMember 中跟踪 backend/open_webui/models/groups.py:69-80。

实体	代码标识符	描述
组表	`Group`	存储组元数据、名称和特定权限。
组成员	`GroupMember`	连接表，将 `user.id` 链接到 `group.id`。
组逻辑	`GroupTable`	包含 `insert_new_group` 和 `get_groups_by_member_id` 等方法。

组访问控制流程

当用户尝试访问受限资源时，系统通过 Groups 模型检查基于组的访问 backend/open_webui/models/groups.py:181-221。

标题：组访问解析

graph TD
    User["UserModel"] --> MemberOf["Groups.get_groups_by_member_id()"]
    MemberOf --> GroupIDs["组 ID 列表"]

    Resource["资源（模型/知识库）"] --> AccessCheck["check_model_access()"]

    GroupIDs --> AccessCheck
    User --> AccessCheck

    AccessCheck --> Result{有访问权限？}
    Result -->|"是"| Allow["授予访问权限"]
    Result -->|"否"| Deny["HTTP 403 禁止访问"]

来源：backend/open_webui/models/groups.py:33-80，backend/open_webui/models/groups.py:181-221，backend/open_webui/utils/models.py:25-26

---

访问授权

AccessGrants 系统提供了一种统一的方式来管理跨用户和组对特定资源（工具、模型、知识库）的权限。

资源权限检查

系统使用 has_access 来验证用户是否对特定资源拥有“读取”或“写入”权限 backend/open_webui/utils/access_control/__init__.py。如果启用了 BYPASS_ADMIN_ACCESS_CONTROL，管理员用户可以绕过这些检查 backend/open_webui/config.py:29-31。

标题：访问授权逻辑流程

graph TD
    UserRequest["用户请求资源"] --> CheckAdminBypass{启用了 BYPASS_ADMIN_ACCESS_CONTROL 且用户是管理员？}
    CheckAdminBypass -->|"是"| GrantAccess["访问已授予（管理员绕过）"]
    CheckAdminBypass -->|"否"| GetUserGroups["Groups.get_groups_by_member_id(user.id)"]
    GetUserGroups --> GetResourceAccessGrants["AccessGrants.get_access_grants_by_resource_id()"]
    GetResourceAccessGrants --> AccessDecision{访问已授予？}
    AccessDecision -->|"是"| GrantAccess
    AccessDecision -->|"否"| DenyAccess["访问被拒绝"]

来源：backend/open_webui/models/access_grants.py:17-18，backend/open_webui/utils/models.py:25-26，backend/open_webui/config.py:29-31

---

SCIM 2.0 预置（实验性）

Open WebUI 包含一个实验性的跨域身份管理系统（SCIM）2.0 协议实现，用于自动用户和组预置 backend/open_webui/routers/scim.py:1-6。

SCIM 端点

SCIM 路由器为身份提供商（IdP）提供标准端点：

用户：GET /Users，POST /Users，PATCH /Users/{id}，DELETE /Users/{id} backend/open_webui/routers/scim.py:270-550。
组：GET /Groups，POST /Groups，PATCH /Groups/{id}，DELETE /Groups/{id} backend/open_webui/routers/scim.py:553-850。

身份验证与模式

SCIM 请求通过专用的 Bearer Token 检查 get_scim_auth 进行身份验证 backend/open_webui/routers/scim.py:235-268。该实现将 SCIM 模式映射到内部模型：

urn:ietf:params:scim:schemas:core:2.0:User 映射到 UserModel backend/open_webui/routers/scim.py:128-144。
urn:ietf:params:scim:schemas:core:2.0:Group 映射到 GroupModel backend/open_webui/routers/scim.py:178-188。

来源：backend/open_webui/routers/scim.py:39-67, 235-268, 270-850

---

前端实现

管理 UI 提供了管理这些安全组件的界面。

组管理 UI

Groups.svelte 组件允许管理员创建组并修改默认权限 src/lib/components/admin/Users/Groups.svelte:73-100。

EditGroupModal.svelte：在“常规”、“权限”和“用户”选项卡之间协调组编辑 src/lib/components/admin/Users/Groups/EditGroupModal.svelte:28-30。
Permissions.svelte：提供 UI 来切换组的特定工作区和功能权限 src/lib/components/admin/Users/Groups/Permissions.svelte:36-185。它使用 DEFAULT_PERMISSIONS src/lib/constants/permissions.ts 通过 fillMissingProperties 确保所有字段都存在 src/lib/components/admin/Users/Groups/Permissions.svelte:18-29。
Users.svelte：通过允许管理员将用户加入或移出组来管理成员资格 src/lib/components/admin/Users/Groups/Users.svelte。

来源：src/lib/components/admin/Users/Groups.svelte，src/lib/components/admin/Users/Groups/Permissions.svelte，src/lib/components/admin/Users/Groups/EditGroupModal.svelte，src/lib/constants/permissions.ts