ClickHouse桌面客户端连接失败：如何排查SSL/TLS配置错误？

Question

常见问题：使用DBeaver、DataGrip或ClickHouse官方客户端连接时提示“SSL handshake failed”“certificate verify failed”或“connection reset”，但HTTP端口（8123）可通、TCP端口（9000）却无法建立加密连接。根本原因多为客户端与服务端TLS配置不匹配：服务端未启用`openSSL`配置、证书链不完整或自签名证书未导入客户端信任库；客户端未正确设置`ssl=true`、`sslmode=verify-full`等参数，或忽略证书校验时误用`sslmode=disable`导致协议协商失败；此外，Java客户端（如DBeaver）还需额外将服务端CA证书导入JVM `cacerts`，而CLI工具（clickhouse-client）则依赖`--ca_certificates`指定路径。时间不同步、TLS版本不兼容（如服务端强制TLS 1.3而客户端仅支持1.2）亦会静默中断握手。排查需逐层验证：`openssl s_client -connect host:9000 -servername host`测试底层SSL连通性，再比对服务端`config.xml`中``段与客户端连接字符串参数一致性。

Answer 1

```html

一、现象层：典型错误日志与表征特征

• SSL handshake failed —— TLS 握手在 ClientHello/ServerHello 阶段即中断，常因协议版本、密码套件不兼容或服务端未启用 TLS 导致
• certificate verify failed —— 客户端校验服务端证书失败，根源多为自签名证书未信任、CA 证书链缺失、主机名（SAN）不匹配或证书过期
• connection reset —— TCP 连接被服务端主动 RST，常见于 OpenSSL 配置错误（如 <openSSL> 块缺失 <server> 或私钥权限异常）或 TLS 协商失败后的静默拒绝
• HTTP 端口（8123）可通但 TCP 端口（9000）SSL 连接失败 → 明确指向 ClickHouse 原生协议层 TLS 配置失效，而非网络连通性问题

二、协议层：TLS 握手关键路径与失败断点

下图展示 ClickHouse SSL 连接建立的典型交互流程及常见故障注入点：

flowchart LR
  A[Client: openssl s_client -connect host:9000] --> B[Server: TCP SYN-ACK]
  B --> C[Client Hello TLS 1.2/1.3]
  C --> D{Server Config Valid?}
  D -- No → E[Connection Reset / EOF]
  D -- Yes → F[Server Hello + Certificate Chain]
  F --> G{Client Trusts CA? SAN Matches? Time Valid?}
  G -- No → H[certificate verify failed]
  G -- Yes → I[Key Exchange & Finished]
  I --> J[Authenticated Native Protocol Session]

三、服务端配置层：OpenSSL 模块深度解析

配置项	必需性	典型错误	修复示例
<openSSL> 块是否启用	✅ 强制	注释掉整个块或未加载 OpenSSL 库	<openSSL><server><certificateFile>/etc/clickhouse-server/server.crt</certificateFile>...</server></openSSL>
证书链完整性	✅ 强制	仅含 server.crt，缺失 intermediate.crt 或 root.crt	合并为 cat server.crt intermediate.crt root.crt > fullchain.pem 并在配置中引用
TLS 版本限制	⚠️ 推荐显式声明	<tlsV1>true</tlsV1> 未设，导致旧客户端协商失败	显式启用：<tlsV1>true</tlsV1><tlsV1_1>true</tlsV1_1><tlsV1_2>true</tlsV1_2><tlsV1_3>false</tlsV1_3>

四、客户端适配层：三大工具差异化处理策略

1. DBeaver（Java JVM）：
   必须将服务端根 CA 证书导入 JVM $JAVA_HOME/jre/lib/security/cacerts：
   keytool -import -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -alias clickhouse-ca -file ca.crt
   连接字符串参数：ssl=true&sslmode=verify-full&sslrootcert=/path/to/ca.crt
2. DataGrip：
   同样依赖 JVM truststore，但支持 UI 界面导入证书（Database → Driver → Options → SSL Root Certificate）；
   若使用 JetBrains Runtime，需向 jetbrains-jbr/lib/security/cacerts 导入。
3. clickhouse-client（CLI）：
   不走 JVM，直接调用 OpenSSL：
   clickhouse-client --host ch.example.com --port 9000 --secure --ca_certificates /etc/clickhouse-server/ca.crt --cert_file /path/client.crt --key_file /path/client.key

五、诊断验证层：分层排查命令清单

• ✅ 底层 TLS 连通性：openssl s_client -connect ch.example.com:9000 -servername ch.example.com -showcerts -verify 9（验证证书链）
• ✅ 服务端配置语法检查：clickhouse-server --config-file /etc/clickhouse-server/config.xml --test-config
• ✅ 时间同步确认：timedatectl status | grep "System clock"（误差 >5s 可致证书校验失败）
• ✅ 密码套件协商测试：openssl s_client -connect ch.example.com:9000 -cipher 'DEFAULT@SECLEVEL=1' -tls1_2（强制 TLS 1.2）
• ✅ 日志精确定位：grep -i "ssl\|tls\|certificate" /var/log/clickhouse-server/clickhouse-server.err.log | tail -20

六、生产加固层：企业级 TLS 最佳实践

面向 5+ 年经验工程师的进阶建议：

• 禁用 TLS 1.0/1.1，启用 OCSP Stapling 减少证书吊销查询延迟
• 采用 Let’s Encrypt + certbot 自动轮转，配合 <reloadable>true</reloadable> 实现零停机证书更新
• 对 clickhouse-client 使用双向 TLS（mTLS），在 <openSSL><client> 中配置 <verificationMode>strict</verificationMode>
• 在 Kubernetes 环境中，通过 Secret 挂载证书，并设置 securityContext.readOnlyRootFilesystem=true 防止私钥篡改
• 审计所有客户端连接字符串，禁止出现 sslmode=disable 或 ssl=false —— 此类配置会绕过加密，触发协议降级至非安全模式并被服务端拒绝

```