> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理自定义角色

> 本页介绍管理员如何添加、修改和删除自定义角色。

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Beta 版功能</span>
        </a>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

本指南适用于在 ClickHouse Cloud 中拥有 Admin 角色的用户。

ClickHouse Cloud 客户可以选择预定义的系统角色，也可以创建自定义角色并分配给用户。有关系统角色及其对应权限的更多信息，请参阅[控制台角色和权限](/zh/products/cloud/reference/security/console-roles)。本指南将详细介绍如何管理自定义角色。

<div id="create-custom-role">
  ## 创建自定义角色
</div>

自定义角色可以包含组织、服务和数据库权限的任意组合。权限可应用于全部或部分服务和数据库。

<Steps>
  <Step title="进入组织设置并选择 Users and roles" id="users-and-roles-1">
    在 services 页面中，选择你的组织名称。然后在弹出菜单中选择 `Users and roles` 菜单项。

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/avthXRFo-wpxxds8/images/cloud/guides/control_plane/1_users_and_roles.webp?fit=max&auto=format&n=avthXRFo-wpxxds8&q=85&s=465bb65edffc806a153c4ca370a49a81" size="lg" width="3418" height="1702" data-path="images/cloud/guides/control_plane/1_users_and_roles.webp" />
  </Step>

  <Step title={<>选择 <code>Roles</code> 选项卡</>} id="roles-tab">
    在屏幕顶部中间选择 `Roles` 选项卡。

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/avthXRFo-wpxxds8/images/cloud/guides/control_plane/manage_custom_roles/2_custom_role.webp?fit=max&auto=format&n=avthXRFo-wpxxds8&q=85&s=e852f599ac4390cd5d39823e1d71f07e" size="lg" width="3414" height="984" data-path="images/cloud/guides/control_plane/manage_custom_roles/2_custom_role.webp" />
  </Step>

  <Step title={<>在右上角选择 <code>Create new role</code></>} id="create-new-role">
    点击屏幕右上角的 `Create new role` 按钮。

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/avthXRFo-wpxxds8/images/cloud/guides/control_plane/manage_custom_roles/3_custom_role.webp?fit=max&auto=format&n=avthXRFo-wpxxds8&q=85&s=72a6f738fc7b1143ae02c2d96a51df5c" size="lg" width="3418" height="1706" data-path="images/cloud/guides/control_plane/manage_custom_roles/3_custom_role.webp" />
  </Step>

  <Step title="为角色命名" id="name-the-role">
    输入一个便于识别的角色名称。这将是在为用户和 API 密钥 分配角色时显示的名称。

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/avthXRFo-wpxxds8/images/cloud/guides/control_plane/manage_custom_roles/4_custom_role.webp?fit=max&auto=format&n=avthXRFo-wpxxds8&q=85&s=6c57d29e02640cc5d285bdd568f3348f" size="md" width="1200" height="1704" data-path="images/cloud/guides/control_plane/manage_custom_roles/4_custom_role.webp" />
  </Step>

  <Step title={<>点击 <code>Allow</code> 并选择权限范围</>} id="scope-permissions">
    点击 `Allow` 按钮，然后从 Organization、Service 和/或 Database 权限中进行选择。有关所有权限的说明，请参阅[控制台角色和权限](/zh/products/cloud/reference/security/console-roles)。

    <Tip>
      确保需要登录控制台的用户至少具有 Organization > Access organization 权限。
    </Tip>

    <Info>
      **Data Sources tab access**

      要访问 **Data Sources** 选项卡，该角色目前需要 `Manage selected services` 权限。
    </Info>

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/avthXRFo-wpxxds8/images/cloud/guides/control_plane/manage_custom_roles/5_custom_role.webp?fit=max&auto=format&n=avthXRFo-wpxxds8&q=85&s=90001bfe74b8ca1f528b7aea343884c3" size="md" width="1192" height="1700" data-path="images/cloud/guides/control_plane/manage_custom_roles/5_custom_role.webp" />
  </Step>

  <Step title="检查新角色" id="review-role">
    完成之前，请检查分配给新角色的权限。确认无误后，点击 `Create role`。

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/avthXRFo-wpxxds8/images/cloud/guides/control_plane/manage_custom_roles/6_custom_role.webp?fit=max&auto=format&n=avthXRFo-wpxxds8&q=85&s=95310ec2a3576945f6b9222803cbf934" size="md" width="1190" height="1696" data-path="images/cloud/guides/control_plane/manage_custom_roles/6_custom_role.webp" />
  </Step>
</Steps>

<div id="manage-database-roles">
  ## 管理数据库角色 (Beta)
</div>

<BetaBadge />

除控制台权限外，自定义角色还可包含数据权限，以控制对所选服务中数据库的访问。这样，您可以在一个位置管理控制台和数据库访问权限，无需在每个数据库中分别维护角色。

<Note>
  此功能目前处于 Beta 阶段，适用于运行 ClickHouse 26.4 及更高版本的服务。
</Note>

向自定义角色添加数据权限时，ClickHouse Cloud 会在每个所选服务中创建一个对应的角色，并添加 `cloud:` 前缀。例如，名为 `readonly` 的自定义角色会在数据库中显示为 `cloud:readonly`。自定义角色的成员通过 SQL 控制台的免密码身份验证连接到服务时，将获得这些数据库权限。

<Info>
  在数据库中使用 [`sql-console-role:<email>` 命名约定](/zh/products/cloud/guides/security/cloud-access-management/manage-database-users#sql-console-users-and-roles)手动分配的角色，优先于通过控制台分配的角色。
</Info>

<Steps>
  <Step title="向角色添加数据权限" id="add-data-permissions">
    [创建自定义角色](#create-custom-role)，或编辑现有角色。在角色对话框中，单击 `Allow permissions` 按钮并选择 `Data`。
  </Step>

  <Step title="选择服务" id="select-data-permissions-service">
    选择要应用权限的服务。添加更多服务即可在多个服务中应用权限。
  </Step>

  <Step title="选择访问级别" id="choose-data-access-level">
    选择 `Read-only`、`Admin` 或 `Custom` 访问级别。选择 `Custom` 时，可通过 ClickHouse [`GRANT` 语句](/zh/reference/statements/grant)定义具体的数据访问权限。

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/avthXRFo-wpxxds8/images/cloud/guides/control_plane/manage_custom_roles/create_role_data_permissions.webp?fit=max&auto=format&n=avthXRFo-wpxxds8&q=85&s=0e3d1544276432eb02a1298aabd3f0cd" alt="新建角色对话框，其中的数据权限由自定义授权语句定义" size="md" width="1174" height="1230" data-path="images/cloud/guides/control_plane/manage_custom_roles/create_role_data_permissions.webp" />
  </Step>

  <Step title="创建角色" id="create-role-with-data-permissions">
    单击 `Create role`。系统将在所选服务中创建数据库角色。
  </Step>
</Steps>

<div id="verify-database-roles">
  ### 验证数据库角色
</div>

通过控制台管理的角色会在数据库中创建，其名称带有 `cloud:` 前缀，存储类型为 `cloud`。要列出这些角色，请查询服务中的 `system.roles` 表：

```sql theme={null}
SELECT * FROM system.roles;
```

```response theme={null}
┌─name───────────┬─id───────────────────────────────────┬─storage─┐
│ cloud:readonly │ 9a4910f4-abcf-4904-466a-717c8c75ac42 │ cloud   │
└────────────────┴──────────────────────────────────────┴─────────┘
```

<div id="update-custom-role">
  ## 更新自定义角色
</div>

自定义角色创建后可以更新。用户会失去从该角色中移除的所有权限，并获得新增的所有权限。

<Tip>
  用户权限是叠加的。如果用户通过多个角色拥有执行某项操作的权限，那么仅从其中一个角色移除该权限时，他们可能不会立即失去访问权限。
</Tip>

1. 进入组织设置，然后选择 `Users and roles`
2. 选择 `Roles` 选项卡
3. 选择要更新的角色旁边的三个点
4. 选择 `Edit`
5. 修改权限
6. 选择 `Edit role`

<div id="delete-custom-role">
  ## 删除自定义角色
</div>

自定义角色可随时删除。

<Warning>
  组织中必须至少有一位用户拥有管理权限。如果删除该角色会导致最后一位用户失去管理权限，则无法删除该角色。要解决此问题，请先为至少一位用户分配 Admin 系统角色，然后再删除自定义角色。
</Warning>

1. 进入组织设置并选择 `Users and roles`
2. 选择 `Roles` 选项卡
3. 选择要删除的角色旁边的三个点
4. 查看删除该角色后将失去访问权限的用户和 API 密钥，并按需调整分配。
5. 选择 `Delete role` 完成删除