Docs
文档目录

团队管理

功能概述

团队管理(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_opsVIP客户技术支持组{"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_platformAI智能体与模型平台组{"gatewayId": "gw_7194685489feb1e169548619", "primaryModel": "qwen-plus"}architect(AI 架构师)、operator(评测工程师)绑定存储桶 agent_multimedia_bucket 及评测数据集表,负责多模态评测样本上传与智能体对话轨迹分析。

角色、入口与关联关系

控制台入口与权限要求

与其他模块的关联关系

  1. 与用户管理(Auth Users)双向同步:在 Auth → Teams → 团队详情 → Members 中添加或移除成员后,对应用户在 Auth → Users → 用户详情 → Memberships 页签中的团队列表会实时同步更新。

  2. 与邮件模板(Auth Templates)联动:当通过客户端 SDK 或在未开启管理员直接入组时发起邮件邀请,系统会渲染 Auth → Templates 中的 Invite user 模板(包含 {{team}}、{{user}}、{{project}}、{{redirect}} 变量)向受邀人发送确认邮件。

  3. 与数据库(Databases)及存储(Storage)联动:团队 ID 与自定义角色名称直接构成 team:<TEAM_ID> 和 team:<TEAM_ID>/<ROLE> 权限主体,在表级权限、行级安全(Row Security)、桶级权限与文件级安全(File Security)中实时生效。


功能详解与操作指南

1. 创建与管理团队(Create team)

  1. 进入项目 Auth → Teams 页签,页面展示当前项目下的所有团队(表格列包括 Name 团队名称、Members 成员数量、Created 创建时间,支持顶部按名称关键词搜索)。

  2. 点击右上角 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 字符,且不能以特殊字符开头。

  3. 点击 Create 按钮完成创建。系统弹出通知 "{name} has been created" 并自动进入该团队的 Overview 详情页。

2. 团队详情页配置(Overview / Members / Activity)

进入团队详情页(如 /auth/teams/team-team_support_ops)后,可通过三个页签进行精细化管理:

页签名称卡片 / 区域功能说明与操作规范
Overview基本信息概览顶部展示团队 ID(可复制)、当前成员总数(Members)与创建时间(Created)。
OverviewName(修改团队名)修改团队显示名称后点击 Update。修改显示名称不会改变 Team ID,因此不会影响任何已绑定 team:<TEAM_ID> 的数据库行或存储桶权限。
OverviewPreferences(团队偏好)维护团队级共享 JSON 键值配置(如 slaTargetMinutes: "15"、defaultKbId: "kb_enterprise_support")。团队内任意成员可通过客户端 SDK 调用 teams.getPrefs(teamId) 读取本团队共享配置。
OverviewDelete team(删除团队)位于底部危险区域(Danger zone)。点击 Delete 并在弹窗确认后,永久删除该团队及其全部成员关系(Memberships)与团队偏好,操作不可逆(详见下方风险提示)。
Members成员列表与管理展示所有成员的 Name(点击跳转至该用户详情页)、Roles(自定义角色列表)与 Joined(加入时间),支持点击 Create membership 添加成员或行内移除成员。
Activity团队审计日志按时间倒序记录团队创建、改名、偏好修改、成员加入/移出及角色调整等全量审计事件。

3. 添加团队成员与自定义角色分配(Create membership)

向团队中添加成员共有两种路径:Console / Server SDK 管理态直接添加(或发送邀请) 与 客户端 SDK 终端用户自助邀请流程。

在 Console 中添加团队成员操作步骤

  1. 进入目标团队详情页(如 team_support_ops),切换到 Members 页签,点击右上角 Create membership 按钮。

  2. 在弹窗中填写成员信息:

    • Email(必填):输入被添加用户的邮箱地址(如李娜的 lina.support@agentbase-ops.example.com 或张伟的 zhangwei@customer-corp.example.com)。若该邮箱尚不存在对应的 Auth 用户,系统会自动以此邮箱创建新用户记录。

    • Name(可选):输入成员显示名称(如 李娜)。

    • Roles(可选,强烈建议配置):在标签输入框中输入自定义角色名称并按回车确认。角色名称完全自定义,不受任何预设枚举限制,可同时输入多个角色(例如为李娜同时添加 admin 和 support_lead 两个角色)。

  3. 提交后,成员关系即创建完成(若通过客户端邀请流触发,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') 的数据库行和存储桶文件会怎样?

原因分析与影响:

Q3:为什么在客户端调用 teams.createMembership() 邀请新成员时报错 SMTP Disabled 或收件人收不到邀请邮件?

原因分析: 当从客户端 SDK 发起团队成员邀请时,Agentbase 必须向被邀请人发送包含确认链接({{redirect}})的邀请邮件,被邀请人点击确认后 Membership 状态才从待确认变为已生效(confirm: true)。如果项目尚未配置自定义 SMTP 服务器或平台默认邮件通道受限,邮件发送就会失败。

解决方案:

  1. 生产环境标准做法:在项目 Settings → SMTP 中配置企业自定义 SMTP 服务,并在 邮件模板(Templates) 中检查 Invite user 模板。

  2. 后端免邮件直接入组方案:如果您的业务由企业后端统一管理团队成员(无需用户点击邮件确认),请使用持有 teams.write Scope 的 Server SDK(API Key 路径) 调用 teams.createMembership()——在 Server API Key 路径下创建的成员关系会直接标记为已确认(confirm: true)并立即生效,无需依赖邮件确认流。


相关文档