Skip to main content

​
组件

ClickHouse 连接器运行三个守护进程，它们均内置于 clicklink 二进制文件中：
  • 执行器 (执行器) 与连接器端点之间保持一条出站命令通道，并执行 ClickHouse Cloud 针对其在你的集群中所管理的服务下发的生命周期命令。这些命令包括创建、扩缩容、停止与启动、重启、备份与删除备份、删除，以及你已批准的平台更新。它执行的每一项操作都是一次 Kubernetes API 调用。它不会与 ClickHouse 建立任何连接，也不持有你的桶或 IAM 凭据。它仅在托管模式下运行。
  • 抓取器 (scraper) 按固定时间间隔读取允许列表中的 ClickHouse 系统表，并将结果缓存在本地，随后连同基础设施元数据与健康状况一并发送至你的连接器端点。
  • 故障排查工具 (troubleshooter) 与连接器端点之间保持一条出站命令通道，并在处于活动状态的支持会话期间运行只读诊断。在会话之外，它不执行任何操作。
在 Kubernetes 上，clicklink-connector Helm 图表会将这些守护进程部署到你指定的命名空间中 (默认为 clicklink) 。执行器是一个单副本 Deployment，其命令状态保存在持久卷上。在 Linux VM 上，这些守护进程以 clicklink-scraper、clicklink-troubleshooter 和 clicklink-executor 三个 systemd 单元的形式，在无特权的 clicklink 系统用户下运行。

​
连接

连接器建立的每一个连接都是出站连接。完整列表如下： 每个 API 请求都会携带一个 Authorization 标头，其中包含对请求方法、路径、时间戳以及请求体哈希计算得出的 HMAC-SHA256 签名。即便在 TLS 通道内部，请求也无法被重放或在传输过程中被篡改。 在入站方向，每个守护进程只暴露一个本地健康状况端口：抓取器为 8082，故障排查工具为 8084，执行器 为 8086。该端口提供 /livez、/readyz、/healthz，并在 /metrics 暴露该守护进程的 Prometheus 指标；没有单独的指标端口。执行器 的本地命令 API 仅绑定到回环地址，也没有任何 Service 将其对外暴露。唯一的另一个监听器，是需手动启用的会话网关；参见支持会话。ClickHouse Cloud 绝不会连接其中任何一个。

​
证书生命周期

连接器使用自行获取并维护的客户端证书向你的端点进行身份验证。三个 守护进程 出示的是同一份证书。
  • 注册。 clicklink clctl init 会在本地生成私钥和证书签名请求 (CSR) 。该 CSR 以你的 organization ID 作为通用名 (CN) ，并以你的端点 host 作为唯一的 DNS SAN。私钥始终不会离开你的环境。
  • 首次签发。 init 以 HMAC 进行身份验证，将 CSR 提交到 /v1/pcm/cert/sign 注册签名端点。如果你的组织已存在未过期的证书，该端点会返回 409 拒绝请求，此时命令行客户端会提示如何沿用现有证书完成流程，或使用 --force 将其替换。
  • 自动续订。 三个 守护进程 每 12 小时检查一次证书有效期。当剩余有效期不足 10 天时，它们会通过 /v1/pcm/cert/renew (mTLS 加 HMAC) 申请一份有效期为 30 天的续订证书。在 Kubernetes 上，续订后的证书会借助精确名称的 RBAC grant 写回 clicklink-mtls Secret；在 VM 上，每个 守护进程 会将其写入 /etc/clicklink/tls。续订过程无需 operator 干预。
连接器会对照系统 trust store 校验你的端点所出示的服务器证书。若设置了 api.tls.ca_file (VM) 或 api.tls.caFile (Helm) ，则会将 enrollment bundle 中的 CA 证书链追加到这些根证书之后。

​
数据流

​
哪些内容会离开您的环境

  • 来自允许列表中系统表的指标。 抓取器默认抓取 metric_log、asynchronous_metric_log、tables、warnings 和 server_settings。允许列表由显式配置指定；抓取器不会读取列表之外的任何内容。
  • 基础设施元数据。 通过 API 同步的服务、基础设施和备份清单。对于托管服务，这包括其状态、当前副本数和期望副本数，以及正在运行的服务器版本和配置版本。
  • 健康状况和自身指标。 组件状态以及连接器自身的运行指标。执行器 的心跳还会报告其命令通道是否已连接，并携带最近一次平台更新的结果、平台组件版本，以及最近一次所应用支持包的摘要。在虚拟机安装环境中，还会附加其 Kubernetes 访问包处于 ok、expiring、expired 还是缺失状态。
  • 命令执行结果。 对于 执行器 运行的每个生命周期命令：收敛过程中的进度，以及最终的成功或失败信息 (失败时包含错误文本) 。
  • 您提交的服务定义。 clicklink clctl instances create 会发送您的环境 ID、云和区域、服务名称、其桶名称和 IAM 角色 ARN，以及幂等性键。同时还会发送 default 用户密码的两种哈希值 (SHA-256 和双重 SHA-1) 。
  • 支持会话输出。 在您启用的会话期间执行的只读诊断结果，经过脱敏处理。

​
默认情况下绝不外传的内容

  • 抓取路径上的原始查询文本。 system.query_log 未包含在默认抓取集中，因为其查询相关列可能包含字面值，从而携带 PII 或密钥。若要重新加入，需要按部署逐一进行覆盖配置。默认的会话表允许列表中确实包含 system.processes，它会显示正在执行的查询文本；如需对其进行裁剪，请参阅支持会话。
  • 你的表数据和备份。 它们始终保留在你账户下的桶中。执行器不持有访问这些桶的凭据，也无法读取其中的数据。
  • 凭据。 init 不会将任何凭据写入配置文件。ClickHouse 仅存储连接器用户密码的 bcrypt 哈希，密钥则保存在 Kubernetes Secrets 或主机上仅 root 可读的文件中。托管服务的 default 用户密码在你这一侧生成，且只显示一次；提交的只有其哈希值。抓取路径和同步路径都不会传输任何凭据。
  • 未脱敏的故障排查工具输出。 故障排查工具返回的所有内容在外传之前，都会先经过脱敏规则 (内置规则以及你自定义的规则) 处理。请参阅支持会话。

​
信任边界

  • 你的环境即边界。 ClickHouse Cloud 只接收连接器发送的内容：抓取数据、心跳与状态、命令执行结果，以及活跃支持会话返回的内容。它从不反向发起连接。
  • 会话网关归你所有。 除非你主动选择通过 Ingress 将其暴露，否则它只能在你的环境内部访问 (在 Kubernetes 上通过 kubectl port-forward，在 VM 上通过本地访问) 。ClickHouse Cloud 从不连接它。
  • 对 ClickHouse 的访问是只读的。 pcm_scraper 和 pcm_troubleshooter 用户持有按表授予的 SELECT 授权、抓取器的 READ ON REMOTE (clusterAllReplicas() 所需) ，以及一项仅供抓取器使用的 SYSTEM FLUSH LOGS 授权。不存在任何 INSERT、DDL 或用户管理类授权。执行器没有对应的 ClickHouse 用户。完整清单见特权模型。
  • 抓取器和故障排查工具无法更改你的集群。 它们的 RBAC 来自连接器命名空间和服务命名空间中的 Role。这些 Role 对工作负载资源仅授予只读动词权限，并且只能按精确名称访问连接器自身的 Secret。不存在 exec、delete 或 patch 权限。
  • 执行器以 pcm-executor 身份更改服务命名空间中的集群状态。 它创建和删除带有服务前缀 (默认为 ns-) 的命名空间，并通过删除 pod (容器组) 来重启它们。在这些命名空间内，它写入 ClickHouseCluster、Backup 和 ScalingOverride 对象，以及服务所需的 Secret、ServiceAccount 和 Service。它还会写入为抓取器提供读取权限的 Role 和 RoleBinding。ValidatingAdmissionPolicy 会拒绝该 ServiceAccount 在前缀范围之外的任何写入操作。例外情况全部发生在其所属命名空间中：其自身的令牌续期、clicklink-instance-registry ConfigMap，以及在 Kubernetes 上 mTLS Secret 中续期的客户端证书。当该策略无法被评估时，会以拒绝方式失败。admission 不作用于读取操作，因此它对这些资源族的读取不受前缀限制。
  • 执行器仅在你批准的更新期间以 pcm-platform 身份更改平台命名空间。 clicklink clctl platform approve 会为该身份签发有效期 2 小时的令牌；该令牌永不续期。凭此令牌，执行器只能写入 Deployment、Service、ConfigMap、Secret、Job 和 PodDisruptionBudget。命名空间、CRD、ServiceAccount、RBAC、webhook 与 admission 配置、PriorityClass 以及 StorageClass 则在批准过程中使用你自己的凭据应用。参见平台更新。
  • 执行器不持有访问你的桶或 IAM 的凭据。 clicklink clctl executor prepare 会创建某个服务的数据桶和备份桶及其 IAM 角色。clicklink clctl executor teardown 则将其移除。两者均使用你的凭据运行。该角色仅信任该服务的 Pod (容器组) ，因此执行器和 ClickHouse 都无法扮演它。执行器的云调用仅发往 Amazon ECR 和 STS。当平台同步或创建操作拉取图表时，它会登录 registry。在平台更新期间，它会使用只读拉取角色检查镜像。
  • 网络策略。 在 Kubernetes 上，图表会为每个守护进程渲染一个默认拒绝的 NetworkPolicy。出站流量仅允许发往 DNS、你为连接器端点列出的 CIDR，以及 Kubernetes API 服务器的 CIDR。抓取器和故障排查工具的策略还允许访问执行器所管理命名空间中的 ClickHouse 服务 (通过执行器为其打上的标签选中) ，或你按名称列出的服务。执行器的策略不包含任何 ClickHouse 规则。如果平台捆绑包的图表存放在 Amazon ECR 中，请将 ECR 和 STS 的地址范围 (或你的 registry 镜像源) 添加到 allowEgressCIDRs。否则，在启用强制执行的 CNI 下同步将无法拉取图表。若没有具备强制能力的 CNI，该策略将形同虚设。参见配置。
  • VM 上的主机加固。 这些单元以不可登录的系统用户身份运行，并启用了 ProtectSystem=strict、NoNewPrivileges、只读配置路径以及 FIPS 模式。
关于连接器的确切授权和 RBAC 规则，请参阅特权模型参考文档。如果由 ClickHouse 自行预配并运维集群，信任模型会有所不同；参见 BYOC 架构和 BYOC 特权页面。