命令行客户端参考

连接器以名为 clicklink 的单个二进制文件形式提供；可通过 clicklink clctl 运行相关命令。本页介绍安装和日常运维中使用的命令。对任意命令运行 --help，即可查看完整帮助文本。troubleshoot 和 preflight 子树中的 flags 还可通过 CLCTL_* 环境变量 (名称见各 flag 的帮助输出) 或 ~/.clicklink/clctl.yaml 提供。

clicklink clctl init

通过注册令牌、已保存的注册包或带外签名证书初始化连接器。一次调用即可暂存配置、配置 ClickHouse 访问权限、获取 mTLS 客户端证书、部署 (Helm 图表或 systemd 单元) 并验证运行状况。重复运行是安全的：配置和集群 UUID 会被保留，凭据会以原子方式覆盖；除非传入 --force，否则会复用现有客户端密钥。有关完整流程，请参阅入门配置。

入口点

三个入口点中必须且只能使用一个，彼此互斥。

标志	说明
`--enroll <url>`	标准流程。接受组织连接器端点 (`https://<subdomain>.<connector domain>`) ，兑换一次性注册令牌 (在终端中会提示输入且不回显；否则从 stdin 的第一行读取) ，将生成的包写入 `handoff.yaml` (权限模式为 0600) ，然后以 `--handoff handoff.yaml` 继续执行。令牌绝不会出现在命令行、磁盘或日志中。
`--handoff <path>`	使用已保存的注册包进行引导。`handoff.yaml` 存在后，重新运行和恢复时都会使用此选项。
`--signed-cert <path>`	隔离网络流程的第 2 阶段：安装通过带外方式签名的客户端证书，并完成分阶段安装。还可使用 `--chain <path>` 同时替换 CA 证书链。

通用标志

标志	说明
`--target <shape>`	部署形态：`systemd` (默认；引导当前所在的 VM) 或 `helm` (在具有 kubeconfig 的工作站上暂存 `clicklink-connector` chart) 。
`--instance <spec>`	以逗号分隔的 `key=value` 对指定 ClickHouse 实例 (`name`、`host`、`port`、`secure`、`database`、`namespace`、`cluster`) ；可重复指定。跳过交互式实例提示。
`--operators <emails>`	允许发起支持会话的 operator 电子邮件地址，以逗号分隔；启用会话网关并跳过提示。
`--no-gateway`	禁用会话网关 (不使用 OIDC 管理的会话) ；跳过提示。在 VM 上，主机上的 root 用户仍可通过本地会话文件管理会话。
`--force`	覆盖现有 config 或 overlay，并重新生成客户端密钥；同时确认替换尚未过期的自动签名证书。即使使用 `--force`，cluster UUID 也会保留。
`--skip-provision`	仅暂存：跳过按角色进行的 ClickHouse 访问预配 (在 systemd target 上还会跳过单元启用和验证) 。请另行运行 `clicklink clctl {scraper,troubleshoot} access provision`。
`--ch-user-suffix <suffix>`	为已预配的 ClickHouse 用户名添加可选后缀 (`pcm_scraper` 变为 `pcm_scraper_<suffix>`) ，使第二个连接器部署可与第一个共享同一实例，且不会发生用户冲突。
`--ch-admin-password-stdin`	当 SQL 预配需要 ClickHouse 管理员密码时，从 stdin 读取；在 terminal 中运行时则会提示输入。

签名选项 (仅限阶段 1)

标志	描述
`--no-auto-sign`	仅限阶段 1：跳过通过注册端点自动签署 CSR，适用于隔离网络或带外签名流程。
`--sign-endpoint <url>`	覆盖注册签名端点 (默认值：通过在支持包端点中插入 `enroll` DNS 标签生成) 。必须为 HTTPS URL。

仅适用于 Kubernetes 的标志

仅可与 --target helm 一同使用。

标志	说明
`--target-namespace <ns>`	chart 要安装到的命名空间，Secret 也会创建在此处 (默认值为 `clicklink`；会在终端中提示输入) 。
`--instance-namespace <ns>`	目标 ClickHouse 实例所在的命名空间；用于初始化原生 Service 检测和实例相关提示。
`--storage-class <name>`	troubleshooter 状态卷使用的存储类 (默认值：集群的默认 StorageClass；如果集群未设置默认 StorageClass，则会提示输入或要求提供) 。
`--values <path>`	暂存的配置值覆盖文件路径 (默认值为 `clicklink-values.yaml`) 。
`--chart <ref>`	要部署的 chart：在 `--chart-repo` 中解析的名称，或用于镜像安装的直接 `oci://`、URL 或本地引用 (默认值为 `clicklink-connector`) 。
`--chart-repo <url>`	用于解析 chart 名称的 Helm 仓库 (默认值为 `https://releases.clicklink.clickhouse.com/charts`) ；直接指定 `--chart` 引用时将忽略此项。
`--chart-version <ver>`	要部署的 chart 版本 (默认值：此二进制文件的发行版版本) 。
`--ch-pod <ref>`	用于 pod 内预配步骤的 ClickHouse pod (容器组) ，可指定名称或 `k=v` 标签选择器 (默认值：为每个实例的 Service 提供支持的一个运行中 pod) 。
`--api-private-ca`	API 端点提供由注册包 CA 签发的证书：暂存 `api.tls.caFile`，使其指向已挂载的 CA 证书链，而非系统根证书。

仅适用于 VM 的标志

仅可与 --target systemd 配合使用。

标志	描述
`--server <url>`	访问包所指向的 Kubernetes API server URL (默认使用此主机的 kubeconfig；否则会提示输入) 。
`--ca-data <base64>`	用于 `--server` 的 Base64 `certificate-authority-data` (默认使用此主机的 kubeconfig；否则会提示输入) 。

标志冲突

--handoff、--enroll 和 --signed-cert 互斥；必须且只能指定其中一个。
仅 Kubernetes 适用的标志仅在指定 --target helm 时可用；使用 --target helm 时，不接受 --server 和 --ca-data (Helm 流程会读取工作站的 kubeconfig) 。
--no-auto-sign 与 --sign-endpoint 互斥，且二者 (以及 --api-private-ca) 均不能与 --signed-cert 一起使用。
--operators 与 --no-gateway 互斥。
使用 --skip-provision 时，不接受 --ch-pod、--ch-user-suffix、--server、--ca-data 和 --ch-admin-password-stdin (不会执行任何预配) 。

clicklink clctl preflight

运行按类别分组的连接器检查套件：配置、文件、网络、ClickHouse、systemd、访问、磁盘和脱敏。每项检查会报告通过、警告、失败或跳过。退出代码为 0 表示所有检查均已通过 (警告不造成阻塞) ；退出代码为 2 表示一项或多项检查失败。该命令默认在本地运行。使用 --k8s-namespace 时，它会通过 kubectl exec 在连接器 pod (容器组) 中运行连接器自身的二进制文件，并在本地生成报告 (在 pod 中始终跳过 systemd 检查) 。使用远程通道标志时，则会在远程 VM 上运行已安装的二进制文件。

标志	说明
`--config <path>`	连接器配置文件的路径；对于远程目标，则为该主机上的路径。
`--output <fmt>`, `-o`	输出格式：`text` (默认) 或 `json`。
`--timeout <dur>`	所有检查的总超时时间 (默认值为 `30s`) 。
`--skip-systemd`	跳过 systemd 单元状态检查 (用于非 systemd 主机) 。
`--k8s-namespace <ns>`	连接器 chart 所在的命名空间；通过 `kubectl exec` 在连接器 pod (容器组) 内运行预检。
`--k8s-component <name>`	要运行预检的连接器 pod (容器组) ：`scraper` (默认) 或 `troubleshooter`。
`--k8s-pod <ref>`	Pod (容器组) 名称，或 `k=v` 标记选择器覆盖项 (默认：chart 的组件标记) 。
`--k8s-container <name>`	要 exec 进入的容器 (默认：组件名称) 。

--k8s-* 标志与远程通道标志互斥；请选择其中一个目标。

clicklink clctl troubleshoot session

用于启用、禁用和检查支持会话：故障排除程序在此限定时间窗口内接受命令。当没有活动会话时，即使其 WebSocket 已连接，守护进程也会拒绝所有命令。请参阅支持会话。这些命令可在以下两种模式之一运行：

本地文件 (默认) ：在运行故障排除程序的主机上读取和写入会话状态文件 (默认为 /var/lib/clicklink/session.json) 。
Gateway：使用 --gateway-url 时，会从您的工作站获取 OIDC ID 令牌，并改为调用故障排除程序的会话网关。

共享选项

标志	说明
`--session-file <path>`	会话状态文件的路径 (默认为 `/var/lib/clicklink/session.json`) 。
`--config <path>`	连接器配置文件；会从其 `troubleshooter` 部分获取会话文件路径。
`--gateway-url <url>`	会话网关的基础 URL。设置后，命令会获取 OIDC Bearer 令牌并调用网关，而不访问本地状态文件。与 `--session-file` 和 `--config` 互斥。
`--gateway-audience <aud>`	OIDC 令牌绑定的 audience 声明 (默认为 `clicklink-clctl`，与网关自身的默认值一致) 。仅当重新配置了网关 audience 时才设置此项。
`--gateway-issuer <url>`	网关用于验证的 OIDC 签发方。留空时使用 Google 流程；与 `--oidc-client-id` 一同设置，可针对非 Google 身份提供商运行设备代码流程。
`--oidc-client-id <id>`	用于设备代码流程的公网 OIDC 客户端 ID，已在 `--gateway-issuer` 注册并启用设备授权。
`--token-file <path>`	包含预先生成的 OIDC ID 令牌的文件；该令牌将作为 Bearer 令牌使用，并绕过其他令牌提供商。
`--gateway-ca <path>`	用于验证网关证书的 CA bundle (自带证书) 。未设置时，使用通过 `gateway trust` 固定的证书；未固定证书的自签名网关会拒绝连接。

启用 session

标志	描述
`--duration <dur>`	session 保持激活状态的时长 (默认 `4h`，最长 `24h`) 。
`--reason <text>`	与 session 一同记录的可选自由文本原因 (最多 256 个字符) 。
`--user <name>`	在本地文件模式下记录的操作员身份；默认为 `$SUDO_USER` 或 `$USER`。在 gateway 模式下，以 token 认证的电子邮件地址为准。

如果已有处于活动状态的 session，启用操作将失败；请先将其禁用，或等待其过期。

禁用 session

立即停用 session。未激活 session 时，此操作为空操作。

会话状态

显示会话是否处于活动状态、由谁启用及其到期时间。--output (-o) 可选择 table (默认) 或 json。在 Kubernetes 中，通过端口转发访问网关：

kubectl -n <connector-namespace> port-forward \
  statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 1h --reason "support ticket 1234"

clicklink clctl troubleshoot gateway trust

在 VM 上，session 网关使用自签名 TLS 证书。此命令会将证书的 SHA-256 指纹记录到 ~/.clicklink/clctl.yaml，以便 session 命令验证该证书；若固定的指纹不再匹配，验证将失败并拒绝连接。可通过以下两种带外方式之一建立信任：

使用远程通道标志时，会通过已完成身份验证的通道直接从 VM 读取并固定证书。
不使用通道时，传入 --gateway-fingerprint，其值为连接器生成证书时记录的 SHA-256 指纹；仅当获取的证书与其匹配时才会固定。省略该标志会打印出当前提供的指纹，但不会固定任何内容。

标志	描述
`--gateway-url <url>`	要信任的网关基础 URL (必填) ，例如 `https://<vm-host>:8443`。
`--gateway-fingerprint <sha256>`	连接器日志中记录的预期 SHA-256 指纹，固定前会进行验证。忽略冒号和字母大小写。
`--remote-cert-file <path>`	VM 上网关证书的路径，通过通道读取 (默认为 `/var/lib/clicklink/gateway/tls/server.crt`) 。

clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<vm-host>:8443 \
  --gateway-fingerprint <sha256-from-connector-log>

在 Kubernetes 中，不使用固定方式：应通过具有 CA 签发证书的入口公开网关，或使用端口转发。

clicklink clctl troubleshoot audit tail

打印故障排除程序审计日志中的最后几条记录：采用以换行分隔的 JSON 格式，守护进程接受或阻止的每条命令各对应一条记录。该命令以只读方式打开日志，绝不会对其进行修改。

标志	说明
`--lines <n>`, `-n`	要打印的尾随记录数 (默认为 50) 。
`--path <path>`	审计日志文件的路径 (默认为 `/var/log/clicklink/troubleshoot-audit.log`) 。

连接器的运行时镜像不包含 shell，因此在 Kubernetes 中，此命令是受支持的读取方式：

kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
  /clicklink clctl troubleshoot audit tail

访问凭据预配

clicklink clctl scraper access provision 和 clicklink clctl troubleshoot access provision 会创建组件每个实例的访问包；使用 --force 时会轮换该访问包。访问包包括只读 ClickHouse 用户及其授权，以及组件所使用的 Kubernetes ServiceAccount、RBAC 和令牌。init 会在安装期间内联执行此操作；独立命令则用于重新执行和轮换。

标志	说明
`--instance <name>`	配置中的实例名称 (必填) 。
`--server <url>`	Kubernetes API 服务器 URL (必填) 。
`--ca-data <base64>`	用于生成 kubeconfig 的 Base64 编码集群 CA 证书。
`--config <path>`	用于读取实例信息的连接器配置文件。
`--target <shape>`	`systemd` (默认：通过远程通道将访问包发送到 VM，或使用 `--provider local` 在本地生成) 或 `helm` (将访问包作为 Kubernetes Secret 推送到 chart) 。
`--target-namespace <ns>`	存放访问包 Secret 的命名空间 (使用 `--target helm` 时必填) 。
`--instance-namespace <ns>`	(`--target helm`) 目标 ClickHouse 实例所在的命名空间。
`--force`	覆盖现有访问包：用于重新执行和轮换凭据。
`--secret-name <name>`	覆盖访问包 Secret 的名称 (默认值为 `clicklink-connector-<component>-access-<instance>`) 。
`--output-dir <path>`	(`--target helm` 或 `--provider local`) 访问包的输出根目录。
`--ch-admin-user <name>`	用于应用授权的 ClickHouse 管理员用户 (默认值为 `default`) 。
`--ch-admin-password-stdin`	从 stdin 读取 ClickHouse 管理员密码。
`--ch-user-suffix <suffix>`	为预配的 ClickHouse 用户名指定可选后缀。
`--ch-user-via <mode>`	ClickHouse 用户的预配方式：`sql` (默认；以 `--ch-admin-user` 身份应用生成的授权) 或 `cr` (将用户写入实例的自定义资源，适用于由 operator 管理且没有可执行 SQL 的管理员的实例) 。
`--apply-ch-grants`	(`--target helm`) 通过 `kubectl exec` 在 pod (容器组) 中应用生成的授权，而非留待你自行应用。
`--ch-pod <ref>`, `--ch-pod-namespace <ns>`, `--ch-container <name>`	(`--target helm` 搭配 `--apply-ch-grants` 或 `--ch-user-via cr`) 选择要 exec 进入的 ClickHouse pod (容器组) 和容器。
`--token-duration <dur>`	ServiceAccount 令牌有效期 (默认 `2160h`，即 90 天；EKS 将令牌有效期限制为 24 小时) 。
`--skip-restart`	预配后跳过重启组件。
`--dry-run`	打印计划后退出；不会向 Kubernetes、远程系统或 ClickHouse 写入任何内容。

轮换某个组件中某个实例的凭据：

clicklink clctl scraper access provision --target helm \
  --target-namespace <connector-namespace> \
  --instance <instance-name> --instance-namespace <clickhouse-namespace> \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
  --force

远程通道标志

preflight、gateway trust 和 access provision 接受一组通用标志，用于指定连接到 VM 目标的方式：

标志	描述
`--provider <name>`	执行通道：对于远程 VM，可使用 `ssh`、`aws` (SSM) 或 `gcp` (IAP)；在目标 VM 上运行时，使用 `local`。未显式设置时，将根据各提供商相关的标志推断；绝不会推断为 `local`。
`--ssh-host <host>`, `--ssh-user <user>`, `--ssh-port <port>`, `--ssh-identity-file <path>`	SSH 连接信息 (`--provider ssh`) ；用户、端口和密钥默认采用你的 SSH 配置。
`--instance-id <id>`, `--region <region>`, `--profile <name>`	用于 SSM 的 EC2 实例、区域和共享配置 profile (`--provider aws`) 。
`--project <id>`, `--zone <zone>`, `--instance-name <name>`	用于 IAP 隧道的项目、可用区和实例 (`--provider gcp`) 。

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

clicklink clctl init

入口点

通用标志

签名选项 (仅限阶段 1)

仅适用于 Kubernetes 的标志

仅适用于 VM 的标志

标志冲突

clicklink clctl preflight

clicklink clctl troubleshoot session

共享选项

启用 session

禁用 session

会话状态

clicklink clctl troubleshoot gateway trust

clicklink clctl troubleshoot audit tail

访问凭据预配

远程通道标志

​clicklink clctl init

​入口点

​通用标志

​签名选项 (仅限阶段 1)

​仅适用于 Kubernetes 的标志

​仅适用于 VM 的标志

​标志冲突

​clicklink clctl preflight

​clicklink clctl troubleshoot session

​共享选项

​启用 session

​禁用 session

​会话状态

​clicklink clctl troubleshoot gateway trust

​clicklink clctl troubleshoot audit tail

​访问凭据预配

​远程通道标志

clicklink clctl init

入口点

通用标志

签名选项 (仅限阶段 1)

仅适用于 Kubernetes 的标志

仅适用于 VM 的标志

标志冲突

clicklink clctl preflight

clicklink clctl troubleshoot session

共享选项

启用 session

禁用 session

会话状态

clicklink clctl troubleshoot gateway trust

clicklink clctl troubleshoot audit tail

访问凭据预配

远程通道标志