用户管理
功能概述
用户管理(Users)是 Agentbase 身份认证(Auth)服务的核心操作中心,面向项目管理员与研发运维人员提供终端用户账号的全生命周期治理能力。在项目 **企业智能客服与知识中台**(Project ID:enterprise-ai-hub-210)中,管理员可通过 Console 的 Auth → Users 页面或服务端 SDK(agentbase-node-sdk@2.10.0)集中检索、创建、验证、封禁/解封用户,维护用户的分类标签(Labels)与个性化键值偏好(Preferences),并实时审计或清理用户的活跃登录会话(Sessions)、团队成员关系(Memberships)、第三方 OAuth 身份(Identities)与消息投递目标(Targets)。
通过将终端用户的基础属性与业务扩展元数据(如 vip 客户等级标签、architect 架构师身份标签、界面语言与默认知识库偏好)统一收敛在 Auth Users 中,企业无需在业务数据库(如 enterprise_biz_db)中重复建设冗余的账号密码表、会话状态表与密码哈希校验逻辑,同时还能与 Agentbase 的长期记忆(Memory)模块无缝联动——例如智能体可直接根据 user_zhangwei_001(张伟)和 user_lina_002(李娜)的 User ID 自动关联长期对话事实与用户画像(Profile)。
核心概念与架构
每个 Auth 用户实体由“核心身份标识(Core Identity)”与五个关联子域(Memberships、Identities、Targets、Sessions、Activity)组成。下图展示了单个终端用户在 Agentbase 内的六维数据模型与生命周期状态流转:
flowchart LR
subgraph Lifecycle["用户账号状态机 (Status)"]
Unverified["已创建 / 未验证<br/>(Unverified)"]
Verified["已验证激活<br/>(Verified: Email / Phone)"]
Blocked["账户已封禁<br/>(Blocked: 立即阻断访问)"]
Deleted["永久级联删除<br/>(Deleted: 不可逆)"]
Unverified -->|验证邮箱或手机号| Verified
Unverified & Verified -->|Block account| Blocked
Blocked -->|Unblock account| Verified
Unverified & Verified & Blocked -->|Delete user| Deleted
end
subgraph UserEntity["用户核心档案 (User Overview)"]
UID["User ID: user_zhangwei_001<br/>Name: 张伟<br/>Email: zhangwei@enterprise.example.com<br/>Phone: +8613800138001"]
Labels["用户标签 (Labels)<br/>['vip', 'architect']<br/>→ Role.label('vip')"]
Prefs["键值偏好 (Preferences)<br/>{\"tier\": \"platinum\", \"lang\": \"zh-CN\"}"]
MFAState["MFA 多因素认证 &<br/>User Impersonation 冒充开关"]
end
subgraph SubDomains["五大关联子域 (6个详情页签)"]
TabMemberships["Memberships<br/>所属团队与角色<br/>(team_support_ops / vip_customer)"]
TabIdentities["Identities<br/>第三方 OAuth2 绑定身份<br/>(Gitee / GitHub / SSO)"]
TabTargets["Targets<br/>消息通知目标<br/>(自动生成 Email & SMS Target)"]
TabSessions["Sessions<br/>活跃设备会话列表<br/>(Chrome on macOS / 单退或全退)"]
TabActivity["Activity<br/>用户级安全审计日志<br/>(登录 / 改密 / 权限变更)"]
end
Verified --> UID
UID --> Labels & Prefs & MFAState
UID --> TabMemberships & TabIdentities & TabTargets & TabSessions & TabActivity核心概念与实战示例数据表
在 SIT 演示项目 enterprise-ai-hub-210 中,系统预置并管理了以下典型终端用户档案,贯穿智能客服工单、知识库检索与长期记忆提取全流程:
| 属性维度 | 示例用户 1(企业 VIP 客户) | 示例用户 2(高级技术支持专家) | 字段约束与平台行为说明 |
|---|---|---|---|
**User ID($id)** | user_zhangwei_001 | user_lina_002 | 最长 36 字符,仅允许 a-z、A-Z、0-9、.、-、_,且首字符不能为特殊字符;留空时系统自动生成唯一 ID。 |
| Name(姓名) | 张伟 | 李娜 | 最长 128 字符,支持中文与多语言字符;可在创建时留空并在后续随时更新。 |
| Email(邮箱) | zhangwei@customer-corp.example.com | lina.support@agentbase-ops.example.com | 创建时自动转为全小写,在同一项目内强制唯一(冲突时返回 USER_EMAIL_ALREADY_EXISTS)。 |
| Phone(手机号) | +8613800138001 | +8613900139002 | 必须遵循 E.164 标准:以 + 开头并附带国际国家码,+ 后最多 15 位纯数字。 |
| Status(状态) | Verified(邮箱与手机已验证) | Verified(邮箱已验证) | 包含账户启用态(Active vs blocked 红色封禁徽标)以及邮箱/手机号各自的验证状态。 |
| Labels(标签) | vip, architect | support, internal | 每项标签仅允许字母与数字字符(a-zA-Z0-9),自动映射为 label:vip、label:architect 等权限角色。 |
| Preferences(偏好) | {"company": "远航金融科技", "slaLevel": "P0", "preferredModel": "qwen-plus"} | {"department": "企业智能客服中心", "shift": "day", "workbenchMode": "expert"} | JSON 键值对象,支持客户端通过 account.updatePrefs() 或管理员在 Console 逐条编辑。 |
| 关联长期记忆(Memory) | 已提取客户架构偏好与 OceanBase 分布式事务咨询上下文 | 已沉淀标准排障 SOP 与技能蒸馏记录 | Memory 模块按 user_id 索引并构建个性化用户画像(Profile)。 |
角色、入口与关联关系
控制台入口与权限要求
- 访问路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 点击左侧导航栏 Auth → 默认进入 Users 页签(路由:/console/project-{region}-{project}/auth)。 - 详情页路径:在用户列表中点击任意一行(如
user_zhangwei_001),进入/console/project-{region}-{project}/auth/user-{userId}。 - 操作权限门禁:
- 查看用户列表与详情页签需要组织角色具备
users.read权限(owner、admin、developer、editor、analyst)。 - 创建用户、修改用户资料/密码/标签/偏好、封禁账号、踢出会话或删除用户需要
users.write权限(仅owner、admin、developer、editor具备;billing与analyst角色无写权限)。
- 查看用户列表与详情页签需要组织角色具备
与上下游模块的关联关系
- 自动创建消息目标(Targets):当管理员在 Console 点击 Create user 或通过 API 创建用户时,只要填写了
Email,系统会自动为该用户生成一条Email类型的 Target;若同时填写了Phone,还会自动生成一条SMS类型的 Target,直接供 消息推送(Messaging) 与 消息目标(Targets) 订阅主题和发送通知。 - 团队成员关系(Memberships):用户在 Memberships 页签中展示其所属的所有项目团队(如
team_support_ops)及团队角色。将用户移出团队后,其对绑定了Role.team(...)的数据库表(customer_tickets)和存储桶(kb_enterprise_docs)的访问权限立即收回。 - 长期记忆与用户画像(Memory & Profiles):在 记忆管理 与 用户画像 中,系统直接以 Auth 用户的
User ID(如user_zhangwei_001)聚合对话历史、长期事实(Facts)与经验蒸馏结果。
功能详解与操作指南
1. 检索与浏览用户列表
进入 Auth → Users 页面后,控制台展示项目内全部终端用户的分页列表(按创建时间倒序排列):
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
- 多维全文检索:顶部搜索框支持直接输入**用户姓名(如
张伟)、邮箱地址、手机号或 User ID(如user_zhangwei_001)**进行实时过滤。 - 表格列说明与自定义列:
- 默认展示列:User ID(带一键复制按钮)、Name(用户头像与显示名称)、Identifiers(已绑定的邮箱与手机号)、Status(显示
Verified、Unverified,若账号被封禁则显示醒目的红色blocked徽标)、Joined(注册/创建时间)。 - 可选隐藏列:点击表格右上角的列选择器(Columns),可勾选打开默认隐藏的 Labels(用户标签)与 Last activity(最近活跃时间)列。
- 默认展示列:User ID(带一键复制按钮)、Name(用户头像与显示名称)、Identifiers(已绑定的邮箱与手机号)、Status(显示
- 批量删除:勾选列表左侧复选框后,底部浮现批量操作栏,支持一键批量删除所选用户(操作不可逆,请谨慎执行)。
2. 创建终端用户(Create user)
在日常运营中,除了终端用户通过前端页面自助注册外,管理员可在 Console 手动创建内部支持账号或 VIP 客户账号:
- 在 Auth → Users 页面右上角点击 Create user 按钮,打开创建用户弹窗。
- 按下表规范填写字段(所有字段均为可选,留空可创建匿名或待绑定用户,但生产环境建议至少填写姓名、邮箱与密码):
| 弹窗字段 | 必填性 | 校验规则与输入示例 |
|---|---|---|
| Name | 可选 | 用户显示名称,最长 128 字符。示例:张伟 |
| 可选 | 合法电子邮箱格式;服务端入库前统一转换为小写,且在同一项目内必须唯一。示例:zhangwei@customer-corp.example.com | |
| Phone | 可选 | 必须以 + 开头并带国际区号,+ 后最多 15 位数字。示例:+8613800138001 |
| Password | 可选 | 长度至少 8 个字符(服务端校验范围为 8–256 字符)。若项目在 安全策略 中启用了密码字典(Password dictionary)或禁止包含个人信息(Disallow personal data),密码还需通过对应合规校验。 |
| User ID | 可选 | 默认自动生成唯一 ID。点击 User ID 标签可展开自定义输入框,填入如 user_zhangwei_001(仅限字母、数字、.、-、_,最长 36 字符,不能以特殊符号开头)。 |
- 点击 Create 提交。页面右上角弹出成功通知
"{name} has been created",并自动跳转至该用户的详情页(/auth/user-{userId})。
3. 用户详情页六大页签全解析
进入单个用户详情页(以 user_zhangwei_001 为例)后,可通过顶部六个页签完成全方位运维管理:
(1)Overview 页签:基础档案、标签、偏好与高危安全开关
Overview 页签由多张独立保存的配置卡片组成:
| 卡片名称 | 核心功能与操作步骤 | 生效机制与安全边界 |
|---|---|---|
| Status(账户状态与验证) | 1. 点击 Block account 立即封禁账号(已封禁时显示 Unblock account 解封)。<br/>2. 点击 Verify(或下拉菜单)可分别将 Email 和 Phone 标记为 Verify(已验证)或 Unverify(取消验证)。 | 封禁账号立即生效,该用户的所有既有会话将无法再通过权限校验。手动修改验证状态不会向用户发送验证邮件或短信。 |
| Email(修改邮箱) | 输入新邮箱地址后点击 Update。 | 直接在服务端更新该用户的绑定邮箱,不会触发确认邮件;新邮箱同样不得与项目内其他用户冲突。 |
| Phone(修改手机号) | 输入符合 + 开头 E.164 格式的新手机号后点击 Update。 | 直接更新绑定手机号并同步关联 SMS Target。 |
| Password(重设密码) | 输入新密码(至少 8 个字符)后点击 Update。 | 管理员强制重设用户密码。若项目在 Security → Session security 中开启了密码修改后失效会话(Invalidate sessions),用户既有会话将同步失效。 |
| Labels(用户标签) | 在输入框中输入纯字母数字标签(如 vip、architect),按回车添加后点击 Update。 | 仅允许字母与数字字符(不含连字符或下划线)。保存后该用户立即获得 Role.label('vip') 与 Role.label('architect') 权限角色。 |
| Preferences(键值偏好) | 点击 Add preference 逐行输入 Key 与 Value(如 tier = platinum、preferredModel = qwen-plus),点击 Update 保存。 | 存储于用户对象的 prefs JSON 字段中,前端可通过 account.getPrefs() 直接读取,总大小上限为 64 KB。 |
| User impersonation(用户冒充) | 切换开关以允许或禁止该用户通过 Client SDK 冒充项目内其他终端用户。 | 高危权限:仅可授予受信任的内部运营或技术支持专家(如 user_lina_002)。冒充期间的所有操作审计均记录在发起冒充的账号名下。 |
| Multi-factor authentication(多因素认证) | 切换该用户的 MFA 启用状态;若用户已绑定验证器 App,会显示 TOTP (One-time code) 及 Delete authenticator 按钮。 | 当用户丢失手机导致无法生成 TOTP 验证码时,管理员可点击 Delete authenticator 移除其 TOTP 因子(该删除操作不可逆,移除后用户需重新绑定)。 |
| Delete user(删除用户) | 点击底部红色 Delete 按钮,在确认弹窗中核对信息后确认删除。 | 永久且不可逆:彻底删除该用户及其关联的全部 Sessions、Memberships、Identities、Targets 数据。 |
(2)Memberships 页签:所属团队与角色管理
- 展示该用户当前加入的所有项目内团队列表,包含三列:Name(团队名称,点击可直接跳转到对应团队详情页,如
VIP客户技术支持组)、Roles(该用户在团队内拥有的自定义角色标签,如admin、support_lead)、Joined(加入团队时间)。 - 移除团队成员:点击行尾删除图标或勾选多行批量删除,可将用户移出对应团队(操作不可逆,移出后立即丧失该团队赋予的数据访问权限)。
(3)Identities 页签:第三方 OAuth 关联身份
- 当用户曾通过 GitHub、Google 或 Custom OAuth2(如 Gitee、企业 SSO)登录时,该页签会列出所有已关联的外部身份。
- 表格列包括:Identity ID、Provider(提供方名称)、Email、Expiry Date(OAuth 访问令牌过期时间)、Created(首次关联时间);通过列选择器还可打开默认隐藏的 Provider UID 与 Updated 列。
- 操作边界:此页签仅支持单条或批量删除(解绑)第三方身份,不提供手动新建入口(Identity 只能通过真实 OAuth2 登录流程自动建立)。
(4)Targets 页签:通知目标查看与清理
- 列出该用户关联的所有消息投递目的地,包含 Target ID、Target(邮箱地址、手机号或设备推送名称)、Type(
Email/SMS/Push)、Provider、Created。 - 支持勾选后批量删除失效目标。详细规则请参阅 消息目标(Targets)。
(5)Sessions 页签:在线设备监控与强制踢出
- 展示该用户当前所有活跃的登录会话,表格列包括:
- Client:客户端浏览器与操作系统识别信息(如
"Chrome 128 on macOS 14"),如果是当前测试会话还会显示绿色current session徽标。 - Location:基于登录 IP 解析的国家/地区名称(无法解析时显示
Unknown)。 - IP:客户端源 IP 地址(支持一键复制)。
- 安全设计说明:为防止会话劫持,Console 页面绝不展示任何 Session Token / Secret 明文,也不展示具体过期时间戳。
- Client:客户端浏览器与操作系统识别信息(如
- 强制登出操作:
- 单设备下线:点击目标设备行右侧的 Sign out,立即销毁该设备上的登录态。
- 全设备强制下线:点击列表右上角的 Sign out all sessions 并在弹窗中确认,立即注销该用户在所有终端设备上的全部会话(常用于账号疑似被盗或员工离职应急处置)。
(6)Activity 页签:用户级安全审计轨迹
- 按时间倒序展示与该用户相关的全部关键操作审计日志(Audit Logs),涵盖登录成功/失败、密码修改、邮箱更新、会话销毁等事件,包含触发时间、事件名称、客户端环境与源 IP,满足企业合规审计要求。
常见问题与排障
Q1:在 Console 为用户添加标签时提示格式错误,为什么不能输入 vip-customer 或 tier_1?
原因分析: Agentbase 的用户标签(Labels)在服务端有严格的字符集校验:**仅允许纯英文字母与数字字符(a-z、A-Z、0-9)**,不支持连字符(-)、下划线(_)、空格或中文字符。
解决方案: 请使用纯字母数字组合命名标签,例如使用 vip、vipcustomer、tier1 或 architect。如果需要存储包含特殊字符或中文的复杂业务属性(如所属公司名称 "远航金融科技" 或部门编码 "dept-01"),请将其存入 Overview → Preferences(键值偏好) 中。
Q2:管理员在用户详情页直接修改了用户的 Email,系统会向新邮箱发送验证链接吗?
回答: 不会。管理员在 Console 的 Overview → Email 卡片中修改邮箱并点击 Update 属于管理态直接覆写操作,不会触发邮件发送。修改后,如果管理员确认该新邮箱真实有效,可在上方的 Status 卡片中点击 Verify → Verify email 直接将其状态切换为 Verified;若希望触发真实的验证邮件流程,应由终端用户在客户端调用 account.createVerification(redirectUrl)。
Q3:为什么删除某个用户后,业务数据库表 customer_tickets 中由该用户创建的工单记录还在?
原因分析: 在 Auth → Users 中执行 Delete user 会级联永久删除该用户在 Auth 与 Messaging 域内的全部附属资源(包括 Sessions、Memberships、Identities、Targets),但不会自动物理删除业务数据库(Databases)或存储桶(Storage)中的业务行与文件,以防止因误删单个客户账号而导致企业核心业务工单或财务台账丢失。
解决方案:
- 该用户被删除后,原工单行上的
Role.user('user_zhangwei_001')权限自然失效(因为该 User ID 的有效会话已不存在),不会产生越权风险。 - 如果业务上要求在注销用户时同步清理或匿名化其业务表数据,可通过监听
users.*.deleteWebhook / Event 触发器(在项目 Settings → Webhooks 或 云函数 Functions 中配置)自动执行关联业务数据清洗。
相关文档
- 认证概览(Auth Overview):了解 Session、JWT、API Key 三种认证方式及
Role.user()、Role.label()权限表达式。 - 团队管理(Teams):将终端用户编入业务团队并授予自定义团队角色。
- 认证安全策略(Security):配置密码历史、弱密码字典校验、并发会话数上限与 MFA 策略。
- 消息目标(Targets):查看与管理用户自动生成的 Email / SMS 通知目标及 Push 推送目标。
- 用户画像(Profiles):查看基于 Auth 用户 ID 自动构建的智能体长期记忆画像。