VM 配置文件
clicklink clctl init 写入的 /etc/clicklink/config.yaml。除非传入 --force，否则重新运行时会保留该文件。文件中未指定的键将使用下方的编译时默认值。凭据绝不会存储在此文件中。
顶层键
| 键 | 默认值 | 含义 |
|---|---|---|
pcm_infra_uuid | 由 init 生成 | 此连接器部署的唯一标识符，会随每个上游请求一同发送。重复运行时会保留，包括使用 --force 的情况。请勿编辑。 |
cloud | 由 init 检测 | 此主机的云提供商标签。必填；为空时，守护进程将拒绝启动。 |
region | 由 init 检测 | 此主机的区域标签。必填；为空时，守护进程将拒绝启动。 |
api | 上游 API 连接块，参见 api。 | |
instances | {} | 按名称映射的 ClickHouse 实例，参见 instances。 |
scraper | 抓取器守护进程块，参见 scraper。 | |
troubleshooter | 故障排查守护进程块，参见 troubleshooter。 | |
observability | 共享日志和端口块，参见 observability。 |
api
| 键 | 默认值 | 含义 |
|---|---|---|
api.endpoint | 来自注册包 | 您的组织连接器 API 端点：https://<subdomain>.<connector domain>。 |
api.access_key_file | /etc/clicklink/access-key (由 init 写入) | 存储 HMAC 访问密钥的文件 (权限模式为 0600) 。 |
api.secret_key_file | /etc/clicklink/secret-key (由 init 写入) | 存储 HMAC 密钥的文件 (权限模式为 0600) 。 |
api.tls.enabled | true | 在 API 连接中出示 mTLS 客户端证书。 |
api.tls.cert_file | /etc/clicklink/tls/client.crt | mTLS 客户端叶证书；续订时会自动重写。 |
api.tls.key_file | /etc/clicklink/tls/client.key | mTLS 客户端私钥。 |
api.tls.ca_file | /etc/clicklink/tls/ca.crt | 用于验证服务器的额外 CA 证书链，会添加到系统根证书中；init 会将注册包中的证书链安装到此处。 |
api.retry.max_retries | 5 | 每个 API 请求的重试次数。 |
api.retry.initial_delay | 1s | 首次重试的退避延迟。 |
api.retry.max_delay | 30s | 退避延迟上限。 |
api.retry.jitter_factor | 0.25 | 应用于退避延迟的随机抖动。 |
instances
instances.<name> 下的每个条目描述一个 ClickHouse 原生协议目标：
| 键 | 默认值 | 含义 |
|---|---|---|
host | ClickHouse 原生监听端点的主机名或 IP 地址。 | |
port | 原生协议端口 (启用 TLS 时通常为 9440，明文连接时为 9000) 。 | |
database | 连接器会话默认使用的数据库。 | |
secure | false | 在原生连接中启用 TLS。 |
max_open_conns | 未设置 | 此实例的打开连接数上限。 |
max_idle_conns | 未设置 | 此实例的空闲连接池连接数上限。 |
namespace | 实例所在的 Kubernetes 命名空间，用于限定故障排查器读取 Kubernetes 资源的范围。 | |
cluster | default | 用于分布式查询的 ClickHouse 集群名称。 |
抓取器
| 键 | 默认值 | 含义 |
|---|---|---|
scraper.enabled | false (init 会写入 true) | 运行抓取器守护进程。 |
scraper.labels.platform | 注入到每个导出指标中的标记。启用抓取器时必填。 | |
scraper.labels.env | 环境标记，例如 production。必填。 | |
scraper.labels.region | 区域标记。必填。 | |
scraper.scrape.interval | 2m | 抓取各实例的频率。 |
scraper.scrape.timeout | 30s | 单次抓取的查询超时时间。 |
scraper.scrape.tables | 见下文 | 每个实例抓取的系统表。默认集合为 metric_log、asynchronous_metric_log、tables、warnings、server_settings；特意排除 query_log，因此默认情况下原始 SQL 文本不会离开您的安全边界。 |
scraper.buffer.path | /var/lib/clicklink/buffer | API 端点不可访问时，用于确保至少一次交付的磁盘缓冲区。 |
scraper.buffer.retention | 168h | 缓冲数据的最长保留时间。 |
scraper.buffer.max_size_mb | 1024 | 缓冲区大小上限 (MB) 。 |
scraper.sender.bandwidth_limit_mb | 1.0 | 上传速率上限 (MB/s) 。 |
scraper.observability.health_port | 8082 | 抓取器健康检查端点的端口。 |
scraper.observability.metrics_port | 9092 | 抓取器指标端口。 |
scraper.access_directory | /etc/clicklink/access/scraper | 抓取器各实例访问包的根目录。 |
故障排查器
| 键 | 默认值 | 含义 |
|---|---|---|
troubleshooter.enabled | false (init 会写入 true) | 运行故障排查器守护进程。 |
troubleshooter.poll_interval | 5s | 会话状态轮询时间间隔。 |
troubleshooter.command_timeout | 60s | 单个命令的执行超时。 |
troubleshooter.session_timeout | 4h | 默认支持会话时长。 |
troubleshooter.session_file_path | /var/lib/clicklink/session.json | 会话状态文件，与 clicklink clctl troubleshoot session 命令共用。 |
troubleshooter.access_directory | /etc/clicklink/access/troubleshooter | 故障排查器按实例划分的访问包根目录。 |
troubleshooter.allowed_tables | 参见默认表允许列表 | 故障排查器可执行 SELECT 查询的系统表。 |
troubleshooter.max_open_conns | 5 | 打开的 ClickHouse 连接数上限。 |
troubleshooter.max_idle_conns | 5 | 连接池中空闲连接数上限。 |
troubleshooter.redaction.workers | 4 | 并行脱敏工作线程数。 |
troubleshooter.redaction.patterns_file | /etc/clicklink/redaction-patterns.yaml | 客户可编辑的脱敏模式；如果文件存在但无效，守护进程将拒绝启动。 |
troubleshooter.redaction.metrics_per_pattern | false | 为每个模式输出匹配计数器指标。 |
troubleshooter.redaction.metrics_per_pattern_cap | 50 | 每模式指标中不同模式名称的数量上限。 |
troubleshooter.audit_log.path | /var/log/clicklink/troubleshoot-audit.log | 仅追加的 NDJSON 审计日志，记录每个已接受或被阻止的命令。 |
troubleshooter.audit_log.max_size_mb | 128 | 活动日志文件超过此大小时进行轮转。 |
troubleshooter.audit_log.max_files | 5 | 保留的轮转日志文件数。 |
troubleshooter.audit_log.max_age | 168h | 早于此时间的轮转日志文件将被清理。 |
troubleshooter.gateway.enabled | false | 提供会话网关服务 (通过 OIDC 支持会话) 。 |
troubleshooter.gateway.listen_addr | ":8443" (由 init 写入) | 网关监听地址。 |
troubleshooter.gateway.audience | clicklink-clctl (由 init 写入) | 操作员标记中必需的受众声明。 |
troubleshooter.gateway.required_hosted_domain | "" | 可选的托管域声明限制；在查询允许列表前，会拒绝来自该域外的标记。 |
troubleshooter.gateway.allowed_operators_file | /etc/clicklink/allowed-operators.txt (由 init 写入) | 以换行符分隔的操作员电子邮件允许列表。为空表示不允许任何人访问。 |
troubleshooter.gateway.rate_limit_per_minute | 0 (已禁用) | 每位操作员的请求速率限制。 |
troubleshooter.gateway.handler_timeout | 未设置 | 服务器端请求超时。 |
troubleshooter.gateway.jwks_uri | "" | 非 Google 身份提供商的 JWKS 端点；为空时使用 Google 的端点。 |
troubleshooter.gateway.issuer | "" | 设置 jwks_uri 时要固定的签发方声明。 |
troubleshooter.gateway.tls.enabled | false (启用支持会话时，init 会在 VM 上写入 true) | 使用守护进程在证书不存在时生成的自签名证书，通过 TLS 提供网关服务；操作员需固定其指纹。 |
troubleshooter.gateway.tls.cert_file | /var/lib/clicklink/gateway/tls/server.crt | 网关服务证书。 |
troubleshooter.gateway.tls.key_file | /var/lib/clicklink/gateway/tls/server.key | 网关服务私钥。 |
troubleshooter.gateway.tls.self_signed_dns_names | [] (init 会预填充主机名) | 守护进程在证书不存在时自行生成的自签名证书的 SAN；可解析为 IP 地址的条目将成为 IP SAN。 |
可观测性
| 键 | 默认值 | 含义 |
|---|---|---|
observability.enabled | true | 提供健康检查和指标端点。 |
observability.log_level | info | 日志级别。 |
observability.health_port | 8080 | 共享健康检查端口的基准值。 |
observability.metrics_port | 9090 | 共享指标端口的基准值。 |
observability 块会在这些基础配置之上进行覆盖：抓取器使用 8082/9092，故障排查器使用 8084/9094，网关 启用时则监听 8443。
默认表允许列表
allowed_tables 集合，与图表中 troubleshooter.allowedTables 的默认值相同：
system.build_options system.clusters system.columns
system.databases system.tables system.parts
system.parts_columns system.parts_summary system.detached_parts
system.processes system.merges system.mutations
system.replicas system.replication_queue
system.metrics system.events system.asynchronous_metrics
system.disks system.storage_policies
system.settings system.settings_profiles
system.settings_profile_elements
system.functions system.formats system.table_engines
system.users system.roles system.grants
Helm 图表配置值
clicklink-connector Helm 图表的配置值进行配置。clicklink clctl init 会生成一个 clicklink-values.yaml 覆盖文件，其中已填入以下所有内容；除非传入 --force，否则在重复运行时会保留该文件。下表列出了图表的默认值；每个组件都提供标准工作负载配置项 (resources、nodeSelector、tolerations、affinity、serviceAccount.annotations、env、imagePullSecrets) ，其默认值均为空，因此不在各表中重复列出。
集群
| 键 | 默认值 | 含义 |
|---|---|---|
cluster.pcmInfraUuid | "" (由 init 填写) | 此连接器部署的唯一标识符。启用任一组件时必须提供；重新运行时会保留。 |
cluster.region | "" (由 init 填写) | 区域标签。必填。 |
cluster.cloud | "" (由 init 填写) | 云提供商标签。必填。 |
image
| 键 | 默认值 | 含义 |
|---|---|---|
image.repository | 已在发布的 图表 中预先设置 | Connector 镜像仓库。发布的 图表 指向公网 registry 中的镜像 (支持多架构，且已通过 cosign 签名) ；仅在需要覆盖时设置，例如使用网络边界内的 mirror。可使用 helm show values 查看发布的值。 |
image.tag | "" (跟随 图表 的 appVersion；init 固定命令行客户端版本) | 镜像标签。 |
image.pullPolicy | IfNotPresent | Kubernetes 镜像拉取策略。 |
api
| 键 | 默认值 | 含义 |
|---|---|---|
api.endpoint | "" (由 init 填充) | 组织连接器的 API 端点，供两个组件共用。 |
api.tls.enabled | true | 在 API 连接中提供 mTLS 客户端证书。 |
api.tls.caFile | "" (系统根证书) | 用于服务器验证的 CA，会附加到系统根证书中。当端点使用由私有 CA 签发的证书时，将其设置为 /etc/clicklink/secrets/mtls/ca.crt (或使用 --api-private-ca 重新运行 init) 。 |
密钥
init 会在安装前创建这些 Secret。
| 键 | 默认值 | 含义 |
|---|---|---|
secrets.mtlsSecretName | clicklink-mtls | 包含 mTLS 客户端私钥、证书和 CA 链的 kubernetes.io/tls Secret。 |
secrets.hmacSecretName | clicklink-hmac | 包含用于请求签名的 access-key 和 secret-key 的 Opaque Secret。 |
secrets.mtlsWriteback | true | 允许守护进程将自动续订的 mTLS 叶证书写回 mTLS Secret。这会为组件的 ServiceAccount 授予对该指定名称 Secret 的 update 权限；否则，续订后的证书将没有可持久化存储的位置。 |
scraper
| 键 | 默认值 | 含义 |
|---|---|---|
scraper.enabled | false (init 会写入 true) | 部署抓取器。 |
scraper.replicaCount | 1 | 抓取器副本数。 |
scraper.logLevel | info | 日志级别。 |
scraper.ports.health | 8082 | 健康检查端点端口。 |
scraper.ports.metrics | 9092 | 指标端口。 |
scraper.instances | {} | ClickHouse 实例映射，结构与 VM instances 字段相同。 |
scraper.labels.platform、scraper.labels.env、scraper.labels.region | "" | 注入到每个输出指标中的标记。启用抓取器时，这三个标记均为必填；否则 图表 会在渲染时报错。 |
scraper.config | {} | 透传上文未涵盖的任意 scraper 配置键 (如抓取时间间隔、缓冲区和发送器等；schema 与 VM scraper 块相同) 。 |
scraper.bufferSizeLimit | 2Gi | 抓取器临时卷的容量上限；抓取器不保留持久化磁盘状态。 |
scraper.rbac.extraSecretNames | [] | 抓取器的 ServiceAccount 可执行 get 操作的额外 Secret 名称，仅支持精确名称。 |
scraper.accessBundles | {} | 按实例名称索引的每实例访问包，每个访问包包含 secretName 和 serviceAccountName。挂载至 /etc/clicklink/access/scraper/<instance>/；由 clicklink clctl scraper access provision --target helm 创建。 |
故障排查器
| 键 | 默认值 | 含义 |
|---|---|---|
troubleshooter.enabled | false (init 会写入 true) | 部署故障排查器 (单副本 StatefulSet) 。 |
troubleshooter.logLevel | info | 日志级别。 |
troubleshooter.ports.health | 8084 | 健康检查端点端口。 |
troubleshooter.ports.metrics | 9094 | 指标端口。 |
troubleshooter.instances | {} | ClickHouse 实例映射，结构与 scraper.instances 相同。 |
troubleshooter.sessionTimeout | 4h | 默认支持会话时长。 |
troubleshooter.allowedTables | 默认表允许列表 | 故障排查器的 ClickHouse 用户可执行 SELECT 查询的表。这是需要在覆盖配置中调整的安全审查范围；无论此处列出了什么，命令验证器都会应用硬编码的拒绝列表 (query_log、text_log) 。 |
troubleshooter.auditLog.path | /var/log/clicklink/troubleshoot-audit.log | 审计日志路径，位于状态卷上，因此记录可在 pod (容器组) 重新调度后保留。 |
troubleshooter.auditLog.maxSizeMb | 128 | 超过此大小时旋转。 |
troubleshooter.auditLog.maxFiles | 5 | 保留的轮转文件数。 |
troubleshooter.auditLog.maxAge | 168h | 早于此时间的轮转文件会被清理。 |
troubleshooter.redaction.workers | 4 | 并行脱敏工作线程数。 |
troubleshooter.redaction.patternsConfigMap | "" | 包含自定义模式的 ConfigMap 名称，其 redaction-patterns.yaml 键存储自定义模式；图表 会将其挂载到 /etc/clicklink/redaction-patterns.yaml。为空时，仅应用内置模式。 |
troubleshooter.redaction.metricsPerPattern | false | 为每种模式导出匹配计数器指标。 |
troubleshooter.redaction.metricsPerPatternCap | 50 | 每种模式指标中不同模式名称的数量上限。 |
troubleshooter.config | {} | 透传上方未涵盖的任何 troubleshooter 配置键 (轮询间隔、命令超时、连接上限等) 。 |
troubleshooter.rbac.extraSecretNames | [] | 故障排查器的 ServiceAccount 可执行 get 操作的额外 Secret 名称，仅支持精确名称。 |
troubleshooter.accessBundles | {} | 按实例配置的访问包，结构与 scraper.accessBundles 相同，挂载到 /etc/clicklink/access/troubleshooter/<instance>/。 |
持久化
| 键 | 默认值 | 含义 |
|---|---|---|
persistence.enabled | true | 使用 PersistentVolumeClaim 持久化故障排查器的状态目录，确保会话状态和审计记录在重启后仍会保留。 |
persistence.storageClass | "" (集群默认值) | 此声明使用的存储类；init 会根据 --storage-class 或检测到的默认值进行填充。 |
persistence.size | 5Gi | 声明的大小。 |
persistence.accessModes | [ReadWriteOnce] | 声明的访问模式。 |
clctl.gateway
| 键 | 默认值 | 含义 |
|---|---|---|
clctl.gateway.enabled | false | 在 故障排查器 中提供会话网关。 |
clctl.gateway.listenAddr | ":8443" | pod (容器组) 本地监听地址。 |
clctl.gateway.port | 8443 | 通过 故障排查器 Service 和入口公开的容器端口；与 listenAddr 中的端口一致。 |
clctl.gateway.audience | clicklink-clctl | 操作员 标记中必须包含的 受众声明。会话客户端默认使用相同的值，因此仅在更改此值时才需要协调两者。 |
clctl.gateway.requiredHostedDomain | "" | 网关要求的可选托管域声明；在查询允许列表前拒绝工作区外的标记。 |
clctl.gateway.allowedOperators | [] (关闭) | 操作员 电子邮件允许列表，会渲染为 ConfigMap；轮换时需更改配置值并执行 helm upgrade。 |
clctl.gateway.jwksUri | "" | 非 Google 身份提供商的 JWKS 端点覆盖值；留空时使用 Google 的端点。 |
clctl.gateway.issuer | "" | 要固定的签发方声明。任何设置了 jwksUri 的实际部署都必须提供此项。 |
clctl.gateway.jwksEgressCIDRs | [] | 在默认拒绝的 NetworkPolicy 下，网关为进行 JWKS 验证需要访问的 CIDR；留空会阻止所有标记检查。 |
clctl.gateway.ingressFromSelector | {} | 网关端口的 NetworkPolicy 入口来源；留空时允许图表命名空间中的任何 pod (容器组) 访问。使用入口时，请将其设置为入口 controller 的命名空间标签。 |
clctl.gateway.rateLimit.requestsPerMinute | 30 | 每个 操作员 的每分钟请求速率限制。 |
clctl.gateway.ingress.enabled | false | 为网关渲染入口。禁用时，操作员 可通过 kubectl port-forward 访问网关；无需入口 controller 或 cert-manager。 |
clctl.gateway.ingress.className, hosts, tls, annotations | "", [], [], {} | 标准入口字段；tls 引用 kubernetes.io/tls Secrets。 |
networkPolicy
| 键 | 默认值 | 含义 |
|---|---|---|
networkPolicy.enabled | true | 生成默认拒绝的 NetworkPolicy，并配置 egress 允许列表。需要使用支持强制执行的 CNI 才能生效。 |
networkPolicy.allowEgressCIDRs | [] | 连接器 API 端点所在的 CIDR。在支持强制执行的 CNI 环境中，填入此项前连接器无法进行 egress。 |
networkPolicy.allowEgressPorts | [443] | 向 allowEgressCIDRs 开放的端口；如果端点监听非默认端口，请覆盖此值。 |
networkPolicy.clickhouseNamespaces | [] | ClickHouse 服务所在的命名空间，通过 kubernetes.io/metadata.name 标签匹配。留空则不允许访问集群内的 ClickHouse。 |
networkPolicy.metricsScrapeSelector | {} | 通过标签将指标抓取入口限制为特定的 Prometheus 命名空间；留空则允许图表所在命名空间中的任意 pod (容器组) 抓取。 |
networkPolicy.kubeletProbeCIDRs | [] | kubelet 健康探针的来源 CIDR (节点 IP) 。留空则允许来自任何来源的探针入口，这与大多数 CNI 对 kubelet 的豁免行为一致；在严格的默认拒绝策略下应显式设置。 |
networkPolicy.apiserverCIDRs | [] | Kubernetes API server 的 CIDR。留空不会生成 API server egress 规则；在托管 Kubernetes 环境中，守护进程在设置此项前首次请求 token 时会失败。 |