18.1 · 用户管理（User Management）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节18.1 状态全文译文模块界面与交互、接口与服务契约、认证、权限与安全、系统架构

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节User Management 上一章18 下一章18.2

源码线索

backend/open_webui/models/auths.py
backend/open_webui/models/users.py
backend/open_webui/routers/users.py
src/lib/components/ChangelogModal.svelte
src/lib/components/admin/Users/Groups.svelte
src/lib/components/admin/Users/Groups/EditGroupModal.svelte
src/lib/components/admin/Users/Groups/GroupItem.svelte
src/lib/components/admin/Users/Groups/Permissions.svelte
src/lib/components/admin/Users/Groups/Users.svelte
src/lib/components/admin/Users/UserList.svelte

模块标签

界面与交互
接口与服务契约
认证、权限与安全
系统架构
测试、发布与运维

中文译文

用户管理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/18.1-user-management

翻译时间：2026-06-09T16:12:15.428Z

翻译模型：deepseek-chat

原文字符数：9469

项目：Open WebUI (open-webui)

---

用户管理

用户管理界面

管理用户的主要管理界面位于管理面板中。它支持对用户账户进行搜索、排序以及执行 CRUD 操作。

用户列表与搜索

UserList.svelte 组件负责编排用户的显示。它采用分页表格视图，并支持带有 300ms 防抖延迟的实时搜索 src/lib/components/admin/Users/UserList.svelte:101-107。

数据获取：前端调用 API 层的 getUsers src/lib/components/admin/Users/UserList.svelte:85-90，该函数指向 /api/v1/users/ 端点。
分页：由 page 变量控制 src/lib/components/admin/Users/UserList.svelte:40，默认每页显示 30 项，该值在后端的 PAGE_ITEM_COUNT 中定义 backend/open_webui/routers/users.py:57-72。
排序：管理员可以通过 setSortKey 函数 src/lib/components/admin/Users/UserList.svelte:74-81 按 created_at、name、role 或 last_active_at 等键进行排序。

用户实体数据流

下图展示了用户数据从数据库到管理界面的流动过程，突出了从自然语言空间（搜索查询）到代码实体空间的转换。

用户数据检索流程

graph TD
    subgraph "自然语言空间"
        Input["管理员在搜索输入框中输入 'John'"]
    end

    subgraph "前端 SvelteKit"
        UL["UserList.svelte"] -- "getUsers(token, query, page)" --> API["src/lib/apis/users.ts"]
    end

    subgraph "后端 FastAPI"
        API -- "GET /api/v1/users/" --> UR["routers/users.py:get_users"]
        UR -- "Users.get_users(filter, skip, limit)" --> UM["models/users.py:UsersTable"]
    end

    subgraph "存储代码实体空间"
        UM -- "SQL SELECT" --> DB[("SQL_DB: 'user' 表")]
    end

    DB -- "行数据" --> UM
    UM -- "UserModel" --> UR
    UR -- "UserGroupIdsListResponse" --> API
    API -- "JSON" --> UL

来源：src/lib/components/admin/Users/UserList.svelte:83-101、backend/open_webui/routers/users.py:60-104、backend/open_webui/models/users.py:41-73

组管理与权限

Open WebUI 实现了一个强大的组系统来大规模管理权限。用户可以被分配到多个组，每个组拥有特定的权限集，这些权限集可以增强默认的用户权限。

组结构

组通过 Groups 模型定义，并通过 src/lib/components/admin/Users/Groups.svelte 进行管理 src/lib/components/admin/Users/Groups.svelte:35-71。每个组包含：

元数据：名称和描述 src/lib/components/admin/Users/Groups/EditGroupModal.svelte:36-38。
权限：一个 JSON 对象，定义了对工作区、共享、聊天和功能的访问权限 src/lib/components/admin/Users/Groups/Permissions.svelte:43-249。
成员：与组关联的用户，通过 addUserToGroup 和 removeUserFromGroup 函数管理 src/lib/components/admin/Users/Groups/Users.svelte:67-81。

权限类别

权限在后端被组织成层次化的 Pydantic 模型，以确保类型安全和验证 backend/open_webui/routers/users.py:169-250：

类别	描述	后端类
工作区	访问模型、知识、工具和技能。	`WorkspacePermissions`
共享	公开共享模型、知识和笔记的能力。	`SharingPermissions`
聊天	聊天功能的控制（STT、TTS、文件上传、编辑）。	`ChatPermissions`
功能	访问 API 密钥、网络搜索和图像生成。	`FeaturesPermissions`

组与用户的关联

用户与组之间的关联在 UI 中通过组管理视图中的 Users.svelte 组件处理 src/lib/components/admin/Users/Groups/Users.svelte:26-30。UI 使用 Checkbox 组件来切换成员状态，并通过 toggleMember 触发后端更新 src/lib/components/admin/Users/Groups/Users.svelte:67-81。

权限管理实体关系

classDiagram
    class User {
        +String id
        +String role
        +JSON settings
        +JSON info
    }
    class Group {
        +String id
        +String name
        +JSON permissions
    }
    class GroupMember {
        +String group_id
        +String user_id
    }
    class UserPermissions {
        +WorkspacePermissions workspace
        +SharingPermissions sharing
        +ChatPermissions chat
        +FeaturesPermissions features
    }

    User "1" -- "0..*" GroupMember : "通过 GroupMember 表映射"
    Group "1" -- "0..*" GroupMember : "通过 GroupMember 表映射"
    Group "1" -- "1" UserPermissions : "定义组范围的权限"
    User "1" -- "1" UserPermissions : "继承默认权限"

来源：backend/open_webui/models/users.py:41-105、backend/open_webui/routers/users.py:169-250、src/lib/components/admin/Users/Groups/Permissions.svelte:18-29

后端实现细节

数据模型

User 类继承自 Base 并映射到 user 表 backend/open_webui/models/users.py:41-42。它包含个人资料信息、在线状态和状态的字段 backend/open_webui/models/users.py:44-73。身份验证详情（密码）单独存储在 auth 表中，并由 AuthsTable 管理 backend/open_webui/models/auths.py:20-26。

API 端点

users.py 路由器处理管理和个人资料请求：

GET /：获取用户数据，并通过 Groups.get_groups_by_member_ids 包含 group_ids，以避免 N+1 查询问题 backend/open_webui/routers/users.py:60-104。
GET /permissions：通过 get_permissions 检索已认证用户的有效权限 backend/open_webui/routers/users.py:155-164。
GET /default/permissions：返回系统范围的默认用户权限 backend/open_webui/routers/users.py:252-257。
POST /update/by/id/{id}：更新用户详细信息，包括角色、名称和密码 backend/open_webui/routers/users.py:381-432。

安全与访问控制

对管理端点的访问通过 FastAPI 依赖项进行限制：

get_admin_user：确保请求者具有 admin 角色 backend/open_webui/routers/users.py:66。
get_verified_user：确保用户已通过身份验证并已验证 backend/open_webui/routers/users.py:121。

来源：backend/open_webui/models/users.py:41-73、backend/open_webui/routers/users.py:60-104、backend/open_webui/routers/users.py:155-164、backend/open_webui/models/auths.py:91-120