团队管理
功能概述
团队管理(Teams)是 Agentbase 面向项目内终端用户(End Users)提供的多租户分组与基于角色的访问控制(RBAC)能力。在构建企业级 SaaS、客户服务门户与多部门协同智能体应用(如示例项目 企业智能客服与知识中台,Project ID:enterprise-ai-hub-210)时,单靠“按个人用户 ID 授权(Role.user(id))”或“向全体注册用户开放(Role.users())”往往难以满足复杂的组织协作诉求。通过 Auth → Teams,企业可以将项目内的终端用户编入不同的业务团队(如 team_support_ops VIP 客户技术支持组、team_kb_governance 企业知识库治理专家组、team_ai_platform AI 智能体与模型平台组),并在每个团队内部为成员分配完全自定义的角色标签(如 owner、admin、support_lead、reviewer、auditor)。
当终端用户加入团队并获得相应团队角色后,Agentbase 的权限引擎会自动将 team:<TEAM_ID> 与 team:<TEAM_ID>/<ROLE> 注入该用户的运行时有效角色集(Effective Roles)。无论是结构化数据库表(如 enterprise_biz_db 中的客户工单表 customer_tickets)、文件存储桶(如 kb_enterprise_docs 和 agent_multimedia_bucket),还是消息推送主题(Messaging Topics),都可以直接绑定 Role.team('team_support_ops') 或 Role.team('team_support_ops', 'admin'),实现“人在团队即享权限、移出团队权限立收”的零信任数据治理。
核心概念与架构
在 Agentbase 中,初学者最容易混淆的概念是 项目内终端用户团队(Auth Teams) 与 控制台组织成员(Organization Members)。下图清晰展示了两者的隔离边界,以及 Auth Teams 在项目内驱动数据级 RBAC 授权的完整架构:
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
Auth Teams 与组织成员(Organization Members)本质区别对比
| 对比维度 | 项目终端用户团队(Auth Teams,本文档范围) | 控制台组织成员(Organization Members) |
|---|---|---|
| 管理对象 | 业务应用中的终端用户(Auth Users,如客户 user_zhangwei_001、客服坐席 user_lina_002) | 登录并使用 Agentbase Console 的平台研发、运维与管理员账号 |
| 核心用途 | 控制业务应用内的数据访问权限(数据库行级 ACL、存储桶与文件 ACL、消息订阅权限) | 控制云平台基础设施治理权限(创建项目、配置 AI 网关、管理数据库表结构、查看账单) |
| 角色体系 | 100% 完全自定义字符串标签(如 admin、support_lead、vip_guest、reviewer),一个成员在同一团队内可同时持有多个角色 | 系统预设 6 种固定角色:Owner、Admin、Developer、Editor、Billing、Analyst |
| 管理入口 | 项目侧栏 Auth → Teams(路由 /console/project-{region}-{project}/auth/teams) | 组织顶栏或侧栏 Members 页(详见 组织与账号中心) |
| API 端点 | /v1/teams(客户端与服务端均可按策略调用) | /v1/organizations/{organizationId}/memberships(仅控制台组织管理域) |
典型业务团队规划示例(enterprise-ai-hub-210)
在示例项目 企业智能客服与知识中台 中,围绕智能客服工单流转、知识库文档治理与 AI 网关运维,规划了以下三个核心业务团队:
团队 ID($id) | 团队名称(name) | 团队偏好(prefs)示例 | 团队内自定义角色规划 | 绑定的业务资源与权限范围 |
|---|---|---|---|---|
team_support_ops | VIP客户技术支持组 | {"slaTargetMinutes": "15", "escalationChannel": "dingtalk_vip"} | admin(组长)、support_lead(一线专家)、vip_guest(客户代表) | 绑定数据库 enterprise_biz_db 的 customer_tickets 表:Role.team('team_support_ops') 可读全组工单,Role.team('team_support_ops', 'admin') 可修改工单状态与指派处理人。 |
team_kb_governance | 企业知识库治理专家组 | {"defaultKbId": "kb_enterprise_support", "requireReview": "true"} | owner(知识库负责人)、reviewer(审核专家)、contributor(文档贡献者) | 绑定存储桶 kb_enterprise_docs:Role.team('team_kb_governance', 'reviewer') 拥有上传与更新 SOP 文档(如 智能客服SOP标准作业手册.md)的写权限。 |
team_ai_platform | AI智能体与模型平台组 | {"gatewayId": "gw_7194685489feb1e169548619", "primaryModel": "qwen-plus"} | architect(AI 架构师)、operator(评测工程师) | 绑定存储桶 agent_multimedia_bucket 及评测数据集表,负责多模态评测样本上传与智能体对话轨迹分析。 |
角色、入口与关联关系
控制台入口与权限要求
导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 左侧导航栏 Auth → 点击顶部 Teams 页签。路由地址:
团队列表页:
/console/project-{region}-{project}/auth/teams团队详情页:
/console/project-{region}-{project}/auth/teams/team-{teamId}(含 Overview / Members / Activity 三个子页签)
操作权限门禁:
浏览团队列表、查看团队成员与审计记录需要
teams.read权限(组织角色owner、admin、developer、editor、analyst)。创建团队、修改团队名称与偏好、邀请/移除成员、修改成员角色及删除团队需要
teams.write权限(组织角色owner、admin、developer、editor)。
与其他模块的关联关系
与用户管理(Auth Users)双向同步:在 Auth → Teams → 团队详情 → Members 中添加或移除成员后,对应用户在 Auth → Users → 用户详情 → Memberships 页签中的团队列表会实时同步更新。
与邮件模板(Auth Templates)联动:当通过客户端 SDK 或在未开启管理员直接入组时发起邮件邀请,系统会渲染 Auth → Templates 中的 Invite user 模板(包含
{{team}}、{{user}}、{{project}}、{{redirect}}变量)向受邀人发送确认邮件。与数据库(Databases)及存储(Storage)联动:团队 ID 与自定义角色名称直接构成
team:<TEAM_ID>和team:<TEAM_ID>/<ROLE>权限主体,在表级权限、行级安全(Row Security)、桶级权限与文件级安全(File Security)中实时生效。
功能详解与操作指南
1. 创建与管理团队(Create team)
进入项目 Auth → Teams 页签,页面展示当前项目下的所有团队(表格列包括 Name 团队名称、Members 成员数量、Created 创建时间,支持顶部按名称关键词搜索)。
点击右上角 Create team 按钮,打开创建团队弹窗:
Name(必填):输入具有明确业务含义的团队名称(最长 128 字符),例如
VIP客户技术支持组。Team ID(可选):默认由系统自动生成唯一 ID。建议点击 Team ID 标签展开自定义输入框,填入语义化标识(如
team_support_ops、team_kb_governance、team_ai_platform)。自定义 ID 仅允许a-z、A-Z、0-9、句点(.)、连字符(-)、下划线(_),最长 36 字符,且不能以特殊字符开头。
点击 Create 按钮完成创建。系统弹出通知
"{name} has been created"并自动进入该团队的 Overview 详情页。
2. 团队详情页配置(Overview / Members / Activity)
进入团队详情页(如 /auth/teams/team-team_support_ops)后,可通过三个页签进行精细化管理:
| 页签名称 | 卡片 / 区域 | 功能说明与操作规范 |
|---|---|---|
| Overview | 基本信息概览 | 顶部展示团队 ID(可复制)、当前成员总数(Members)与创建时间(Created)。 |
| Overview | Name(修改团队名) | 修改团队显示名称后点击 Update。修改显示名称不会改变 Team ID,因此不会影响任何已绑定 team:<TEAM_ID> 的数据库行或存储桶权限。 |
| Overview | Preferences(团队偏好) | 维护团队级共享 JSON 键值配置(如 slaTargetMinutes: "15"、defaultKbId: "kb_enterprise_support")。团队内任意成员可通过客户端 SDK 调用 teams.getPrefs(teamId) 读取本团队共享配置。 |
| Overview | Delete team(删除团队) | 位于底部危险区域(Danger zone)。点击 Delete 并在弹窗确认后,永久删除该团队及其全部成员关系(Memberships)与团队偏好,操作不可逆(详见下方风险提示)。 |
| Members | 成员列表与管理 | 展示所有成员的 Name(点击跳转至该用户详情页)、Roles(自定义角色列表)与 Joined(加入时间),支持点击 Create membership 添加成员或行内移除成员。 |
| Activity | 团队审计日志 | 按时间倒序记录团队创建、改名、偏好修改、成员加入/移出及角色调整等全量审计事件。 |
3. 添加团队成员与自定义角色分配(Create membership)
向团队中添加成员共有两种路径:Console / Server SDK 管理态直接添加(或发送邀请) 与 客户端 SDK 终端用户自助邀请流程。
在 Console 中添加团队成员操作步骤
进入目标团队详情页(如
team_support_ops),切换到 Members 页签,点击右上角 Create membership 按钮。在弹窗中填写成员信息:
Email(必填):输入被添加用户的邮箱地址(如李娜的
lina.support@agentbase-ops.example.com或张伟的zhangwei@customer-corp.example.com)。若该邮箱尚不存在对应的 Auth 用户,系统会自动以此邮箱创建新用户记录。Name(可选):输入成员显示名称(如
李娜)。Roles(可选,强烈建议配置):在标签输入框中输入自定义角色名称并按回车确认。角色名称完全自定义,不受任何预设枚举限制,可同时输入多个角色(例如为李娜同时添加
admin和support_lead两个角色)。
提交后,成员关系即创建完成(若通过客户端邀请流触发,Agentbase 会向该邮箱发送邀请确认邮件,收件人点击邮件中的确认链接完成加入)。
通过 Server SDK(agentbase-node-sdk@2.10.0)直接编排团队与成员角色
在企业自动化开通流程(如 HR 系统或 CRM 系统同步组织架构)中,后端服务可使用持有 teams.write 权限的 API Key 直接创建团队并管理成员角色:
import { Client, Teams } from 'agentbase-node-sdk'; // 版本固定 @2.10.0
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('enterprise-ai-hub-210')
.setKey('<APPBASE_API_KEY>');
const teams = new Teams(client);
// 1. 创建“企业知识库治理专家组”团队
await teams.create(
'team_kb_governance',
'企业知识库治理专家组',
['owner', 'reviewer'] // 创建者默认角色(Server API 调用时作为初始角色模板)
);
// 2. 将高级支持专家李娜(user_lina_002)加入 VIP 客户技术支持组并授予 admin 与 support_lead 角色
const membership = await teams.createMembership(
'team_support_ops',
['admin', 'support_lead'],
'lina.support@agentbase-ops.example.com', // 成员邮箱
'user_lina_002', // 指定已有 User ID
undefined, // 手机号(可选)
'https://appbuild.oceanbase.com/console/invite', // 邀请回跳 URL
'李娜' // 成员名称
);
// 3. 动态升级或调整成员在团队中的角色(立即影响其数据访问权限)
await teams.updateMembership(
'team_support_ops',
membership.$id,
['admin', 'support_lead', 'auditor']
);4. 团队级数据权限(Team-Scoped Permissions)最佳实践
在设计多租户或多部门协同的数据表(如 customer_tickets)和存储桶(如 kb_enterprise_docs)时,推荐遵循以下三层团队角色授权规范:
| 业务动作 | 推荐授权角色表达式 | 实际效果说明 |
|---|---|---|
| 全组成员只读共享 | Permission.read(Role.team('team_support_ops')) | 只要用户是 team_support_ops 的已确认成员(无论其 Roles 为空还是 vip_guest、support_lead),均可读取该工单或文档。 |
| 一线工程师处理与更新 | Permission.update(Role.team('team_support_ops', 'support_lead')) | 仅在 team_support_ops 中持有 support_lead 角色的成员可更新工单回复内容,普通 vip_guest 成员无法篡改。 |
| 团队管理员高危删除与归档 | Permission.delete(Role.team('team_support_ops', 'admin')) | 仅在 team_support_ops 中持有 admin 角色的团队负责人可执行删除操作,实现团队内部的最小权限职责分离。 |
常见问题与排障
Q1:用户在团队中被赋予了 admin 角色(如 team:team_support_ops/admin),他能登录 Agentbase Console 管理项目吗?
回答: 完全不能。Auth → Teams 中的团队与角色(哪怕命名为 owner 或 admin)100% 仅作用于项目内的业务数据权限(Databases / Storage / Messaging),与 Agentbase Console 的组织成员(Organization Members)没有任何交叉。项目终端用户无法使用其账号登录 Console,更无法修改项目基础设施配置。如需授权同事登录 Console 协同管理项目,请前往组织顶层的 组织与账号中心 邀请组织成员。
Q2:将某位成员从团队 team_support_ops 中移除(或删除整个团队)后,之前授权给 Role.team('team_support_ops') 的数据库行和存储桶文件会怎样?
原因分析与影响:
移除单个成员:立即生效。该用户的运行时有效角色集不再包含
team:team_support_ops及其子角色,其后续发起的任何针对customer_tickets或kb_enterprise_docs的读写请求都会因缺少匹配角色而被服务端拦截(返回401或在列表中自动过滤掉无权行)。删除整个团队:团队实体及其下属所有 Membership 记录被永久删除。原业务数据库行和存储桶文件本身不会被删除,但这些资源上残留的
team:team_support_ops权限项将不再匹配任何用户(除非未来管理员重新创建一个同 IDteam_support_ops的团队并重新添加成员)。
Q3:为什么在客户端调用 teams.createMembership() 邀请新成员时报错 SMTP Disabled 或收件人收不到邀请邮件?
原因分析: 当从客户端 SDK 发起团队成员邀请时,Agentbase 必须向被邀请人发送包含确认链接({{redirect}})的邀请邮件,被邀请人点击确认后 Membership 状态才从待确认变为已生效(confirm: true)。如果项目尚未配置自定义 SMTP 服务器或平台默认邮件通道受限,邮件发送就会失败。
解决方案:
生产环境标准做法:在项目 Settings → SMTP 中配置企业自定义 SMTP 服务,并在 邮件模板(Templates) 中检查 Invite user 模板。
后端免邮件直接入组方案:如果您的业务由企业后端统一管理团队成员(无需用户点击邮件确认),请使用持有
teams.writeScope 的 Server SDK(API Key 路径) 调用teams.createMembership()——在 Server API Key 路径下创建的成员关系会直接标记为已确认(confirm: true)并立即生效,无需依赖邮件确认流。
相关文档
认证概览(Auth Overview):全面了解
Role.team(id, role)权限表达式与身份鉴权架构。用户管理(Users):在单个用户详情的 Memberships 页签中核查其加入的所有团队。
认证安全策略(Security):通过 Memberships privacy 卡片控制团队成员之间是否相互可见姓名、邮箱与 MFA 状态。
邮件模板(Templates):定制团队邀请邮件(Invite user)的正文与跳转变量。
组织与账号中心:管理登录 Agentbase Console 的组织管理员与研发成员。
