Docs
文档目录

用户管理

功能概述

用户管理(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 内的六维数据模型与生命周期状态流转:

用户管理:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心概念与实战示例数据表

在 SIT 演示项目 enterprise-ai-hub-210 中,系统预置并管理了以下典型终端用户档案,贯穿智能客服工单、知识库检索与长期记忆提取全流程:

属性维度示例用户 1(企业 VIP 客户)示例用户 2(高级技术支持专家)字段约束与平台行为说明
User ID($id)user_zhangwei_001user_lina_002最长 36 字符,仅允许 a-z、A-Z、0-9、.、-、_,且首字符不能为特殊字符;留空时系统自动生成唯一 ID。
Name(姓名)张伟李娜最长 128 字符,支持中文与多语言字符;可在创建时留空并在后续随时更新。
Email(邮箱)zhangwei@customer-corp.example.comlina.support@agentbase-ops.example.com创建时自动转为全小写,在同一项目内强制唯一(冲突时返回 USER_EMAIL_ALREADY_EXISTS)。
Phone(手机号)+8613800138001+8613900139002必须遵循 E.164 标准:以 + 开头并附带国际国家码,+ 后最多 15 位纯数字。
Status(状态)Verified(邮箱与手机已验证)Verified(邮箱已验证)包含账户启用态(Active vs blocked 红色封禁徽标)以及邮箱/手机号各自的验证状态。
Labels(标签)vip, architectsupport, 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)。

角色、入口与关联关系

控制台入口与权限要求

与上下游模块的关联关系

  1. 自动创建消息目标(Targets):当管理员在 Console 点击 Create user 或通过 API 创建用户时,只要填写了 Email,系统会自动为该用户生成一条 Email 类型的 Target;若同时填写了 Phone,还会自动生成一条 SMS 类型的 Target,直接供 消息推送(Messaging) 与 消息目标(Targets) 订阅主题和发送通知。

  2. 团队成员关系(Memberships):用户在 Memberships 页签中展示其所属的所有项目团队(如 team_support_ops)及团队角色。将用户移出团队后,其对绑定了 Role.team(...) 的数据库表(customer_tickets)和存储桶(kb_enterprise_docs)的访问权限立即收回。

  3. 长期记忆与用户画像(Memory & Profiles):在 记忆管理 与 用户画像 中,系统直接以 Auth 用户的 User ID(如 user_zhangwei_001)聚合对话历史、长期事实(Facts)与经验蒸馏结果。


功能详解与操作指南

1. 检索与浏览用户列表

进入 Auth → Users 页面后,控制台展示项目内全部终端用户的分页列表(按创建时间倒序排列):

用户列表页(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

2. 创建终端用户(Create user)

在日常运营中,除了终端用户通过前端页面自助注册外,管理员可在 Console 手动创建内部支持账号或 VIP 客户账号:

  1. 在 Auth → Users 页面右上角点击 Create user 按钮,打开创建用户弹窗。

  2. 按下表规范填写字段(所有字段均为可选,留空可创建匿名或待绑定用户,但生产环境建议至少填写姓名、邮箱与密码):

弹窗字段必填性校验规则与输入示例
Name可选用户显示名称,最长 128 字符。示例:张伟
Email可选合法电子邮箱格式;服务端入库前统一转换为小写,且在同一项目内必须唯一。示例: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 字符,不能以特殊符号开头)。
  1. 点击 Create 提交。页面右上角弹出成功通知 "{name} has been created",并自动跳转至该用户的详情页(/auth/user-{userId})。

3. 用户详情页六大页签全解析

进入单个用户详情页(以 user_zhangwei_001 为例)后,可通过顶部六个页签完成全方位运维管理:

(1)Overview 页签:基础档案、标签、偏好与高危安全开关

Overview 页签由多张独立保存的配置卡片组成:

卡片名称核心功能与操作步骤生效机制与安全边界
Status(账户状态与验证)1. 点击 Block account 立即封禁账号(已封禁时显示 Unblock account 解封)。
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 页签:所属团队与角色管理

(3)Identities 页签:第三方 OAuth 关联身份

(4)Targets 页签:通知目标查看与清理

(5)Sessions 页签:在线设备监控与强制踢出

(6)Activity 页签:用户级安全审计轨迹


常见问题与排障

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)中的业务行与文件,以防止因误删单个客户账号而导致企业核心业务工单或财务台账丢失。

解决方案:


相关文档