agentic_huge_data_base / wiki
页面 Onyx · 9.3 用户角色与权限·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 9.3

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

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节9.3 状态全文译文 模块界面与交互、认证、权限与安全、文档对象与元数据、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节User Roles and Permissions 上一章9.2 下一章9.4
源码线索
  • 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
模块标签
  • 界面与交互
  • 认证、权限与安全
  • 文档对象与元数据
  • 测试、发布与运维
  • 检索、召回与索引

章节正文

用户角色与权限

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

用户角色与权限

相关源文件

本章引用的主要源码文件：

  • 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_USERSlack 用户仅集成角色通过 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 枚举之间的关系。

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

Onyx · 角色层级结构与实体映射 · 图 1
Onyx · 角色层级结构与实体映射 · 图 1

来源： 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 实体的关系来确定其有效权限。

标题：权限解析与组逻辑

Onyx · 组管理员逻辑流程 · 图 2
Onyx · 组管理员逻辑流程 · 图 2

来源： 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