support session

support session 通过 ClickHouse 连接器向 ClickHouse 授予临时诊断访问权限。本页介绍会话的定义、如何启用和禁用会话、会话期间 ClickHouse 支持工程师可执行的操作，以及如何对其进行审计。

什么是 support session

support session 是一段有时限的窗口期，在此期间故障排查工具会接受 ClickHouse 支持工程师下发的命令。在会话之外，即使其 outbound WebSocket 仍处于连接状态，它也会拒绝一切命令。除此之外没有其他执行路径，而 ClickHouse 也无法替你开启会话。ClickHouse Cloud 绝不会主动连入你的环境；它只接收故障排查工具通过其 outbound 通道发送的内容。会话仅管辖诊断操作。managed 模式下 services 的生命周期命令通过 executor 的独立通道传输，support session 既不会开启该通道，也不会对其进行 gate；参见 managed services。你可以通过两种途径控制会话：

会话gateway：嵌入在故障排查工具中的一个需身份验证的 API。它提供 POST /v1/clctl/session/enable、POST /v1/clctl/session/disable 和 GET /v1/clctl/session/status。每次调用都需要一个短期有效的 OIDC ID token，且其邮箱必须在你的操作员允许列表中。
本地会话文件：适用于 Linux VM 安装方式，以 root 权限写入主机。

gateway的传输方式取决于 target。VM gateway使用 self-signed TLS，由每个操作员进行指纹固定。Kubernetes gateway在 pod (容器组) 本地通过 HTTP 监听；你可以通过 kubectl port-forward (隧道借助 API server 的 TLS) 访问它，也可以通过使用 CA 签发证书 terminates TLS 的入口访问。你在执行 clicklink clctl init 时选择会话策略，其中包括操作员允许列表。

启用和禁用会话

Kubernetes
Linux VM

gateway 监听故障排查工具 pod (容器组) 的 8443 端口。如果有集群访问权限，可通过端口转发访问它：

CONNECTOR_NAMESPACE='clicklink'   # 初始化时选择的连接器命名空间
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward statefulset/clicklink-connector-troubleshooter 8443:8443

然后，在另一个终端中启用会话：

clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 4h \
  --reason "<ticket reference>"

同样可以检查或结束会话：

clicklink clctl troubleshoot session status --gateway-url http://localhost:8443
clicklink clctl troubleshoot session disable --gateway-url http://localhost:8443

调用方的 OIDC 身份必须在操作员允许列表中。未经身份验证或不在允许列表中的调用方将收到 401 或 403，且 gateway 会将此次尝试记录到日志中。若要让操作员无需集群凭据即可工作，可通过 chart 中选择性启用的入口公开 gateway，它会使用 CA 签发的证书终止 TLS；请参阅配置。

如果拥有主机的 root 访问权限，可直接管理会话。守护进程和命令行客户端会以原子方式读写状态文件 /var/lib/clicklink/session.json：

sudo clicklink clctl troubleshoot session enable --duration 4h --reason "<ticket reference>"
sudo clicklink clctl troubleshoot session status
sudo clicklink clctl troubleshoot session disable

VM 上的 gateway 也可供没有 root 访问权限的调用方使用。它提供自签名 TLS，因此每位会话用户只需固定一次 gateway 的证书指纹：

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

固定的指纹存储在 ~/.clicklink/clctl.yaml 中。如果提供的证书与其不匹配，连接将被安全地拒绝。如果 gateway 提供的是由你自己的 CA 签发的证书，则需在每个会话命令中通过 --gateway-ca 传入该 CA bundle。

会话过期

会话会自动过期。默认时长为 4 小时；session enable --duration 最长可接受 24 小时。过期时，或运行 session disable 后，故障排查工具将不再接受命令。禁用即可立即撤销访问权限：无需重启，也无需与 ClickHouse 协调。

操作员允许列表

每次gateway调用都会依据操作员电子邮件允许列表进行授权。匹配使用的是经验证的 OIDC 标记中验证的电子邮件，绝不使用客户端提供的值。

**Kubernetes：**在配置值覆盖中设置 clctl.gateway.allowedOperators。chart 会将该列表渲染为 ConfigMap，因此修改配置值后执行 helm upgrade 即可轮换允许列表，无需重启 pod (容器组) 。
**Linux VM：**允许列表位于 /etc/clicklink/allowed-operators.txt，由 clicklink clctl init 根据您提供的操作员电子邮件写入。

在这两种目标上，gateway都会在距上次读取超过 30 秒后的下一次请求时重新读取该文件。修改无需重启即可生效。

操作员在会话期间可以执行哪些操作

会话处于活动状态期间，ClickHouse 支持工程师可以运行两类命令。 只读 SQL 以 pcm_troubleshooter 用户身份在你的集群上执行，该用户的授权仅限于会话表允许列表。故障排查工具还会拒绝任何不以 SELECT、WITH、SHOW、DESCRIBE 或 EXPLAIN 开头的语句。该用户仅持有按表粒度的 SELECT 授权，不具备任何写入、DDL 或管理类特权。默认允许列表涵盖 system.parts、system.merges、system.replicas、system.metrics、system.settings 等 system 表。system.query_log 和 system.text_log 无法加入该列表：守护进程会拒绝列出这两张表的配置，因此永远不会为它们配置任何授权。默认允许列表中确实包含 system.processes，其 query 列会显示正在运行的语句文本。如果不希望实时查询文本在会话中被看到，请将其从 troubleshooter.allowedTables (Helm 覆盖文件) 或 troubleshooter.allowed_tables (VM 配置文件) 中移除。 只读 Kubernetes 视图指在已授权的命名空间中，对 pod (容器组) 、pod 状态、pod 日志、service、configmap、event、PersistentVolumeClaim、deployment、statefulset 和 replicaset 执行 get、list 和 watch。在两种安装目标上，访问包均绑定到 Kubernetes ServiceAccount。若未配置访问包，故障排查工具会直接拒绝 kubectl 类命令。executor 只会为 managed service 配置抓取器，不会配置故障排查工具；参见 managed service 的 support sessions。故障排查工具的 RBAC 不包含 exec、delete 或 patch 权限，因此操作员无法在你的 pod (容器组) 中打开 shell，也无法通过会话更改任何内容。完整的授权与 RBAC 清单参见特权模型参考文档。

审计日志

会话期间执行的每条命令都会以每行一个 JSON 对象 (NDJSON) 的形式追加写入 /var/log/clicklink/troubleshoot-audit.log。被阻止的命令同样会被记录，并由 blocked_by 说明原因 (例如 session inactive) 。submitted_by 是命令通道上的组织 ID：也就是你自己的组织 ID。具体是哪位 ClickHouse 工程师，记录在 ClickHouse Cloud 一侧，而不在该文件中。一条会话命令记录如下所示：

{
  "timestamp": "2026-06-22T22:30:00.123456789Z",
  "command_id": "11111111-2222-4333-8444-555555555555",
  "submitted_by": "<org-id>",
  "command_type": "sql",
  "command_text": "SELECT database, table, active, count() FROM system.parts GROUP BY ALL",
  "instance_id": "analytics",
  "status": "completed",
  "duration_ms": 42,
  "output_lines": 12
}

status 表示命令执行结果：completed、error 或 rejected。 Gateway 调用会单独记录。每次调用 (包括被拒绝的调用) 都会以结构化的 clctl.gateway 行写入故障排查工具自身的日志：在 VM 上是 journal，在 Kubernetes 上是容器日志。该行包含 submitted_by (由已校验标记证明的邮箱地址，绝不会采用客户端提供的值) 和 command_type (clctl.session.enable、clctl.session.disable 或 clctl.session.status) 。该行还包含 reason (启用时传入的 --reason) 、remote_addr 和 status。status 的取值为 ok、unauthorized、forbidden、rate_limited、bad_request、conflict 或 error，因此被拒绝的访问同样会出现在日志中。 VM 上的本地会话变更不属于审计日志条目。发起操作的主机用户会以 enabled_by 的形式记录在 /var/lib/clicklink/session.json 中，并通过 session status 显示。在 VM 上，使用 clicklink clctl troubleshoot audit tail 读取审计日志。在 Kubernetes 上，日志位于故障排查工具 pod (容器组) 内部，而容器镜像中没有 shell，因此需通过 kubectl exec 调用该二进制文件自带的读取器：

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl -n "${CONNECTOR_NAMESPACE}" exec statefulset/clicklink-connector-troubleshooter -- \
  /clicklink clctl troubleshoot audit tail

审计日志只是环境中的一个普通文件；可以像处理其他主机或容器日志一样，将其发送到你自己的 SIEM。

脱敏

故障排查工具返回的所有内容在离开您的环境前都会经过脱敏处理。内置模式可识别 IPv4 和 IPv6 地址、Bearer 令牌、AWS 访问密钥、电子邮件地址、JWT、SSH 私钥，以及嵌入连接字符串中的凭据。您可以在 /etc/clicklink/redaction-patterns.yaml 中扩展或覆盖这些模式；与内置模式同名的条目会将其替换。模式文件无效时，守护进程会拒绝启动，clicklink clctl preflight 也会验证该文件，因此脱敏配置损坏时会明确报错。

Architecture：连接器建立的所有连接，以及会话相关的数据流。
Configuration：gateway、允许列表和脱敏设置。
FAQ：简要解答有关吊销、审计和数据出站的问题。

入门

服务与基础设施

自备 Cloud

数据与集成

连接与查询

访问管理

安全与合规

监控与备份

AI 工具与智能体

Cloud API

账单

支持

ClickHouse Private

什么是 support session

启用和禁用会话

会话过期

操作员允许列表

操作员在会话期间可以执行哪些操作

审计日志

脱敏

​什么是 support session

​启用和禁用会话

​会话过期

​操作员允许列表

​操作员在会话期间可以执行哪些操作

​审计日志

​脱敏

​相关页面

什么是 support session

启用和禁用会话

会话过期

操作员允许列表

操作员在会话期间可以执行哪些操作

审计日志

脱敏

相关页面