本页列出所有可能需要调整的配置键及其默认值和含义:先介绍 VM 配置文件,再介绍 Helm 图表配置值。有关具体配置任务的指导,请参阅配置指南。
VM 配置文件
在 Linux 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.grantsHelm 图表配置值
在 Kubernetes 中,连接器通过 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) 。 |
密钥
该 图表 使用预先创建的 Secret;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 时会失败。 |