角色 (Roles)

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

角色名称	关键字	描述
Admin	`admin`	超级用户。对系统拥有完全控制权。
User	`user`	普通用户。受 RBAC 权限系统约束。
Pending	`pending`	受限用户。在获得批准前无法进行任何访问。

角色详情

管理员 (admin)

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

完全访问：默认拥有访问所有资源和设置的权限。
管理权限：可以管理用户、用户组和全局配置。
绕过限制：默认情况下绕过绝大多数权限检查。

管理员限制与最佳实践

尽管管理员通常拥有不受限的访问权限，但出于安全和隐私考虑，某些系统配置可能会限制他们的能力：

隐私控制：配置类似于 ENABLE_ADMIN_CHAT_ACCESS=False 的环境变量可以阻止管理员查看用户的聊天记录。
可能适用的特定功能例外：某些功能可能在标准的管理员绕过行为之外执行额外的检查。特别是对于 API Key，只要启用了 ENABLE_API_KEYS，管理员便可以随时生成 Key。
访问控制例外：如果禁用了 BYPASS_ADMIN_ACCESS_CONTROL，管理员可能需要获得显式授权才能访问私有模型/知识库/便签等资源。

为了建立健壮的安全态势，我们建议您将管理员也纳入到您的权限方案中（通过用户组），而不是仅仅依赖该角色隐式的绕过机制。这可以确保即使启用了绕过限制，管理员依然能够获得一致的访问权限。

普通用户 (user)

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

受权限约束：不拥有隐式的访问权限。所有能力都必须通过全局默认权限或用户组身份进行授予。
累加式权利：正如在权限 (Permissions) 部分所解释的，他们的实际权利是他们获得的所有授权的总和。

挂起用户 (pending)

新注册用户（如果进行了相应配置）或被停用用户的默认状态。

零访问：无法执行任何操作，也无法看到任何内容。
需要审批：必须由现有的管理员将其晋升为 user 或 admin。

备注

管理员角色实际上在所有方面的权限检查结果均为 check_permission() == True。细粒度的权限（如禁用“网页搜索”）通常不适用于管理员。

角色分配

初始设置

首个用户：在一台全新安装的系统上创建的第一个账户会被自动分配为 Admin 角色。
无头模式管理员创建：对于自动化/容器化部署，您可以使用环境变量自动创建管理员账户（见下文）。
后续用户：新注册的用户将被分配为默认用户角色。

配置

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

DEFAULT_USER_ROLE=pending
# 可选值: 'pending', 'user', 'admin'

pending（推荐用于公共/共享实例）：新用户在管理员在管理面板中明确激活他们之前无法登录。
user：新用户可以立即使用默认权限进行访问。
admin：（谨慎使用）新注册的用户将直接成为完全的系统管理员。

变更角色

管理员可以随时通过 Admin Panel > Users 更改用户的角色。

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

无头模式管理员账户创建

对于手动交互不可行的自动化部署（Docker, Kubernetes，云平台等）场景，Open WebUI 支持在首次启动时利用环境变量自动创建管理员账户。

工作原理

当配置了以下环境变量时：

WEBUI_ADMIN_EMAIL：管理员账户的电子邮件地址
WEBUI_ADMIN_PASSWORD：管理员账户的密码
WEBUI_ADMIN_NAME：（可选）管理员显示名称（默认为 "Admin"）

Open WebUI 将自动执行以下操作：

启动时检查数据库中是否存在任何用户
如果数据库为空（全新安装），将使用提供的凭证创建管理员账户
对密码进行安全哈希处理并予以存储
自动禁用注册（ENABLE_SIGNUP=False）以防止未授权的账户创建

使用场景

此功能特别适用于：

CI/CD 流水线：从密钥管理系统自动为 Open WebUI 实例提供管理员凭证
Docker/Kubernetes 部署：消除容器启动与手动创建管理员之间的时间差
自动化测试：使用预先配置的管理员账户创建可复现的测试环境
无头服务器：部署在无法通过访问 UI 来手动创建账户的环境中

示例配置

Docker Compose

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - WEBUI_ADMIN_EMAIL=admin@example.com
      - WEBUI_ADMIN_PASSWORD=${ADMIN_PASSWORD}  # 使用密钥管理
      - WEBUI_ADMIN_NAME=System Administrator
    # ... 其他配置

Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: openwebui-admin
type: Opaque
stringData:
  admin-email: admin@example.com
  admin-password: your-secure-password
  admin-name: System Administrator
---
apiVersion: v1
kind: Pod
metadata:
  name: open-webui
spec:
  containers:
  - name: open-webui
    image: ghcr.io/open-webui/open-webui:main
    env:
    - name: WEBUI_ADMIN_EMAIL
      valueFrom:
        secretKeyRef:
          name: openwebui-admin
          key: admin-email
    - name: WEBUI_ADMIN_PASSWORD
      valueFrom:
        secretKeyRef:
          name: openwebui-admin
          key: admin-password
    - name: WEBUI_ADMIN_NAME
      valueFrom:
        secretKeyRef:
          name: openwebui-admin
          key: admin-name

重要注意事项

安全注意事项

使用密钥管理：千万不要在 Docker Compose 文件或 Dockerfile 中硬编码 WEBUI_ADMIN_PASSWORD。请使用 Docker secrets、Kubernetes secrets 或环境变量注入。
强密码：在生产环境部署中请使用强且唯一的密码。
设置后更改：为了增强安全性，请考虑在初始部署后通过 UI 更改管理员密码。
自动禁用注册：创建管理员后，注册功能将被自动禁用。如果需要，您稍后可以通过 Admin Panel > Settings > General 重新启用它。

行为详情

仅在全新安装时生效：仅当数据库中不存在任何用户时，才会创建管理员账户。如果用户已经存在，这些环境变量将被忽略。
密码哈希：密码使用与手动创建账户相同的机制进行安全哈希，以确保安全性。
一次性操作：这是在首次启动时的一次性操作。使用相同的环境变量进行后续重启不会修改现有的管理员账户。

有关这些环境变量的完整文档，请参阅环境配置指南。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

角色详情​

管理员 (admin)​

普通用户 (user)​

挂起用户 (pending)​

角色分配​

初始设置​

配置​

变更角色​

无头模式管理员账户创建​

工作原理​

使用场景​

示例配置​

Docker Compose​

Kubernetes Secret​

重要注意事项​