AgentbaseDocs
文档目录

团队管理

功能概述

团队管理(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 授权的完整架构:

flowchart TB
    subgraph OrgLayer["控制台治理平面 (Organization Plane — 管理 Console)"]
        Org["组织: Agentbase 企业智能中台<br/>(ID: 69c6d1aa00062e6bb60)"]
        OrgMembers["组织成员 (Organization Members)<br/>固定角色: Owner / Admin / Developer / Editor / Billing / Analyst"]
        Org --> OrgMembers
    end

    subgraph ProjectLayer["项目业务平面 (Project Plane: enterprise-ai-hub-210 — 面向终端用户)"]
        subgraph Users["项目终端用户 (Auth Users)"]
            U1["张伟 (user_zhangwei_001)<br/>企业 VIP 客户技术总监"]
            U2["李娜 (user_lina_002)<br/>高级技术支持专家"]
        end

        subgraph Teams["项目终端用户团队 (Auth Teams & Custom Roles)"]
            T1["VIP客户技术支持组<br/>(ID: team_support_ops)<br/>自定义角色: admin, support_lead, vip_guest"]
            T2["企业知识库治理专家组<br/>(ID: team_kb_governance)<br/>自定义角色: owner, reviewer, editor"]
            T3["AI智能体与模型平台组<br/>(ID: team_ai_platform)<br/>自定义角色: architect, operator"]
        end

        subgraph ACL["项目内资源级权限绑定 (Resource ACLs)"]
            DBTickets["数据库表: customer_tickets<br/>read: Role.team('team_support_ops')<br/>update/delete: Role.team('team_support_ops', 'admin')"]
            BucketKB["存储桶: kb_enterprise_docs<br/>read: Role.team('team_kb_governance')<br/>write: Role.team('team_kb_governance', 'reviewer')"]
        end

        U1 -->|Membership: vip_guest| T1
        U2 -->|Membership: admin, support_lead| T1
        U2 -->|Membership: reviewer| T2

        T1 --> DBTickets
        T2 --> BucketKB
    end

    OrgMembers -.->|通过 Console 或 Server SDK 治理| Teams

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. 创建与管理团队(Create team)

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 中添加团队成员操作步骤

通过 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 服务器或平台默认邮件通道受限,邮件发送就会失败。

解决方案:


相关文档