版本：4.x

TLS 链路加密

本文档介绍如何为 FE、BE 以及节点间通信开启统一 TLS 链路加密，并说明证书鉴权、证书热更新与协议级控制方式。

适用范围

推荐优先使用统一 TLS 配置 enable_tls，而不是分别配置单协议的 enable_https 或 enable_ssl。统一 TLS 可以覆盖更多通信链路，并统一证书加载与轮转逻辑。

组件	统一 TLS 可覆盖的协议
FE	`http`、`mysql`、`thrift`、`brpc`、`arrowflight`、`bdbje`
BE	`http`、`thrift`、`brpc`、`arrowflight`

enable_https 和 enable_ssl 仍然可用，但更适合作为兼容旧部署的单协议配置项。

证书准备

统一 TLS 使用服务端证书、私钥和 CA 证书。建议使用 PEM 格式文件，并确保：

证书中的 SAN 与实际访问域名或 IP 一致。
集群内部如果启用了双向校验，客户端证书同样由受信任 CA 签发。
FE 和 BE 的证书私钥权限设置为仅对 Doris 运行账号可读。

快速开启

FE 配置

编辑 conf/fe.conf：

enable_tls = true
tls_certificate_path = /path/to/server.crt
tls_private_key_path = /path/to/server.key
tls_ca_certificate_path = /path/to/ca.crt
tls_verify_mode = verify_peer
tls_cert_refresh_interval_seconds = 3600

如果私钥文件带密码，可额外配置：

tls_private_key_password = your_private_key_password

BE 配置

编辑 conf/be.conf：

enable_tls = true
tls_certificate_path = /path/to/server.crt
tls_private_key_path = /path/to/server.key
tls_ca_certificate_path = /path/to/ca.crt
tls_verify_mode = verify_peer
tls_cert_refresh_interval_seconds = 3600

完成配置后，重启 FE 和 BE 使配置生效。

访问入口与端口

统一 TLS 与旧版 enable_https 的端口行为不同，建议按下面理解：

FE 的 HTTP 协议启用统一 TLS 后，会直接在 http_port 上提供 HTTPS 服务，默认端口仍是 8030。
FE 的 MySQL 协议启用统一 TLS 后，仍然使用 query_port，默认端口是 9030。
https_port 主要用于旧版 enable_https 方案；如果使用统一 TLS，不应把它当作主要访问入口。

也就是说，统一 TLS 下访问 FE HTTP 接口时，应优先使用：

https://fe.example.com:8030

而不是 https://fe.example.com:8050。

核心参数

FE 与 BE 共享参数

参数	默认值	说明
`enable_tls`	`false`	是否开启统一 TLS。
`tls_verify_mode`	`verify_peer`	证书校验模式。
`tls_certificate_path`	空	服务端和客户端角色共用的证书路径。
`tls_private_key_path`	空	私钥路径。
`tls_ca_certificate_path`	空	CA 证书路径。
`tls_cert_refresh_interval_seconds`	`3600`	证书轮询刷新周期，单位秒。
`tls_excluded_protocols`	空	不启用 TLS 的协议列表，逗号分隔。
`tls_peer_cert_required_san_dns`	空	基于对端证书 DNS SAN 的协议级准入控制。

FE 专有参数

参数	默认值	说明
`tls_private_key_password`	空	加密私钥文件的密码。
`tls_cert_based_auth_ignore_password`	`false`	用户配置了 `REQUIRE SAN` 且证书校验通过后，是否允许免密登录。

`tls_verify_mode` 取值

取值	说明
`verify_none`	不校验证书。仅适合测试环境。
`verify_peer`	校验对端证书，但不强制要求对端一定提供证书。
`verify_fail_if_no_peer_cert`	强制要求对端提供可被 CA 验证的证书。适合 mTLS。

按协议排除 TLS

如果只想对部分链路启用 TLS，可以通过 tls_excluded_protocols 排除协议：

tls_excluded_protocols = arrowflight

FE 可识别的协议名包括 thrift,mysql,http,brpc,arrowflight,bdbje，BE 可识别的协议名包括 thrift,http,brpc,arrowflight。

双向认证（mTLS）

如果希望节点间或客户端与服务端之间强制使用双向认证，可以将 tls_verify_mode 设置为：

tls_verify_mode = verify_fail_if_no_peer_cert
tls_ca_certificate_path = /path/to/ca.crt

此时客户端需要提供受该 CA 信任的证书和私钥。例如使用 MySQL 客户端连接 FE：

mysql -h fe.example.com -P 9030 -uroot \
  --ssl-mode=VERIFY_CA \
  --ssl-ca=/path/to/ca.crt \
  --ssl-cert=/path/to/client.crt \
  --ssl-key=/path/to/client.key

使用 HTTPS 访问 Stream Load 时：

curl --location-trusted -u user:password \
  --cacert /path/to/ca.crt \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  -H "label:tls-demo" \
  -T data.csv \
  https://fe.example.com:8030/api/db/table/_stream_load

如果只是先验证单向 TLS 是否已经生效，可以先执行：

curl -I --cacert /path/to/ca.crt \
  https://fe.example.com:8030/

证书鉴权

用户级证书鉴权当前仅支持：

REQUIRE SAN '...'
REQUIRE NONE

ISSUER、SUBJECT、CIPHER 以及多个条件组合当前不支持。

为用户配置证书要求

CREATE USER 'etl_user'@'%' IDENTIFIED BY 'Password@123'
REQUIRE SAN 'DNS:client.example.com,URI:spiffe://etl,EMAIL:etl@example.com';

ALTER USER 'etl_user'@'%' REQUIRE SAN 'DNS:client.example.com';

ALTER USER 'etl_user'@'%' REQUIRE NONE;

证书 SAN 校验基于条目逐项匹配。建议直接按证书中的 SAN 条目原样填写，避免因为条目缺失或大小写不一致导致认证失败。

免密证书登录

默认情况下，即使证书校验通过，仍需要校验密码。若希望对配置了 REQUIRE SAN 的用户启用免密登录，可在 FE 中设置：

tls_cert_based_auth_ignore_password = true

该配置仅在用户配置了 TLS 证书要求且证书验证成功时生效。没有配置 REQUIRE SAN 的用户不会因为该参数而绕过密码校验。

对端证书 DNS SAN 准入控制

tls_peer_cert_required_san_dns 用于限制集群内部对端证书的 DNS SAN，只支持 thrift 和 brpc 两个协议段，格式如下：

tls_peer_cert_required_san_dns = brpc=be-1.internal,be-2.internal;thrift=fe-1.internal,fe-2.internal

启用该能力前，需要同时满足以下条件：

已开启 enable_tls = true。
未通过 tls_excluded_protocols 排除对应协议。
tls_verify_mode = verify_fail_if_no_peer_cert。
tls_ca_certificate_path 已正确配置。

如果上述条件不满足，相关协议的 SAN 准入控制不会按预期生效。

证书热更新

统一 TLS 支持按 tls_cert_refresh_interval_seconds 周期轮询证书文件并自动刷新，无需因续期而长时间中断服务。

建议在替换证书时遵循以下顺序：

先替换私钥文件。
再尽快替换对应证书文件。
保持证书链与私钥成对更新。

这样可以降低轮询窗口内读到不匹配证书对的风险。

连接验证

验证 HTTPS

openssl s_client -connect fe.example.com:8030 -servername fe.example.com -CAfile /path/to/ca.crt

验证 MySQL TLS

mysql -h fe.example.com -P 9030 -uroot \
  --ssl-mode=REQUIRED

如果启用了双向认证，请同时加上 --ssl-ca、--ssl-cert 和 --ssl-key 参数。

与旧配置的关系

如果你只需要临时为 FE HTTP 接口开启 HTTPS，仍可使用 enable_https、key_store_path 等旧参数；如果只需要为 MySQL 端口开启 TLS，仍可使用 enable_ssl、ssl_force_client_auth 等旧参数。

但在新部署或需要覆盖多种链路的场景中，建议统一采用本文档中的 enable_tls 方案，避免在多个协议上分别维护不同的证书与配置口径。

适用范围​

证书准备​

快速开启​

FE 配置​

BE 配置​

访问入口与端口​

核心参数​

FE 与 BE 共享参数​

FE 专有参数​

tls_verify_mode 取值​

按协议排除 TLS​

双向认证（mTLS）​

证书鉴权​

为用户配置证书要求​

免密证书登录​

对端证书 DNS SAN 准入控制​

证书热更新​

连接验证​

验证 HTTPS​

验证 MySQL TLS​

推荐使用流程​

与旧配置的关系​