团队管理

ONE SDK 支持基于角色的访问控制以实现团队协作。项目所有者可以通过仪表板或 OneEngineClient 上的 Admin API 方法来邀请团队成员、分配角色和微调权限。

客户端设置

团队管理需要管理员级别的身份验证。使用 secretKey 创建服务端客户端。

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  baseUrl: process.env.ONE_ENGINE_URL!,
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

角色

每个团队成员被分配三个角色之一。每个角色都有一组预定义的权限。

角色	说明	典型用途
admin	对所有项目资源、设置、团队管理和计费拥有完全访问权限。	项目所有者、首席工程师。
developer	对 API 密钥、Webhook 和用量数据拥有读写权限。无法管理团队成员或计费。	后端和前端工程师。
viewer	对项目数据、用量分析和 Webhook 日志拥有只读权限。	QA、产品经理、利益相关者。

角色对比矩阵

功能	admin	developer	viewer
查看项目设置	是	是	是
更新项目设置	是	否	否
查看 API 密钥	是	是	否
重新生成 API 密钥	是	是	否
查看用量分析	是	是	是
创建 Webhook	是	是	否
管理 Webhook	是	是	否
查看 Webhook 日志	是	是	是
邀请团队成员	是	否	否
移除团队成员	是	否	否
更改成员角色	是	否	否
管理计费	是	否	否
删除项目	是	否	否

类型

Permission

定义授予用户或角色的单个权限。

interface Permission {
  id: string;
  action: PermissionAction;
  scope: PermissionScope;
  resource?: string;               // Optional resource ID for fine-grained access
}

type PermissionAction =
  | 'read'
  | 'write'
  | 'delete'
  | 'manage';

PermissionScope

定义权限适用的资源范围。

type PermissionScope =
  | 'project'
  | 'project.settings'
  | 'project.keys'
  | 'project.usage'
  | 'project.webhooks'
  | 'project.team'
  | 'project.billing'
  | 'admin.users'
  | 'admin.projects';

TeamMember

表示项目团队中的一个用户。

interface TeamMember {
  id: string;
  userId: string;
  projectId: string;
  email: string;
  displayName?: string;
  role: 'admin' | 'developer' | 'viewer';
  permissions: Permission[];
  status: 'active' | 'invited' | 'suspended';
  invitedAt: string;               // ISO-8601
  joinedAt?: string;               // ISO-8601, null if still pending
  lastActiveAt?: string;           // ISO-8601
}

管理员操作

以下 OneEngineClient 方法提供管理员级别的用户和团队管理。

方法	说明
`adminListUsers(options?)`	列出项目中的所有用户（仅限管理员）。
`adminGetUser(userId)`	获取特定用户的详细信息。
`adminUpdateUser(userId, updates)`	更新用户的角色、状态或权限。
`adminInviteUser(input)`	通过电子邮件邀请新团队成员。
`adminRemoveUser(projectId, userId)`	从项目团队中移除用户。

adminListUsers

列出项目的所有团队成员，支持可选筛选。

interface AdminListUsersOptions {
  projectId: string;
  role?: 'admin' | 'developer' | 'viewer';
  status?: 'active' | 'invited' | 'suspended';
  page?: number;                   // 1-based (default: 1)
  limit?: number;                  // Items per page (default: 20, max: 100)
  search?: string;                 // Search by email or display name
}

const res = await engine.adminListUsers({
  projectId: 'proj_abc123',
  role: 'developer',
  status: 'active',
});

if (res.success) {
  for (const member of res.data) {
    console.log(`${member.email} -- ${member.role} (${member.status})`);
  }
}

adminGetUser

获取单个团队成员的完整详情，包括其权限。

const res = await engine.adminGetUser('usr_xyz789');

if (res.success) {
  const user: TeamMember = res.data;
  console.log('Email:', user.email);
  console.log('Role:', user.role);
  console.log('Status:', user.status);
  console.log('Permissions:');
  for (const perm of user.permissions) {
    console.log(`  ${perm.action} on ${perm.scope}`);
  }
}

adminUpdateUser

更新团队成员的角色、状态或权限。只有管理员可以执行此操作。

interface AdminUpdateUserParams {
  role?: 'admin' | 'developer' | 'viewer';
  status?: 'active' | 'suspended';
  permissions?: Permission[];
  displayName?: string;
}

// Promote a developer to admin
const res = await engine.adminUpdateUser('usr_xyz789', {
  role: 'admin',
});

if (res.success) {
  console.log('Updated role to:', res.data.role);
}

// Suspend a user
const suspendRes = await engine.adminUpdateUser('usr_xyz789', {
  status: 'suspended',
});

if (suspendRes.success) {
  console.log('User suspended:', suspendRes.data.email);
}

邀请团队成员

从仪表板邀请

在 dashboard.one23.io 上导航到您的项目。
在侧边栏中进入 Team。
点击 Invite Member。
输入电子邮件地址并选择角色（admin、developer 或 viewer）。
点击 Send Invite。

被邀请者将收到一封包含加入项目链接的电子邮件。在他们接受之前，其状态为 invited。

从 SDK 邀请

interface AdminInviteUserInput {
  projectId: string;
  email: string;
  role: 'admin' | 'developer' | 'viewer';
  displayName?: string;
  message?: string;                // Optional personal message in the invite email
}

const res = await engine.adminInviteUser({
  projectId: 'proj_abc123',
  email: 'alice@company.com',
  role: 'developer',
  displayName: 'Alice Chen',
  message: 'Welcome to the team! You have been granted developer access.',
});

if (res.success) {
  console.log('Invite sent to:', res.data.email);
  console.log('Status:', res.data.status);  // 'invited'
  console.log('Invite ID:', res.data.id);
}

管理权限

虽然角色提供了一组便捷的默认权限，但管理员可以为个别用户分配细粒度的权限。

授予自定义权限

const res = await engine.adminUpdateUser('usr_xyz789', {
  role: 'developer',
  permissions: [
    { id: 'perm_1', action: 'read', scope: 'project.settings' },
    { id: 'perm_2', action: 'read', scope: 'project.usage' },
    { id: 'perm_3', action: 'write', scope: 'project.webhooks' },
    { id: 'perm_4', action: 'read', scope: 'project.webhooks' },
    { id: 'perm_5', action: 'read', scope: 'project.keys' },
    { id: 'perm_6', action: 'write', scope: 'project.keys' },
  ],
});

if (res.success) {
  console.log('Custom permissions applied for:', res.data.email);
}

查看用户权限

const res = await engine.adminGetUser('usr_xyz789');

if (res.success) {
  console.log(`Permissions for ${res.data.email} (${res.data.role}):`);

  const grouped = res.data.permissions.reduce((acc, perm) => {
    const key = perm.scope;
    if (!acc[key]) acc[key] = [];
    acc[key].push(perm.action);
    return acc;
  }, {} as Record<string, string[]>);

  for (const [scope, actions] of Object.entries(grouped)) {
    console.log(`  ${scope}: ${actions.join(', ')}`);
  }
}

移除团队成员

从仪表板移除

导航到 Team，找到该成员，点击菜单图标，然后选择 Remove from project。

从 SDK 移除

const res = await engine.adminRemoveUser('proj_abc123', 'usr_xyz789');

if (res.success) {
  console.log('User removed from the project.');
}

注意

移除团队成员会立即撤销其对项目的所有访问权限。如果该用户有任何活跃会话，他们的下一次 API 调用将收到 403 Forbidden。

完整示例

以下脚本演示了邀请团队成员、验证其状态以及在他们加入后更新其角色。

team-setup.ts
import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  baseUrl: process.env.ONE_ENGINE_URL!,
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

async function onboardTeamMember() {
  const projectId = 'proj_abc123';

  // 1. Invite a new developer
  const inviteRes = await engine.adminInviteUser({
    projectId,
    email: 'bob@company.com',
    role: 'developer',
    displayName: 'Bob Smith',
    message: 'You are invited to collaborate on our trading platform.',
  });

  if (!inviteRes.success) {
    console.error('Invite failed:', inviteRes.error);
    return;
  }

  const memberId = inviteRes.data.id;
  console.log('Invite sent. Member ID:', memberId);

  // 2. List all team members
  const listRes = await engine.adminListUsers({ projectId });

  if (listRes.success) {
    console.log(`\nTeam (${listRes.data.length} members):`);
    for (const member of listRes.data) {
      console.log(`  ${member.email} -- ${member.role} (${member.status})`);
    }
  }

  // 3. Check the invited user's details
  const userRes = await engine.adminGetUser(inviteRes.data.userId);

  if (userRes.success) {
    console.log('\nInvited user details:');
    console.log('  Email:', userRes.data.email);
    console.log('  Role:', userRes.data.role);
    console.log('  Status:', userRes.data.status);
  }

  // 4. After they accept, promote to admin
  // (In practice, you would check userRes.data.status === 'active' first)
  const updateRes = await engine.adminUpdateUser(inviteRes.data.userId, {
    role: 'admin',
  });

  if (updateRes.success) {
    console.log('\nPromoted to admin:', updateRes.data.email);
  }
}

onboardTeamMember();

下一步

仪表板概览 -- 返回仪表板功能摘要。
API 密钥 -- 管理团队成员使用的凭据。
用量与分析 -- 查看团队活动和 API 消耗。
Webhook 配置 -- 设置团队事件通知。

客户端设置​

角色​

角色对比矩阵​

类型​

Permission​

PermissionScope​

TeamMember​

管理员操作​

adminListUsers​

adminGetUser​

adminUpdateUser​

邀请团队成员​

从仪表板邀请​

从 SDK 邀请​

管理权限​

授予自定义权限​

查看用户权限​

移除团队成员​

从仪表板移除​

从 SDK 移除​

完整示例​

下一步​