Docs
文档目录

用户管理

功能概述

用户管理用于管理项目中的终端用户账号。管理员可以在控制台的 认证 → 用户 页面或通过服务端 SDK 查询和管理用户、标签、偏好以及关联会话等信息;具体可执行的操作取决于当前账号权限。

通过将终端用户的基础属性与业务扩展元数据(如 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)组成。

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

以下为虚构的用户数据示例,用于说明字段,不代表任何环境的实际数据:

属性维度示例用户 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 点击 创建用户 或通过 API 创建用户时,只要填写了 Email,系统会自动为该用户生成一条 Email 类型的 Target;若同时填写了 Phone,还会自动生成一条 SMS 类型的 Target,直接供 消息推送(Messaging) 与 消息目标(Targets) 订阅主题和发送通知。

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

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


功能详解与操作指南

1. 检索与浏览用户列表

进入 认证 → 用户 页面后,控制台展示项目终端用户的分页列表:

测试项目中的用户列表

图:2.12.0 测试项目中的用户列表,用户为合成示例。

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

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

  1. 在认证 → 用户页面点击创建用户,打开表单。

  2. 按用户的登录方式填写表单;用户 ID 留空时由系统生成。创建结果与校验要求以实际服务响应为准:

弹窗字段必填性校验规则与输入示例
Name可选用户显示名称,最长 128 字符。示例:张伟
Email可选合法电子邮箱格式;服务端入库前统一转换为小写,且在同一项目内必须唯一。示例:zhangwei@customer-corp.example.com
Phone可选必须以 + 开头并带国际区号,+ 后最多 15 位数字。示例:+8613800138001
Password可选长度至少 8 个字符(服务端校验范围为 8–256 字符)。若项目在 安全策略 中启用了密码字典(Password dictionary)或禁止包含个人信息(Disallow personal data),密码还需通过对应合规校验。
User ID可选可直接在用户 ID 输入框填写自定义 ID;留空时自动生成。示例:user_zhangwei_001。
  1. 点击确认提交。创建成功后进入该用户的详情页(/auth/user-{userId});若失败,按页面错误信息检查输入和权限。

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

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

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

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

卡片名称核心功能与操作步骤生效机制与安全边界
Status(账户状态与验证)1. 点击 封禁账户 立即封禁账号(已封禁时显示 解封账户 解封)。
2. 点击 验证(或下拉菜单)可分别将 Email 和 Phone 标记为 验证(已验证)或 取消验证。
封禁账号立即生效,该用户的所有既有会话将无法再通过权限校验。手动修改验证状态不会向用户发送验证邮件或短信。
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(键值偏好)点击 添加偏好 逐行输入 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) 及 删除验证器 按钮。当用户丢失手机导致无法生成 TOTP 验证码时,管理员可点击 删除验证器 移除其 TOTP 因子(该删除操作不可逆,移除后用户需重新绑定)。
Delete user(删除用户)点击底部红色 删除 按钮,在确认弹窗中核对信息后确认删除。永久且不可逆:彻底删除该用户及其关联的全部 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 属于管理态直接覆写操作,不会触发邮件发送。修改后,如果管理员确认该新邮箱真实有效,可在上方的 状态 卡片中点击 Verify → Verify email 直接将其状态切换为 Verified;若希望触发真实的验证邮件流程,应由终端用户在客户端调用 account.createVerification(redirectUrl)。

Q3:为什么删除某个用户后,业务数据库表 customer_tickets 中由该用户创建的工单记录还在?

原因分析: 在 认证 → 用户 中执行 删除用户 会级联永久删除该用户在 Auth 与 Messaging 域内的全部附属资源(包括 Sessions、Memberships、Identities、Targets),但不会自动物理删除业务数据库(Databases)或存储桶(Storage)中的业务行与文件,以防止因误删单个客户账号而导致企业核心业务工单或财务台账丢失。

解决方案:


相关文档