用户组

Open WebUI 中的用户组是大规模组织用户和管理访问控制的强大机制。它们有两个主要用途：

1. 权限管理： 高效地向多个用户分配细粒度权限。
2. 资源访问控制： 控制谁可以访问特定的私有资源（模型、知识库、工具）。

权限合并逻辑

Open WebUI 权限是累加的（基于并集）。

• 如果用户属于多个用户组，他们会获得所有权限的并集。
• 如果用户组 A 允许"图像生成"而用户组 B 不允许，同时属于这两个用户组的用户将拥有图像生成访问权限。
• "拒绝"权限不存在；您只能"授予"权限。

用户组管理

用户组可以在管理面板 > 用户组部分进行管理。

用户组配置

创建或编辑用户组时，您可以配置其在系统中的可见性：

• 谁可以向此用户组共享：（访问控制设置）
  • 任何人：（默认）平台上的任何用户都可以在"访问控制"菜单中看到此用户组，并可向其共享对话内容、模型、提示词或知识库。
  • 成员：只有已经是该用户组成员的用户才会在"访问控制"菜单中看到它作为选项。这是私人团队协作（例如"市场营销"团队）的理想设置，确保只有队友可以相互共享资源（模型、提示词、知识库）。
  • 无人：该用户组对非管理员用户完全隐藏于共享菜单中。这非常适合专门用于 RBAC 权限分配的技术用户组（例如"高级用户"组），不需要内容共享功能。

策略：权限用户组 vs 共享用户组

为了维护一个干净且易管理的系统，考虑使用命名方案将用户组分为两类：

1. 权限用户组（例如前缀 [权限]、角色- 或 P-）

   • 目的：专门用于授予功能（例如 [权限] 图像生成、[权限] 网络搜索）。
   • 配置：将"谁可以共享"设置为无人。
   • 结果：用户获得所需功能，但这些技术用户组不会影响"共享"菜单的简洁性。

2. 共享用户组（例如前缀 团队-、项目- 或普通名称）

   • 目的：专门用于组织人员（例如 市场营销、工程、团队 Alpha）以共享资源。
   • 配置：将"谁可以共享"设置为成员或任何人。
   • 最佳实践：禁用这些用户组中的所有权限。
     • 依赖全局默认权限（或单独的权限用户组）来获得功能权限。
     • 为什么？ 这确保了轻松的权限撤销。如果您决定全局禁用某个功能（例如"网络搜索"），它将立即对所有人生效。如果您的共享用户组启用了"网络搜索"，您将需要手动更新每个用户组来移除该权限，因为用户组的 True 状态会覆盖全局的 False。保持功能用户组简洁以维护全局控制。

创建方式

• 手动创建： 管理员可以通过 UI 手动创建用户组并添加用户。
• OAuth 同步： 如果启用了 ENABLE_OAUTH_GROUP_MANAGEMENT，用户组可以从您的 OAuth 提供商（例如 Keycloak、Azure AD）同步。
  • 自动创建： 启用 ENABLE_OAUTH_GROUP_CREATION 后，本地不存在的用户组将自动创建。
  • 成员同步： 用户会严格按照 OAuth claims 添加/移除到用户组。

用户组结构

用户组定义通常包括：

• 名称：用户组的显示名称。
• 描述：用户组的用途说明。
• 权限：覆盖默认用户权限的详细 JSON 对象（参见权限）。
• 成员：属于该用户组的用户 ID 列表。

向用户组分配权限

编辑用户组时，您可以切换特定权限。

• 默认状态：默认情况下，用户组不授予额外权限；成员依赖全局默认值。
• 授权访问：将权限（例如"网络搜索"）切换为开意味着所有成员都能获得该功能，即使全局禁用了它。

资源访问（RBAC）

您可以使用用户组或单个用户授权来限制对特定对象（如专有模型或敏感知识库）的访问。

1. 标记资源：创建/编辑模型或知识库时，将其可见性设置为私有或受限。
2. 授予访问：选择应具有"读取"或"写入"访问权限的特定用户组或单个用户。重新设计的访问控制 UI 使同时添加多个用户组或用户变得非常方便。

模型的知识库范围

除可见性外，知识库访问也受模型配置限制。当模型附加了特定知识库时，它只能访问这些 KB（而非所有用户可访问的 KB）。详情请参阅使用原生函数调用的知识库范围。

访问授权系统

在更深层面，资源访问通过数据库中存储的标准化访问授权进行管理。每个授权指定：

• 资源：资源的类型和 ID（例如特定模型或知识库）。
• 主体：谁获得访问权限——用户组或单个用户。
• 权限：访问级别——read（读取）或 write（写入）。

例如，授予"市场营销"用户组对某模型的读取访问权限，以及授予特定编辑用户写入访问权限，将创建两个独立的授权条目。公开访问由具有通配符（*）主体的用户授权表示。

• 读取：用户可以查看和使用资源。
• 写入：用户可以更新或删除资源。

预览访问（审计）

当访问授权横跨许多用户组和资源时，很容易搞不清楚谁能看什么。Open WebUI 提供了一个仅限管理员使用的预览访问视图，能解析出指定用户或用户组的所有访问授权，并集中列出——无需逐个资源页面翻找。

针对用户 —— 在管理面板 > 用户中，将鼠标悬停在某个非管理员用户行上，点击眼睛样式的预览访问按钮。弹窗会展示该用户可以读取的所有模型、知识库和工具，这些结果会聚合其所有用户组成员资格以及任何直接的用户授权。

针对用户组 —— 在管理面板 > 用户 > 用户组中，打开用户组编辑器并使用预览用户组访问面板。输出格式相同（模型、知识、工具），只是范围限定在该用户组的授权内。

两个视图都仅限管理员访问且只读——它们反映当前访问授权表中的内容，不做任何修改。在权限变更后，可使用它们来确认结果是否符合预期，或作为定期 RBAC 审计的一部分。

对应的程序化接口：

• GET /api/v1/users/{user_id}/preview — 用户视图（需要管理员权限）
• GET /api/v1/groups/id/{id}/preview — 用户组视图（需要管理员权限）