Skip to main content

角色 (Roles)

Open WebUI 定义了三个主要的系统角色，用于确定用户账户的基本访问级别。这些角色与组 (Groups) 和 权限 (Permissions) 是不同的。

角色关键字描述
管理员 (Admin)admin超级用户。对系统拥有完整控制权。
普通用户 (User)user标准用户。受 RBAC 权限系统约束。
待审核 (Pending)pending受限用户。在获得批准前无法访问。

角色详情​

管理员 (admin)​

管理员角色专为系统维护人员设计。

  • 完整访问权限：默认可以访问所有资源和设置。
  • 管理功能：可以管理用户、组和全局配置。
  • 绕过机制：默认情况下绕过大多数权限检查。
管理员限制与最佳实践

虽然管理员通常拥有不受限制的访问权限，但某些系统配置为了安全和隐私可能会限制其能力：

  • 隐私控制：通过设置环境变量 ENABLE_ADMIN_CHAT_ACCESS=False 可以防止管理员查看用户聊天记录。
  • 严格功能检查：关键安全功能（如 API 密钥 features.api_keys）即使对管理员也需要显式授予权限。
  • 访问控制异常：如果禁用了 BYPASS_ADMIN_ACCESS_CONTROL，管理员访问私有模型/知识库资源可能也需要显式权限。

为了获得稳健的安全态势，我们建议将管理员纳入您的权限方案（通过组）中，而不是仅仅依赖角色的隐式绕过。这可以确保在启用绕过限制时仍能保持一致的访问。

标准用户 (user)​

这是团队成员的默认功能角色。

  • 受权限约束：不具有隐式访问权限。所有能力必须通过全局默认权限或组策略授予。
  • 累加权利：正如在权限 (Permissions) 部分所解释的，他们的有效权利是其获得的所有授权的总和。

待审核用户 (pending)​

这是新注册用户（如果配置了审核）或停用用户的默认状态。

  • 零访问权限：无法执行任何操作或查看任何内容。
  • 需要批准：必须由现有管理员提升为 user 或 admin。
note

管理员角色实际上在所有 check_permission() 检查中都返回 True。细粒度权限（如禁用“网页搜索”）通常不适用于管理员。

角色分配​

初始设置​

  • 首个用户：在新安装的系统上创建的第一个账户会自动分配为管理员 (Admin) 角色。
  • 后续用户：新注册的用户将被分配为默认用户角色。

配置​

您可以通过 DEFAULT_USER_ROLE 环境变量控制新用户的默认角色：

DEFAULT_USER_ROLE=pending
# 选项：'pending', 'user', 'admin'
  • pending（推荐用于公开/共享实例）：新用户在管理员于面板中显式激活前无法登录。
  • user：新用户立即获得默认权限的访问权限。
  • admin：（慎用）新用户直接成为系统管理员。

更改角色​

管理员可以随时通过管理员面板 > 用户更改用户的角色。

  • 将用户提升为 admin 会授予其完整控制权。
  • 将管理员降级为 user 会使其重新受到权限系统的约束。