运维操作

本页介绍连接器在两种安装目标上的日常运维。有关安装和引导设置，请参阅引导设置。服务本身的运维 (创建、扩缩容、删除和平台更新) 请参阅托管服务和平台更新。

升级

Kubernetes

日常 Kubernetes 运维操作需在工作站上使用 helm 命令行客户端。只有 init 内置 Helm 客户端，因此请在首次升级前安装 helm。

使用 init 暂存的配置值覆盖层，从公网 chart 仓库升级 release：

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm upgrade --install clicklink-connector clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version <version> \
  -n "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml

Chart 版本即不含前导 v 的发布标签 (chart X.Y.Z 对应标签 vX.Y.Z) 。已发布的 chart 已指向公网容器镜像，因此常规安装和升级无需指定镜像配置值。如需查看 chart 的默认配置，请运行 helm show values clicklink-connector --repo https://releases.clicklink.clickhouse.com/charts。executor 以单个副本运行，并采用 Recreate strategy，因此升级会导致其短暂断开连接。有关该时间窗口内命令的处理方式，请参阅连接器离线时。通过直接 chart 引用 (oci://、URL、本地归档文件或目录) 安装时，没有可用于解析的 repository。请在新版本中改为重新运行 helm upgrade clicklink-connector <same-chart-reference>。使用较新版本的命令行客户端重新运行 init 也能达到一致状态，但需要一个入口点：如果保留了支持包，则使用 --handoff；或者在按文档完成清理后，使用新的注册标记并添加 --force。上述 helm upgrade 是常规做法 (请参阅重新运行和恢复) 。

Linux VM

在主机上重新运行安装程序。它会像引导设置时一样下载并验证新版本。它会备份原有二进制文件，安装当前的 systemd 单元，并保留正在使用的脱敏规则和环境文件。然后重启守护进程：

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host
sudo systemctl restart clicklink-scraper clicklink-troubleshooter clicklink-executor

若要升级到指定版本而非最新版本，请在安装命令后加上 --version vX.Y.Z。

健康状况

每个守护进程都会在其健康检查端口提供 /livez 端点。健康状态信号是响应正文中的 JSON status 字段，而非 HTTP 状态码。Prometheus 指标在同一端口的 /metrics 上提供；没有单独的指标端口。两个目标的默认端口如下：

组件	健康检查端口
抓取器	8082
故障排查器	8084
executor	8086

executor 还会在 127.0.0.1:9999 上提供其本地命令 API。该 API 自身不带任何身份验证，也绝不会暴露到主机或 pod (容器组) 之外；clicklink clctl 服务命令会在本地访问它。启用支持会话后，gateway 还会监听 8443 端口：在 VM 上使用自签名 TLS；在 Kubernetes 上，可通过 kubectl port-forward 使用 pod (容器组) 本地 HTTP，或使用 TLS 终止入口。在 VM 上，您可以随时运行完整的检查套件：

sudo clicklink clctl preflight

它会检查配置、文件、端口冲突、网络可达性、ClickHouse 连通性、systemd 单元状态、各组件的访问权限、磁盘以及脱敏规则。如果任一检查失败，则以退出码 2 退出。

证书

connector 会自动续订其客户端证书。抓取器、故障排查工具和 executor 各自每 12 小时检查一次叶证书，并在剩余 10 天有效期时进行续订。续订通过现有的 mTLS 和 HMAC 身份验证通道返回有效期为 30 天的叶证书，因此无需 operator 执行任何操作。在 Kubernetes 上，守护进程会将续订后的叶证书写回 clicklink-mtls Secret；在 VM 上，则会写入 /etc/clicklink/tls/ 目录。要查看当前的到期时间：

# Linux VM
sudo openssl x509 -in /etc/clicklink/tls/client.crt -noout -enddate

# Kubernetes
CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl get secret clicklink-mtls -n "${CONNECTOR_NAMESPACE}" -o jsonpath='{.data.tls\.crt}' \
  | base64 -d | openssl x509 -noout -enddate

凭据轮换

API (HMAC) 凭据

向您的 account team 申请新的注册标记，然后使用 --enroll 和 --force 重新运行原来的 init 命令。保留首次安装时使用的所有目标专用标志 (--target-namespace、--values 以及任何 --chart、--chart-repo 或 --chart-version mirror 标志) ，因为 --force 会重新暂存已保留的配置。托管模式会从被替换的配置中沿用，因此这里的 --managed 是可选的。对于默认安装：

# Kubernetes, from your workstation
clicklink clctl init --enroll https://<subdomain>.<connector-domain> --target helm --force

# Linux VM, on the host
sudo clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force

在 VM 上，init 只会启用并启动尚未运行的单元，因此请在轮换后重启这些守护进程：

sudo systemctl restart clicklink-scraper clicklink-troubleshooter clicklink-executor

在 Kubernetes 上，init 会预先创建轮换后的 clicklink-hmac 和 clicklink-mtls Secret；chart 不会渲染它们。其 checksum annotation 不会覆盖这些 Secret，因此正在运行的 Pod (容器组) 仍会继续使用启动时的凭据。轮换完成后需重启所有组件：

kubectl rollout restart deployment,statefulset -n "${CONNECTOR_NAMESPACE}" \
  -l app.kubernetes.io/part-of=clicklink-connector

对于 SQL 配置需要密码的无人值守轮换，stdin 会依次传入两个密钥：第一行是标记，第二行是密码。读取标记时会恰好读取一行。

printf '%s\n' "$ENROLLMENT_TOKEN" "$CH_ADMIN_PASSWORD" | \
  clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force --ch-admin-password-stdin

ClickHouse 用户

为您自行注册的每个实例重新配置 connector 的只读用户。在 Kubernetes 上，请从您的工作站执行这些命令。--apply-ch-grants 会在 pod (容器组) 内重新应用新生成的授权，以便将新凭据同步到 ClickHouse；如果 admin 用户设置了密码，请添加 --ch-admin-password-stdin 并通过管道传入：

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
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
clicklink clctl troubleshoot 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

在虚拟机上，请在主机上运行这些命令，并通过管道传入 admin 密码；在这种情况下，除非传入 --ch-user-via cr，否则必须提供密码：

printf '%s\n' "$CH_ADMIN_PASSWORD" | sudo clicklink clctl scraper access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --ch-admin-password-stdin --force
printf '%s\n' "$CH_ADMIN_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --ch-admin-password-stdin --force

对于由 operator 管理的实例，请在任一命令形式中添加 --ch-user-via cr 和 pod (容器组) 选择标志；请参阅命令行客户端参考。

客户端证书

证书会自动续订 (参见证书) 。如需立即替换尚未过期的证书，请使用 --force 重新运行 init。随后重启每个组件，使守护进程使用新的叶证书：在 Kubernetes 上按 API 凭据一节所述操作，在 VM 上则重启这三个单元。

重复运行与恢复

init 支持幂等重复运行，因此遇到问题时，首先应再次运行相同的命令。未使用 --force 时，会保留现有的 /etc/clicklink/config.yaml (VM) 或 clicklink-values.yaml 覆盖文件 (Kubernetes) ，并复用现有的客户端密钥；init 会以原子方式覆盖凭据和 CA 链。命令行客户端在部分失败后输出的恢复命令可以安全地重复执行。 --force 会覆盖已保留的配置或覆盖文件，重新生成客户端密钥，并替换尚未过期的客户端证书。它绝不会生成新的集群 UUID，因此连接器的身份会保留。在无人值守的重复运行中，被替换配置的托管模式状态会被保留；在终端中运行时，该状态会作为默认值提供，除非你传入 --managed 或 --no-managed。如果暂存后证书签名失败，或者因已存在尚未过期的证书而导致签名端点返回 409，则无需新标记或再次签发。请使用磁盘上已有的已签名材料完成安装：

sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt

这是 VM 形式 (root 会改写 /etc/clicklink 并管理相关服务) 。在 Kubernetes 上，命令行客户端会输出完整形式，包括 --target helm、--target-namespace 和 --values；请按原样使用输出的命令。 连接器离线。 在连接器停机或不可达期间，其管理的服务仍会持续运行。集群中的 ClickHouse Operator 会维持它们的运行，而 executor 并不位于数据路径中。生命周期变更需要 executor 保持连接，因此在其重新连接之前不会应用任何变更。重启后，executor 会从其命令数据库中恢复在传输中的命令。对于 ClickHouse Cloud 再次下发的命令，将依据已记录的结果作出响应；只有失败的命令才会再次运行。关于没有 executor 连接时的生命周期命令，请参阅连接器离线时。

卸载

在卸载之前，请参照删除服务删除所有托管服务，并等待每个服务的销毁过程完成。若先移除连接器，这些服务将没有任何组件来执行其生命周期管理。

Linux VM

uninstall.sh 包含在发布 tarball 中。如果主机上没有保留已解压的 tarball，请拉取并解压一个 (参见手动下载和验证) 。在解压后的目录中运行 uninstall.sh：

sudo ./uninstall.sh

这会停止并禁用 clicklink-scraper、clicklink-troubleshooter 和 clicklink-executor 单元，并移除 systemd 单元和二进制文件。它会保留以下内容，以便后续重新安装时沿用现有配置：

/etc/clicklink，包括位于 /etc/clicklink/access/executor 下的 executor 访问包
/var/lib/clicklink，包括 executor 的命令数据库 executor.db 以及服务 registry
/var/log/clicklink
clicklink 用户

若还要移除这些内容：

sudo ./uninstall.sh --purge

executor 的集群级授权保存在你的 cluster 中，而不在主机上。当不再有任何 managed service 时，请以集群管理员权限将其移除：

kubectl delete validatingadmissionpolicybinding pcm-executor-prefix-guard
kubectl delete validatingadmissionpolicy pcm-executor-prefix-guard
kubectl delete clusterrolebinding pcm-executor-cluster
kubectl delete clusterrole pcm-executor-cluster
kubectl delete serviceaccount pcm-executor -n clicklink-system

该授权还创建了 clicklink-system 命名空间；当没有其他资源使用它时，请将其删除。

Kubernetes

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm uninstall clicklink-connector -n "${CONNECTOR_NAMESPACE}"

executor 的 PersistentVolumeClaim 带有 helm.sh/resource-policy: keep 注解，因此卸载后它会被保留下来，其上的命令数据库和服务 registry 也一并保留。init 创建的 Secret、platform approve 写入的平台支持包 Secret，以及 executor 维护的服务 registry ConfigMap 同样不归 chart 所有，卸载后也会继续存在。请显式删除它们。其中包括你自行注册的每个 instance、以及你为其 provision 了故障排查工具的每个 managed service (以该 service 命名) 所对应的 access Secret 与 ServiceAccount。--ignore-not-found 用于兼容那些从未创建过的 object，例如首次审批之前的平台支持包 Secret：

kubectl delete pvc -n "${CONNECTOR_NAMESPACE}" -l app.kubernetes.io/instance=clicklink-connector --ignore-not-found
kubectl delete secret clicklink-hmac clicklink-mtls clicklink-platform-bundle -n "${CONNECTOR_NAMESPACE}" --ignore-not-found
kubectl delete configmap clicklink-instance-registry -n "${CONNECTOR_NAMESPACE}" --ignore-not-found
kubectl delete secret -n "${CONNECTOR_NAMESPACE}" --ignore-not-found \
  clicklink-connector-scraper-access-<instance> \
  clicklink-connector-troubleshooter-access-<instance>
kubectl delete serviceaccount -n "${CONNECTOR_NAMESPACE}" --ignore-not-found \
  pcm-scraper-<instance> pcm-troubleshooter-<instance>
# Repeat for every ClickHouse namespace that holds an instance you registered yourself;
# a managed service's namespace went away with the service.
for ns in <clickhouse-namespace-1> <clickhouse-namespace-2>; do
  kubectl delete serviceaccount,role,rolebinding -n "${ns}" --ignore-not-found \
    pcm-scraper pcm-troubleshooter
done

init 应用的是 executor 的集群级授权，而非 chart。待不再存在任何 managed services 后，请以集群管理员权限将其移除：

kubectl delete validatingadmissionpolicybinding pcm-executor-prefix-guard
kubectl delete validatingadmissionpolicy pcm-executor-prefix-guard
kubectl delete clusterrolebinding pcm-executor-cluster
kubectl delete clusterrole pcm-executor-cluster
kubectl delete serviceaccount pcm-executor -n "${CONNECTOR_NAMESPACE}"

平台 layer

卸载连接器并不会移除平台 layer。平台命名空间与工作负载、pcm-platform RBAC，以及经你批准安装的 admission object 都会继续留在 cluster 中，所有 managed service 也是如此。请先删除这些 service，参见删除 service。在不含任何 service 的测试 cluster 上，clicklink clctl platform reset 会卸载平台 releases。它遗留的 CustomResourceDefinition、RBAC 和存储类仍需手动删除，参见重置测试 cluster。若不是测试 cluster，请在改动平台 layer 之前先与 account team 商定移除方案。

ClickHouse 用户

无论卸载任一目标端，在你自行注册的实例上，已预配的只读用户都会保留。请以管理员身份在每个实例上删除这些用户 (如果设置了 --ch-user-suffix，请将其附加到名称后) ：

DROP USER IF EXISTS pcm_scraper, pcm_troubleshooter;

入门

服务与基础设施

自备 Cloud

数据与集成

连接与查询

访问管理

安全与合规

监控与备份

AI 工具与智能体

Cloud API

账单

支持

ClickHouse Private

升级

Kubernetes

Linux VM

健康状况

证书

凭据轮换

API (HMAC) 凭据

ClickHouse 用户

客户端证书

重复运行与恢复

卸载

Linux VM

Kubernetes

平台 layer

ClickHouse 用户

​升级

​Kubernetes

​Linux VM

​健康状况

​证书

​凭据轮换

​API (HMAC) 凭据

​ClickHouse 用户

​客户端证书

​重复运行与恢复

​卸载

​Linux VM

​Kubernetes

​平台 layer

​ClickHouse 用户

升级

Kubernetes

Linux VM

健康状况

证书

凭据轮换

API (HMAC) 凭据

ClickHouse 用户

客户端证书

重复运行与恢复

卸载

Linux VM

Kubernetes

平台 layer

ClickHouse 用户