跳到主要内容

角色管理

v3.0.0+

tcb role 命令自 v3.0.0 起提供。

tcb role 命令用于管理 CloudBase 环境中的访问控制角色，包括系统预设角色和自定义角色。

角色与权限的关系
  • 权限（Permission）：控制资源级别的读写访问（tcb permission）
  • 角色（Role）：绑定用户与策略，控制网关路由层的访问权限
  • 二者各司其职，共同构成 CloudBase 访问控制体系

系统预设策略​

创建自定义角色时可引用以下预设策略：

策略 Code效果说明
AdministratorAccessallow管理员全量访问
FunctionsAccessallow云函数访问权
StoragesAccessallow云存储访问权
CloudrunAccessallow云托管访问权
FunctionsDenydeny禁止访问云函数
StoragesDenydeny禁止访问云存储
CloudrunDenydeny禁止访问云托管

deny 策略优先于 allow，同时存在时以 deny 为准。

tcb role list​

查询环境下所有角色（系统角色 + 自定义角色）。

tcb role list [options]

参数​

参数说明默认值
-e, --env-id <envId>环境 ID—
--type <type>过滤类型：system / custom全部
--limit <n>返回条数上限20
--offset <n>跳过条数0
--detail同时显示成员列表和策略详情—
--json输出 JSON—

示例​

# 查看全部角色
tcb role list -e my-env-id

# 只看自定义角色
tcb role list --type custom -e my-env-id

# 显示详情（含成员和策略）
tcb role list --detail -e my-env-id

tcb role get​

查询指定角色的详细信息。

tcb role get --id <roleId> [options]
tcb role get --identity <identity> [options]
tcb role get --name <name> [options]

三种查询方式选其一（必填）：

参数说明
--id <roleId>按角色 ID 精确查询
--identity <identity>按角色标识精确查询
--name <name>按角色名称模糊查询
--detail显示成员和策略详情
-e, --env-id <envId>环境 ID

示例​

# 按 ID 查询
tcb role get --id 2032299359962361858 -e my-env-id

# 按标识查询（含详情）
tcb role get --identity administrator --detail -e my-env-id

tcb role create​

创建自定义角色。

tcb role create --name <name> --identity <identity> [options]

参数​

参数说明约束
--name <name>角色名称（必填）2–32 字符，中文/字母开头
--identity <identity>角色标识（必填，唯一）字母/数字/_-:@.
--description <desc>角色描述最多 255 字符
--users <uids>初始成员 UID，逗号分隔最多 100 个
--policies <json>策略 JSON 数组（见下方格式）最多 50 条
-e, --env-id <envId>环境 ID—

--policies 格式​

策略数组支持预设策略字符串和自定义策略对象混合使用：

[
  "FunctionsAccess",
  {
    "code": "custom_api",
    "name": "API 路径策略",
    "description": "仅允许访问 /api 路径",
    "effect": "allow",
    "expression": {
      "version": "1.0",
      "statement": [
        {
          "action": "functions:/api/*",
          "resource": "*",
          "effect": "allow"
        }
      ]
    }
  }
]

自定义策略对象字段：

字段说明必填
code策略唯一标识✅
effectallow 或 deny✅
name策略名称否
description描述否
expression策略表达式（含 version + statement 数组）否

statement 子语句字段：

字段说明示例
action<功能类型>:<路径>，* 表示全部functions:* / functions:/api/*
resource资源范围，* 表示全部*
effectallow 或 denyallow

功能类型枚举：storages / functions / cloudrun / model

示例​

# 最简创建
tcb role create --name 开发者 --identity developer -e my-env-id

# 创建并分配初始成员
tcb role create --name 开发者 --identity developer --users "1003,1005" -e my-env-id

# 使用预设策略
tcb role create --name 网关角色 --identity gateway_role \
  --policies '["FunctionsAccess","StoragesDeny"]' \
  -e my-env-id

# 混合使用预设 + 自定义策略
tcb role create \
  --name 全栈开发者 \
  --identity fullstack_dev \
  --policies '[
    "FunctionsAccess",
    {
      "code": "custom_api",
      "name": "API路径策略",
      "effect": "allow",
      "expression": {
        "version": "1.0",
        "statement": [{"action": "functions:/api/*", "resource": "*", "effect": "allow"}]
      }
    }
  ]' \
  --users "1003,1005,1007" \
  -e my-env-id

tcb role update​

更新角色信息（名称、描述、成员、策略）。

tcb role update --id <roleId> [options]
系统角色修改限制
  • 管理员角色：只能修改成员，不能修改策略
  • 注册用户/组织成员/匿名用户/所有用户：只能修改策略，不能修改成员
  • 所有系统角色：不可修改角色名称
  • 自定义角色：以上均可修改

参数​

参数说明
--id <roleId>角色 ID（必填）
--name <name>修改角色名称（自定义角色专用）
--description <desc>修改角色描述
--add-users <uids>添加成员，逗号分隔 UID
--remove-users <uids>移除成员，逗号分隔 UID
--add-policies <json>添加策略，格式同 role create --policies
--remove-policies <json>移除策略，传策略 code 字符串数组
-e, --env-id <envId>环境 ID

示例​

# 修改角色名称
tcb role update --id 2032299359962361858 --name "高级开发者" -e my-env-id

# 同时添加/移除成员
tcb role update --id 2032299359962361858 \
  --add-users "1001,1002" \
  --remove-users "1003" \
  -e my-env-id

# 修改策略
tcb role update --id 2032299359962361858 \
  --add-policies '["FunctionsAccess"]' \
  --remove-policies '["StoragesDeny"]' \
  -e my-env-id

tcb role delete​

删除自定义角色（不可撤销，系统角色不可删除）。

tcb role delete <roleId...> [options]

示例​

# 删除单个角色
tcb role delete 2037415874111574018 -e my-env-id

# 批量删除（最多 100 个）
tcb role delete 2037415874111574018 2037420918731018242 -e my-env-id

相关命令​