9.3 · 用户角色与权限（User Roles and Permissions）

用户角色与权限（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/9.3-user-roles-and-permissions

翻译时间：2026-05-27T08:44:53.746Z

翻译模型：deepseek-chat

原文字符数：13318

项目：Onyx (onyx)

---

用户角色与权限

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• backend/alembic/versions/27fb147a843f_add_timestamps_to_user_table.py
• backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.py
• backend/ee/onyx/db/user_group.py
• backend/ee/onyx/server/user_group/api.py
• backend/ee/onyx/server/user_group/models.py
• backend/onyx/auth/schemas.py
• backend/onyx/auth/users.py
• backend/onyx/db/api_key.py
• backend/onyx/db/auth.py
• backend/onyx/db/document_set.py
• backend/onyx/db/enums.py
• backend/onyx/db/models.py
• backend/onyx/db/pat.py
• backend/onyx/db/user_preferences.py
• backend/onyx/db/users.py
• backend/onyx/server/features/document_set/api.py
• backend/onyx/server/manage/administrative.py
• backend/onyx/server/manage/get_state.py
• backend/onyx/server/manage/models.py
• backend/onyx/server/manage/users.py
• backend/onyx/server/models.py
• backend/tests/api/test_api.py
• backend/tests/integration/common_utils/managers/user_group.py
• backend/tests/integration/tests/chat/test_chat_document_set_access.py
• backend/tests/integration/tests/usergroup/test_add_users_to_group.py
• backend/tests/unit/onyx/auth/test_single_tenant_jwt_strategy.py
• backend/tests/unit/onyx/db/test_delete_user.py
• backend/tests/unit/onyx/db/test_index_attempt_errors.py
• backend/tests/unit/onyx/server/test_full_user_snapshot.py
• backend/tests/unit/onyx/utils/test_vespa_tasks.py
• deployment/aws_ecs_fargate/cloudformation/services/onyx_nginx_service_template.yaml
• deployment/aws_ecs_fargate/cloudformation/services/onyx_web_server_service_template.yaml
• web/src/hooks/useAdminUsers.ts
• web/src/hooks/useTokenRefresh.test.tsx
• web/src/hooks/useTokenRefresh.ts
• web/src/hooks/useUserCounts.ts
• web/src/providers/UserProvider.tsx
• web/src/refresh-pages/admin/UsersPage/interfaces.ts

目的与范围

本文档描述了 Onyx 中基于角色的访问控制（RBAC）系统，包括 UserRole 枚举、角色层级结构和权限执行逻辑。它详细说明了系统如何区分 Web 登录用户和外部身份，以及角色如何与企业版的用户组系统集成。

关于认证机制的详细信息，请参见认证方法。关于多租户架构和模式隔离，请参见9.2 多租户架构。

---

用户角色层级结构

Onyx 实现了由 UserRole 枚举定义的层级角色系统。每个角色提供逐步递增的系统权限，范围从受限的外部访问到完整的管理控制。

角色定义

UserRole 枚举定义了七个不同的角色：

角色	显示名称	描述	关键能力
LIMITED	受限用户	权限最小的受限用户	可访问有限的基本 API 端点；无法通过 UI 手动分配 backend/onyx/db/users.py:102-111。
BASIC	基本用户	标准用户角色	常规聊天和搜索访问权限；无管理能力。
ADMIN	管理员	完整管理权限	完整的系统配置、用户管理和连接器管理。
CURATOR	组管理员	组范围管理员	管理操作仅限于其被分配管理的特定用户组 backend/onyx/auth/schemas.py:16-17。
GLOBAL_CURATOR	全局组管理员	跨组管理员	对其所属的所有用户组执行管理操作 backend/onyx/auth/schemas.py:18-19。
EXT_PERM_USER	外部用户	仅身份角色	从外部权限系统同步的用户，尚未登录 Web 应用 backend/onyx/auth/schemas.py:22。
SLACK_USER	Slack 用户	仅集成角色	通过 Slack 与 Onyx 交互但无 Web 登录的用户 backend/onyx/auth/schemas.py:21。

来源： backend/onyx/auth/schemas.py:11-31，backend/onyx/db/users.py:56-132

Web 登录区分

系统使用 is_web_login() 方法来区分交互式用户和外部身份。SLACK_USER 和 EXT_PERM_USER 角色返回 False，因为这些角色代表通过集成捕获的身份，而非活跃的 Web 账户。

来源： backend/onyx/auth/schemas.py:33-37，backend/onyx/db/enums.py:22-27

角色层级结构与实体映射

下图将自然语言角色桥接到管理它们的代码实体，特别展示了 UserRole 与 AccountType 枚举之间的关系。

标题：用户角色与账户类型映射

graph TD
    subgraph "自然语言空间"
        AdminRole["系统管理员"]
        CuratorRole["组管理员"]
        StandardUser["标准 Web 用户"]
        ExternalID["外部身份"]
    end

    subgraph "代码实体空间 (backend/onyx/auth/schemas.py)"
        UR_ADMIN["UserRole.ADMIN"]
        UR_GC["UserRole.GLOBAL_CURATOR"]
        UR_C["UserRole.CURATOR"]
        UR_BASIC["UserRole.BASIC"]
        UR_LIMITED["UserRole.LIMITED"]
        UR_SLACK["UserRole.SLACK_USER"]
        UR_EXT["UserRole.EXT_PERM_USER"]
    end

    subgraph "账户类型映射 (backend/onyx/db/enums.py)"
        AT_STD["AccountType.STANDARD"]
        AT_BOT["AccountType.BOT"]
        AT_EXT["AccountType.EXT_PERM_USER"]
        AT_ANON["AccountType.ANONYMOUS"]
    end

    AdminRole --> UR_ADMIN
    CuratorRole --> UR_GC
    CuratorRole --> UR_C
    StandardUser --> UR_BASIC
    ExternalID --> UR_SLACK
    ExternalID --> UR_EXT

    UR_ADMIN & UR_GC & UR_C & UR_BASIC & UR_LIMITED --> AT_STD
    UR_SLACK --> AT_BOT
    UR_EXT --> AT_EXT

    style UR_ADMIN stroke-width:4px

来源： backend/onyx/auth/schemas.py:11-37，backend/onyx/db/user_preferences.py:31-34，backend/onyx/db/enums.py:7-21

---

权限能力与执行

权限在 API 和数据库层通过依赖注入和校验函数执行。

管理访问控制

对管理端点的访问由 FastAPI 依赖和 Permission 枚举控制：

• require_permission(Permission.FULL_ADMIN_PANEL_ACCESS)：限制访问权限为 UserRole.ADMIN backend/onyx/server/manage/users.py:140。
• current_curator_or_admin_user：允许 ADMIN、GLOBAL_CURATOR 和 CURATOR 角色访问管理功能 backend/onyx/auth/users.py:160。

来源： backend/onyx/auth/users.py:158-170，backend/onyx/server/manage/users.py:137-143，backend/onyx/db/enums.py:81

对象创建与编辑

系统通过 validate_object_creation_for_user() 根据用户角色校验资源修改（例如，创建文档集或角色）：

1. 管理员：对所有配置和数据管理拥有全局访问权限 backend/ee/onyx/db/user_group.py:159-160。
2. 组管理员：管理操作限定于其管理的特定 UserGroup backend/ee/onyx/db/user_group.py:187-193。
3. 基本用户：通常被限制进行系统级配置，但可以管理个人偏好设置，如 default_model 或 theme_preference backend/onyx/server/manage/models.py:73-86。

来源： backend/ee/onyx/db/user_group.py:137-195，backend/onyx/server/manage/models.py:72-86

角色转换逻辑

更新用户角色时，validate_user_role_update() 会执行严格的校验 backend/onyx/db/users.py:56-132：

• 账户类型为 AccountType.BOT 或 EXT_PERM_USER 的用户在完成 Web 登录之前，无法手动更改其角色 backend/onyx/db/users.py:74-84。
• LIMITED 用户无法通过标准管理面板手动提升 backend/onyx/db/users.py:102-111。
• CURATOR 角色必须通过用户组管理路径分配，以确保组角色一致性 backend/onyx/db/users.py:95-100。

来源： backend/onyx/db/users.py:56-132，backend/onyx/db/user_preferences.py:37-81

---

用户组与组管理员（企业版）

在企业版中，权限通常通过用户组委托给组管理员。

组管理员逻辑流程

系统通过检查用户与 UserGroup 实体的关系来确定其有效权限。

标题：权限解析与组逻辑

flowchart TD
    User["用户模型 (onyx/db/models.py)"] --> RoleCheck{"检查 UserRole"}

    RoleCheck -->|ADMIN| FullAccess["完整系统访问权限"]

    RoleCheck -->|GLOBAL_CURATOR| GroupMember["获取用户所属的<br/>所有 UserGroups"]

    RoleCheck -->|CURATOR| CuratorMember["获取 User.is_curator == True<br/>的所有 UserGroups"]

    GroupMember --> GroupPerms["管理这些组中的 CC Pairs、<br/>Document Sets 和 Personas"]
    CuratorMember --> GroupPerms

    subgraph "逻辑 (onyx/db/user_preferences.py)"
        Recompute["recompute_user_permissions__no_commit()"]
        AssignGroups["assign_user_to_default_groups__no_commit()"]
    end

    GroupPerms --> Recompute
    RoleCheck --> AssignGroups

来源： backend/onyx/db/user_preferences.py:37-81，backend/onyx/db/models.py:129，backend/ee/onyx/db/user_group.py:37-41

---

管理界面

管理员通过 /manage/set-user-role 端点及相关管理路由器管理角色和权限。

关键组件：

• set_user_role：API 端点，在校验请求者的管理员状态和角色转换的有效性后，调用 update_user_role backend/onyx/server/manage/users.py:136-162。
• update_user_role：数据库函数，双写 account_type，协调默认组成员身份，并触发权限重新计算 backend/onyx/db/user_preferences.py:37-82。
• UserPreferences：包含用户特定设置的模型，如 default_model、theme_preference 和 chosen_assistants backend/onyx/server/manage/models.py:72-86。

来源： backend/onyx/server/manage/users.py:136-162，backend/onyx/db/user_preferences.py:37-82，backend/onyx/server/manage/models.py:123-140

用户搜索与过滤

后端通过 get_all_users 和 _get_accepted_user_where_clause 支持带过滤的用户检索，这些函数应用 SQL 级别的过滤条件：

• email_filter_string（对电子邮件进行 ILIKE 匹配）backend/onyx/db/users.py:155-160。
• roles_filter（匹配 UserRole 枚举）backend/onyx/db/users.py:167-170。
• is_active_filter backend/onyx/db/users.py:169。

来源： backend/onyx/db/users.py:134-162，backend/onyx/db/users.py:165-200

---

权限同步与维护

对于用户和组，权限通过以下几个后台机制维护：

1. recompute_user_permissions__no_commit：当用户的角色或组成员身份发生变化时触发，以刷新数据库中的权限状态 backend/onyx/db/user_preferences.py:79。
2. 默认组分配：当标准用户登录或被激活时，通过 assign_user_to_default_groups__no_commit 自动将其分配到默认组 backend/onyx/db/user_preferences.py:73-77。
3. 停用：deactivate_user 将 is_active 设置为 False，阻止用户获取新的会话令牌，同时保留其数据 backend/onyx/db/user_preferences.py:84-91。

来源： backend/onyx/db/user_preferences.py:37-113，backend/onyx/db/users.py:131