Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

配置参考

本页列出所有可能需要调整的配置键及其默认值和含义:先介绍 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_logasynchronous_metric_logtableswarningsserver_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 图表配置值

在 Kubernetes 中,连接器通过 clicklink-connector Helm 图表的配置值进行配置。clicklink clctl init 会生成一个 clicklink-values.yaml 覆盖文件,其中已填入以下所有内容;除非传入 --force,否则在重复运行时会保留该文件。下表列出了图表的默认值;每个组件都提供标准工作负载配置项 (resourcesnodeSelectortolerationsaffinityserviceAccount.annotationsenvimagePullSecrets) ,其默认值均为空,因此不在各表中重复列出。

集群

默认值 含义
cluster.pcmInfraUuid "" (由 init 填写) 此连接器部署的唯一标识符。启用任一组件时必须提供;重新运行时会保留。
cluster.region "" (由 init 填写) 区域标签。必填。
cluster.cloud "" (由 init 填写) 云提供商标签。必填。

image

默认值 含义
image.repository 已在发布的 图表 中预先设置 Connector 镜像仓库。发布的 图表 指向公网 registry 中的镜像 (支持多架构,且已通过 cosign 签名) ;仅在需要覆盖时设置,例如使用网络边界内的 mirror。可使用 helm show values 查看发布的值。
image.tag "" (跟随 图表 的 appVersioninit 固定命令行客户端版本) 镜像标签。
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-keysecret-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.platformscraper.labels.envscraper.labels.region "" 注入到每个输出指标中的标记。启用抓取器时,这三个标记均为必填;否则 图表 会在渲染时报错。
scraper.config {} 透传上文未涵盖的任意 scraper 配置键 (如抓取时间间隔、缓冲区和发送器等;schema 与 VM scraper 块相同) 。
scraper.bufferSizeLimit 2Gi 抓取器临时卷的容量上限;抓取器不保留持久化磁盘状态。
scraper.rbac.extraSecretNames [] 抓取器的 ServiceAccount 可执行 get 操作的额外 Secret 名称,仅支持精确名称。
scraper.accessBundles {} 按实例名称索引的每实例访问包,每个访问包包含 secretNameserviceAccountName。挂载至 /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_logtext_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 时会失败。
Navigation