Skip to main content
本页是 ClickHouse 连接器的安全参考,涵盖其建立的所有连接、拥有的确切权限、从设计上无法执行的操作,以及每项操作的归因方式。有关各组件如何协同工作,请参阅架构

连接器 的功能

出站连接

以下是连接器发起的全部连接。所有连接均从您的环境内部发起。 对于入站连接,连接器仅开放本地健康检查和指标端口,以及可选启用的会话网关。不会有其他服务监听,ClickHouse Cloud 也绝不会连接到您的环境:它只能响应故障排查器发起的出站 WebSocket。

ClickHouse 授权

预配会为每个组件创建一个只读用户。纯读取操作唯一的例外是下方列出的抓取器 SYSTEM FLUSH LOGS 授权;它不能读取或修改任何内容,只会强制日志表将已缓冲的条目持久化。用户通过 IDENTIFIED WITH bcrypt_hash 创建,因此预配 SQL 中仅包含加盐的 bcrypt 哈希;明文密码仅保存在守护进程运行时读取的凭据文件中。授权如下,使用默认表集:
由于抓取查询会通过 clusterAllReplicas() 包装每个系统表,因此需要 READ ON REMOTE。必须在全局范围内授予 SYSTEM FLUSH LOGS,因为 ClickHouse 会拒绝为该权限指定更窄的范围;ClickHouse 仅会对 *_log 系统表执行该权限,因此授予范围比实际能力更广。
两个用户都拥有 system.user_directories 授权,但仅用于一项诊断:clicklink clctl preflight 会使用连接器自身的凭据运行,并检查该实例如何存储 ClickHouse 用户 (副本或本地) 。该表保存的是用户存储配置元数据,而非用户数据;抓取集合和会话表允许列表均未包含该表,因此抓取或会话输出路径不会读取它。没有此授权时,该项预检会显示为已跳过,其他操作仍会继续。 除各表的 SELECT 外,唯一的系统级授权是供抓取器使用的 SYSTEM FLUSH LOGS:它会强制 *_log 系统表将缓冲条目持久化到磁盘,使抓取能获取最新数据,除此之外不执行任何操作;尽管该授权只能在全局范围内授予,ClickHouse 也仅会对日志表执行该操作。没有 INSERT、DDL、用户管理、设置或进程控制方面的授权。当第二个 连接器 部署共享同一实例时,其用户会带有后缀 (pcm_scraper_<suffix>) ,并拥有相同的授权集。

Kubernetes RBAC

该 chart 仅创建命名空间范围内的 Role;不创建集群角色或 ClusterRoleBinding。

连接器无法执行的操作

  • 不会向 ClickHouse 写入数据或状态。 上述授权不包含 INSERT、DDL,也不包含用户管理、设置或进程控制权限;唯一的系统级授权,即抓取器的 SYSTEM FLUSH LOGS,仅会将日志表已缓冲的内容持久化。连接器无法修改数据、schema、用户或设置。
  • 无法执行命令。 RBAC 不包含 pods/exec;连接器无法在您的 Pod (容器组) 中运行命令。
  • 无法删除或修补。 RBAC 仅允许两项变更:对连接器自身的 mTLS Secret 执行精确名称匹配的 update,以及对 serviceaccounts/token 执行 create。后者会为连接器自身的 ServiceAccounts 签发短期标记,且不会修改任何已存储对象。
  • 不具备集群范围权限。 每个 Role 均绑定在某个命名空间中;连接器无法列出或读取您未授予权限的命名空间中的资源。
  • 没有入站连接。 ClickHouse Cloud 绝不会向您的环境发起连接。唯一的命令通道是故障排查器的出站 WebSocket;除非您启用的支持会话处于活动状态,否则故障排查器会拒绝所有命令。即使在会话期间,访问范围也在两端受到限制:ClickHouse 查询仅限于表允许列表,且无论配置如何,验证器都会拒绝 query_logtext_log;Kubernetes 访问则单独限制为命名空间范围 Role 授予的只读视图和 pod (容器组) 日志。

需要您采取操作的事项

  • 支持会话。 交互式故障排查只能在您启用的会话中进行;默认时长为 4 小时,最长不超过 24 小时。禁用后立即生效。请参阅支持会话
  • 操作员允许列表。 每个 Gateway 请求都必须携带 OIDC 标记,且其声明的电子邮件地址必须在您的允许列表中。允许列表为空时,访问默认关闭。该列表由您管理;请参阅配置指南
  • Gateway 暴露。 会话网关默认关闭,需由您启用;除非您选择使用入口,否则只能通过端口转发访问。在 VM 上,每位操作员都必须固定其自签名证书的指纹,会话命令才能与之通信。
  • 网络出站流量。 在强制实施 CNI 的环境中,连接器默认没有出站访问权限,除非您在 chart 的 NetworkPolicy 中将端点 CIDR 加入允许列表。

访问归属

  • 部署身份。 mTLS 客户端证书的通用名称为您的 org ID,且仅有一个 DNS name 绑定到您的端点主机,因此每个 API 连接均可归属于您的 org。证书会在守护进程内自动续订;无需操作员处理密钥材料。
  • 请求完整性。 每个 API 请求还会携带一个 HMAC-SHA256 签名 (Authorization: HMAC-SHA256 AccessKey=..., Signature=..., Timestamp=...) 。该签名使用注册时签发的密钥对,根据方法、路径、时间戳和正文哈希计算得出。
  • 操作员身份。 Gateway 调用归属于操作员 OIDC ID token 中证明的电子邮件地址,并根据您的身份提供商 JWKS 进行验证;只要 token 可用,绝不信任自行声明的名称。
  • 审计跟踪。 每次 gateway 调用和每条 troubleshoot 命令,无论被接受还是阻止,都会追加到 NDJSON 审计日志中:gateway 条目包含经验证的操作员电子邮件地址,VM 本地会话变更包含执行调用的主机用户,会话命令则包含经身份验证通道传递的 org 身份。使用 clicklink clctl troubleshoot audit tail 读取;请参阅 命令行客户端参考

数据最小化默认设置

  • **默认不抓取 query_log。**其列包含带字面值的原始 SQL,其中可能包含个人数据或密钥,因此除非您主动添加,否则这些数据不会离开您的边界。
  • 故障排查器仅读取允许列表中的表,验证器会无条件拒绝 query_logtext_log,因此查询历史记录永远无法读取。默认允许列表包含 system.processes (实时查询文本) ;如果会话期间也必须隐藏这些内容,请缩减会话表允许列表 (Kubernetes 上为 troubleshooter.allowedTables,VM 上为 troubleshooter.allowed_tables) 。
  • 所有故障排查器输出都会脱敏,内置模式可识别 IPv4 和 IPv6 地址、Bearer 令牌、AWS 访问密钥、电子邮件、JWT、SSH 私钥和连接字符串凭据,以及您定义的任何模式。模式文件无效时,守护进程会拒绝启动,而不会在未脱敏的情况下运行。
  • **静态存储的凭据已最小化。**预配 SQL 包含 bcrypt 哈希,绝不包含明文密码;注册令牌绝不会写入命令行、磁盘或日志;密钥存储在 Kubernetes Secrets 中,或存储在权限模式为 0600 的文件中。
最后修改于 2026年8月26日