Skip to main content
本页不适用于 ClickHouse Cloud。本文所述流程在 ClickHouse Cloud 服务中已实现自动化。
本指南介绍如何以简单、最少的配置，让 ClickHouse 使用 OpenSSL 证书验证连接。为便于演示，这里会创建自签名的证书颁发机构 (CA) 证书和密钥，以及节点证书，并使用适当的配置建立连接。
TLS 的实现较为复杂，需要综合考虑许多选项，才能确保部署既安全又稳健。本教程仅提供基础内容和基本 TLS 配置示例。请与你们的 PKI/安全团队协作，为你的组织生成正确的证书。如需入门概览，请参阅这篇证书使用基础教程。
1

创建 ClickHouse 部署

本指南基于 Ubuntu 20.04 编写，且 ClickHouse 是在以下主机上通过 DEB 软件包 (使用 apt) 安装的。域名为 marsnet.local：
有关如何安装 ClickHouse 的更多信息，请参阅快速入门。
2

创建 TLS 证书

自签名证书仅用于演示，不应在生产环境中使用。应创建证书签名请求，并由组织进行签名，再使用将在设置中配置的 CA 证书链进行验证。不过，这些步骤可用于配置和测试相关设置，之后再替换为实际使用的证书。
  1. 生成一个将用于新 CA 的私钥：
  2. 生成一个新的自签名 CA 证书。以下命令将创建一个新证书，该证书将使用 CA 私钥为其他证书签名：
将私钥和 CA 证书备份到集群外的安全位置。生成节点证书后，应从集群节点中删除该私钥。
  1. 验证新 CA 证书的内容：
  2. 为每个节点创建证书签名请求 (CSR) 并生成私钥：
  3. 使用 CSR 和 CA 创建新的证书与私钥对：
  4. 验证证书中的 subject 和签发方：
  5. 检查新证书是否可通过 CA 证书验证：
3

创建并配置用于存储证书和密钥的目录

这一步必须在每个节点上执行。请在每台主机上使用相应的证书和密钥。
  1. 在每个节点上，创建一个 ClickHouse 可访问目录中的文件夹。建议使用默认配置目录 (例如 /etc/clickhouse-server) ：
  2. 将 CA 证书、节点证书以及与各节点对应的密钥复制到新的 certs 目录中。
  3. 更新所有者和权限，使 ClickHouse 能够读取这些证书：
4

使用 ClickHouse Keeper 配置基础版集群环境

在此部署环境中，每个节点均使用以下 ClickHouse Keeper 配置。每台服务器都有其独立的 <server_id>。 (例如，节点 chnode1 对应 <server_id>1</server_id>，其余节点以此类推。)
ClickHouse Keeper 建议使用 9281 端口。不过，该端口可配置；如果此端口在当前环境中已被其他应用占用，可改为其他端口。有关所有选项的完整说明，请访问 https://clickhouse.com/docs/operations/clickhouse-keeper/
  1. 在 ClickHouse server 的 config.xml 文件中，在 <clickhouse> 标签内添加以下内容
对于生产环境，建议在 config.d 目录中使用单独的 .xml 配置文件。 更多信息请参见 https://clickhouse.com/docs/operations/configuration-files/
当 ClickHouse Keeper 作为嵌入式组件运行在 ClickHouse server 中时 (如上所示) ，Keeper 会使用 在 ClickHouse 节点上配置 TLS 接口 中 OpenSSL 部分定义的 server OpenSSL 配置。如果将 ClickHouse Keeper 作为独立进程运行，则必须在 Keeper 配置文件中添加 <openSSL> 部分，并使用相同的 CA 证书以及节点证书/密钥设置。有关详细信息，请参阅下方的 为独立运行的 ClickHouse Keeper 配置 OpenSSL。
  1. 取消所有节点上 Keeper 设置的注释并更新，然后将 <secure> 标志设为 1：
  2. 在 chnode1 和 chnode2 上更新并添加以下集群设置。chnode3 将用作 ClickHouse Keeper 的仲裁节点。
对于此配置，仅配置了一个示例集群。测试用的示例集群必须删除或注释掉；如果存在正在测试的现有集群，则必须更新端口并添加 <secure> 选项。如果在安装时或在 users.xml 文件中，default 用户最初被配置了密码，则必须设置 <user 和 <password>。
以下将创建一个集群，该集群在两台服务器上各有一个分片副本 (每个节点一个) 。
  1. 定义宏配置值，以便创建用于测试的 ReplicatedMergeTree 表。在 chnode1 上：
    在 chnode2 上：
5

在 ClickHouse 节点上配置 TLS 接口

以下设置需要在 ClickHouse server 的 config.xml 中配置：
  1. 为部署设置显示名称 (可选) ：
  2. 将 ClickHouse 设置为监听外部端口：
  3. 在每个节点上配置 https 端口，并禁用 http 端口：
  4. 在每个节点上配置 ClickHouse Native 安全 TCP 端口，并禁用默认的非安全端口：
  5. 在每个节点上配置 interserver https 端口，并禁用默认的非安全端口：
  6. 使用证书和路径配置 OpenSSL
每个文件名和路径都必须更新为与当前配置的节点相匹配。 例如，在 chnode2 主机上进行配置时，应将 <certificateFile> 条目更新为 chnode2.crt。
如需了解更多信息，请访问此页面
  1. 在每个节点上为 gRPC 配置 TLS：
    如需了解更多信息，请访问 https://clickhouse.com/docs/interfaces/grpc/
  2. 在至少一个节点上配置 ClickHouse client，使其在自身的 config.xml 文件中通过 TLS 建立连接 (默认位于 /etc/clickhouse-client/) ：
  3. 禁用 MySQL 和 PostgreSQL 的默认模拟端口：
6

测试

  1. 逐个启动所有节点：
  2. 确认安全端口已启动并正在监听，每个节点上的输出应与以下示例类似：
  3. 检查 ClickHouse Keeper 的健康状态 常见的 4 字母命令 (4lW) 在未启用 TLS 时无法直接通过 echo 使用，以下说明如何用 openssl 执行这些命令。
    • 使用 openssl 启动一个交互式会话
  • 在 OpenSSL 会话中执行 4LW 命令
  1. 使用 --secure 参数和 TLS 端口启动 ClickHouse 客户端：
  2. 使用 https 接口登录位于 https://chnode1.marsnet.local:8443/play 的 Play UI。
浏览器会显示证书不受信任，因为这是从工作站访问的，而这些证书并不在客户端机器的根 CA 存储中。 如果使用由公共证书颁发机构或企业 CA 签发的证书，则应显示为受信任。
  1. 创建一个复制表：
  2. 在 chnode1 上添加几条记录：
  3. 通过查看 chnode2 上的数据行来验证复制：

​
为独立运行的 ClickHouse Keeper 配置 OpenSSL

当 ClickHouse Keeper 以独立进程方式运行时 (而不是嵌入在 ClickHouse server 中) ，必须在 Keeper 配置文件中单独配置 OpenSSL 证书和相关设置。否则，Keeper 将无法为客户端通信 (tcp_port_secure) 或 Keeper 节点之间的 Raft 复制建立安全连接。 将以下 <openSSL> 部分添加到每个节点上的独立运行的 ClickHouse Keeper 配置文件中：
必须将每个文件名更新为与其所在节点匹配。 例如，在 chnode2 主机上配置时，将 <certificateFile> 条目更新为 chnode2.crt。
<server> 部分用于通过安全的 Keeper 端口 (tcp_port_secure) 接收客户端传入连接。<client> 部分用于在 Raft 复制期间建立 Keeper 节点之间的出站连接。
上述证书路径使用 /etc/clickhouse-keeper/certs/，这是独立部署 Keeper 时的典型路径。如果你通过其他路径安装了 Keeper，请相应调整。证书本身与在步骤 2中创建的证书相同。

​
OpenSSL 验证模式和证书处理器

<openSSL> 配置支持多种 <verificationMode> 和 <invalidCertificateHandler> 选项，用于控制 ClickHouse 如何验证 TLS 证书。这些设置适用于 clickhouse-server、clickhouse-client 以及独立运行的 ClickHouse Keeper。

​
验证模式

在 <openSSL> 的 <server> 或 <client> 部分中设置 <verificationMode>：

​
无效证书处理器

在 <openSSL> 的 <server> 或 <client> 部分中设置 <invalidCertificateHandler>。该处理程序用于确定证书验证失败时如何处理。在服务器端，它控制对无效客户端证书的响应；在客户端，它控制对无效服务器证书的响应。

​
示例：禁用证书验证

禁用证书验证会取消 TLS 身份检查，使连接面临中间人攻击的风险。仅应在隔离的开发或测试环境中使用此配置。
如需完全跳过证书验证 (例如在测试环境中使用自签名证书时) ，请将 verificationMode 设置为 none，并使用 AcceptCertificateHandler。 对于 clickhouse-client，你也可以使用 --accept-invalid-certificate CLI 标志，该标志会自动应用这两项设置。 clickhouse-client (/etc/clickhouse-client/config.xml)：
clickhouse-server (config.xml 或 config.d/ 中的某个文件) 。<server> 部分仍然需要证书和密钥路径，因为即使服务器不验证客户端证书，也必须向客户端提供自己的证书：
独立运行的 ClickHouse Keeper (Keeper 配置文件) ：

​
无需重启即可轮换证书和 CA 证书

ClickHouse server 和 ClickHouse Keeper 会监视 openSSL.server 和 openSSL.client 配置段 (以及可组合协议的 protocols.* 配置段) 中由 certificateFile、privateKeyFile 和 caConfig 引用的文件；如果 caConfig 指向的是一个目录，则监视该目录下的文件。当其中任一文件发生变化，或执行 SYSTEM RELOAD CONFIG 时，证书会被重新加载，并用于所有新建立的 TLS 连接，包括 HTTPS、安全的原生协议、服务器间连接、到 Keeper 的连接，以及 Keeper 节点之间的 Raft 连接。已建立的连接仍会继续使用其建立时所用的证书。 若要在不停机的情况下轮换 CA，请先将 caConfig 文件替换为同时包含旧 CA 证书和新 CA 证书的证书包，然后将节点证书和客户端证书切换为由新 CA 签发的证书，最后再将该证书包替换为仅包含新 CA 证书的文件。

​
总结

本文重点介绍了如何为 ClickHouse 环境配置 TLS。生产环境中的具体设置会因需求不同而有所差异，例如证书验证级别、协议、密码套件等。不过，相信你现在已经对配置和建立安全连接所需的步骤有了较为清晰的认识。
最后修改于 2026年9月28日