跳转到主要内容
您可以在这里加入私有预览等候名单。
本文介绍 ClickPipes 为通过 Google Cloud Pub/Sub 进行身份验证并从您的主题中消费数据所需的 GCP IAM 权限，以及如何设置一个恰好授予这些权限的服务账号。

​
前置条件

要按照本指南操作，你需要具备：
  • 一个处于活跃状态的 ClickHouse Cloud 服务
  • 一个 GCP 项目，其中包含你要从中摄取数据的 Pub/Sub topic
  • 在该项目中拥有创建服务账号并授予角色所需的 IAM 权限

​
身份验证模型

用于 Pub/Sub 的 ClickPipes 使用 服务账号 JSON 密钥向 GCP 进行身份验证。创建管道时，您需要上传该密钥文件；ClickPipes 会在静态存储时对其加密，并在运行时将其用于：
  • 列出并读取您项目中的 topic，
  • 创建和删除 ClickPipes 用于消费消息的托管订阅，
  • 从该订阅消费消息，以及
  • (可选) 从 Schema Registry 读取原生 Pub/Sub schema。
不支持 Workload Identity 或直接粘贴凭据；目前唯一支持的身份验证方法是服务账号 JSON 密钥。

​
所需权限

ClickPipes 需要在拥有该 topic 的 GCP 项目中具备以下 IAM 权限。这些权限涵盖管道的完整生命周期：发现 (topic 列表、验证、采样) 、订阅管理、稳定运行时的摄取以及清理。

​
topic 访问 (发现与校验)

​
订阅生命周期 (发现与摄取)

​
Schema 访问 (可选——仅适用于原生 Avro/Protobuf topic)

​
预定义角色

​
配置

​
创建自定义角色 (推荐)

为遵循最小权限原则，请创建一个仅包含 ClickPipes 所需权限的自定义角色。 你可以使用 gcloud CLI 执行此操作：
或者，在 GCP Console 中，前往 IAM & Admin → Roles → Create role，并添加所需权限中列出的各项权限。
可选权限如果你要从使用原生 Pub/Sub Avro 或 Protobuf schema 的 topic 摄取数据，请将 pubsub.schemas.get 追加到 --permissions 列表中。否则无需添加，以保持角色权限最小化。
如果你不想创建自定义角色，也可以直接授予 roles/pubsub.editor。

​
创建服务账号

为 ClickPipe 创建专用服务账号：

​
向服务账号授予角色

在项目级别，将你创建的角色 (或 roles/pubsub.editor) 绑定到服务账号：

​
创建并下载服务账号密钥

为服务账号创建一个 JSON 密钥，并下载到本地：
您将在创建该管道时，在 ClickPipes UI 中上传此 clickpipes-pubsub-key.json 文件。
请将该密钥作为机密信息处理服务账号密钥可用于访问您的 GCP 项目。请妥善保管该文件，不要将其提交到版本控制系统，并定期轮换。上传后，ClickPipes 会对静态存储中的密钥进行加密。

​
注意事项

  • pubsub.topics.attachSubscription 需要在topic 资源上授予，而不是在订阅上。只授予订阅级权限时，通常会遗漏这一点。
  • 如果您的 topic 未使用原生 Pub/Sub schema (Avro 或 Protobuf) ，则不需要 pubsub.schemas.get 权限。
  • 托管订阅命名为 clickpipes-{pipeID}，ack deadline 为 60 秒，消息保留期为 7 天，并启用了消息排序。
  • 临时发现订阅命名为 clickpipes-discovery-{uuid}，ack deadline 为 10 秒，保留期为 10 分钟，并设置了 24 小时自动过期的生存时间 (TTL)。
  • ClickPipes 将 PermissionDenied 和 Unauthenticated 错误视为不可重试——如果缺少权限，管道会立即失败，而不是无限重试。
最后修改于 2026年6月10日