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_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 图表配置值

在 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 时会失败。
Navigation