Elasticsearch 5.6.x 开启X-Pack安全认证后客户端连接改造指南

Elasticsearch 5.6.x 开启X-Pack安全认证后客户端连接改造指南

发布时间：2026/10/15 9:35:53
Elasticsearch 5.6.x 开启X-Pack安全认证后客户端连接改造指南 1. 先说背景为什么这个版本会被卡住最近帮一个老项目做安全加固技术栈还停留在 Elasticsearch 5.6.x 系列项目方要求把 x-pack 安全认证开起来。本来以为只是改改配置的事结果一动手才发现最麻烦的根本不是服务端而是连不上来的那一堆客户端。尤其是同期在跑的一些定时任务和运维脚本既有老的 transport client 方式也有已经在用 HTTP 方式访问的 RestClient 调用两边都出现连接失败。这个版本其实很特殊。Elasticsearch 5.6.x 是最后一个还正式支持 Java transport client 的 5.x 版本再往后的 6.x、7.x 直接废弃了 transport client官方明说要用 REST 客户端代替。所以很多老系统卡在 5.6.x 不是没有原因——代码里全是 transport client 的调用动不动几千行升级客户端等于重写数据访问层没人敢动。但安全又不能在裸奔状态一直拖下去于是ES 5.6.x x-pack 开启安全后客户端怎么改连接方式就成了绕不开的话题。我这次对接的是某内部数据平台ES 集群是 5.6.16x-pack 装好后需要同时兼容两拨连接方老调度系统走原生 transport client端口 9300Java 代码直连。数据分析应用走 RestClient端口 9200HTTP 方式调_search和_bulk接口。开安全之前这俩都是明文直连不用密码、不用证书改完 x-pack 之后用户名、密码、SSL 证书全部需要落实。这篇文章我结合这次改造的具体过程把两种连接方式从配置到代码从头拆一遍包括我踩过的一些坑和最终采用的方案。如果你也正好卡在这个版本过渡或者后续要迁到更高版本 ES这篇内容可以作为一份完整参考。先说一个重要前提标题里的5.6.1X我理解是 5.6.x 全系列我实测以 5.6.16 为准配置项在 5.6.x 各小版本里差异不大。2. 彻底搞懂x-pack 到底拦住了什么要改连接方式得先搞清楚 x-pack 安全模块到底在哪些层面做了拦截。很多报错看着吓人其实本质就是三个层面的问题。2.1 传输加密层面TLS 把通道封住了x-pack 安全开启后可以启用传输层加密也就是 transport 协议走 TLS。原来你的 transport client 通过 9300 端口跟集群通信发的是二进制协议裸奔状态下没有加密抓包能看到内容。开启 TLS 后客户端和服务端做握手时会校验 CA 证书、信任链、主机名任何一个环节对不上握手就失败。HTTP 层同理。9200 端口原来是普通 HTTP开启 x-pack 之后可以打开 HTTPS或者保持 HTTP 但加上认证。RestClient 如果之前写死了http://地址不加证书信任、不带用户名密码访问会直接返回 401。需要注意5.6.x 的 x-pack 安全默认并不强制启用 TLS你如果只开了认证没开加密连接时报错主要是认证类错误。但我这次改造是内外网同时有流量安全策略要求加密也一并打开所以传输层和 HTTP 层全部走了 SSL。2.2 身份认证层面没有凭证就进不了门开启 x-pack 安全后ES 集群内部默认有几个内置用户比如elastic、kibana、logstash_system。这些用户默认密码要么自动生成要么你需要手动设置。所有客户端请求进来都需要做认证。transport client 连接时它走的是 transport 协议。虽然 transport client 和 RestClient 最终都是连同一个集群但认证入口不同transport client 需要在 Java 进程里设置xpack.security.user这个属性或者在代码里通过Settings配置用户名密码。RestClient 则是在 HTTP 请求头里加Authorization: Basic xxx也就是常见的 Basic 认证。如果服务端开启了 TLStransport client 还要额外加载信任证书RestClient 也要构造带有信任库的 SSLContext。这些在裸奔时代统统不存在。2.3 授权层面即使能认证没权限也白搭x-pack 还给内置用户分配了固定角色。elastic是超级用户什么都能干logstash_system只能干日志采集的事kibana用户只负责 Kibana 访问。如果客户端用的是某个内置用户权限不对的话即使密码对了执行操作时也可能报security_exception或action [indices:data/read/search] is unauthorized for user。所以改造客户端之前最好先想清楚每个调用方应该用哪个用户、带什么角色。我这次为了给老调度系统最小权限单独建了一个只读用户对特定索引只授予read和view_index_metadata权限。不要图省事全部用elastic一把梭后续审计的时候会很难受。3. 服务端准备先把 x-pack 安全侧配置到位客户端改连接方式之前服务端要先准备好否则客户端无论怎么改都会连不上。3.1 启用 x-pack 安全模块在 5.6.x 里安装 x-pack 插件后安全功能默认是关闭的必须在elasticsearch.yml里显式开启xpack.security.enabled: true加上这一行后ES 节点之间通信也会要求认证。这里有个隐藏点如果集群里节点不是同时改的配置会出现部分节点没启用安全、部分启用了然后节点之间互相报错表现为集群状态红黄切换。建议所有节点统一改好后再逐个滚动重启。3.2 配置 TLS 证书如果你要启用传输层加密需要先生成证书。5.6.x 提供了elasticsearch-certutil命令不过我在实际项目里用的是内部 CA 签发的证书这样各客户端能直接用统一 CA 做信任。服务端elasticsearch.yml核心配置如下xpack.security.transport.ssl.enabled: true xpack.security.transport.ssl.verification_mode: certificate xpack.security.transport.ssl.keystore.path: cert/elastic-certificates.p12 xpack.security.transport.ssl.truststore.path: cert/elastic-certificates.p12verification_mode我建议用certificate而不是full。full会校验主机名如果节点 IP 不是固定域名客户端连接容易踩主机名不匹配的坑。certificate只校验证书本身内网环境够用问题少很多。HTTP 层加密也要配上xpack.security.http.ssl.enabled: true xpack.security.http.ssl.keystore.path: cert/elastic-certificates.p12 xpack.security.http.ssl.truststore.path: cert/elastic-certificates.p123.3 设置内置用户密码x-pack 装好后内置用户密码需要初始化。最简单的做法是交互式设置bin/x-pack/setup-passwords interactive它会一个接一个提示你给elastic、kibana、logstash_system设置密码。注意这个操作必须在你确认安全配置已经启用之后执行否则会提示无法连接到集群。bin/x-pack/setup-passwords autoauto模式会生成随机密码并打印在终端适合一次性初始化。我这次用的是interactive方便后续交接给运维。3.4 验证服务端是否就绪配置改完后先别急着改客户端用 curl 验证一下 HTTPS 和认证是否都正常curl -k -u elastic:你的密码 https://localhost:9200如果返回带cluster_name和version的 JSON说明 HTTP 层 OK。再看 9300 端口是否正常监听节点日志里有没有 TLS 握手报错。服务端确认没问题再动客户端排查范围会小很多。4. 改造方案一transport client 连接方式先说最多老项目在用的 transport client。这个方式本质上是 Java 进程作为集群的一个伪节点通过 9300 端口跟集群通信。开启 x-pack 后transport client 的改造点有三个引入 x-pack 客户端依赖、设置用户名密码、加载信任证书。4.1 依赖引入5.6.16 对应的 transport client 要用配套版本的 x-pack transport 依赖。Maven 配置dependency groupIdorg.elasticsearch.client/groupId artifactIdtransport/artifactId version5.6.16/version /dependency dependency groupIdorg.elasticsearch.client/groupId artifactIdx-pack-transport/artifactId version5.6.16/version /dependency这里最容易踩的坑是版本必须严格对齐。ES 服务端 5.6.16客户端 transport 和 x-pack-transport 就得是 5.6.16差一个小版本都可能出现序列化兼容问题。4.2 配置用户名密码与信任库核心代码里创建一个TransportClient前需要先构造SettingsSettings settings Settings.builder() // 集群名要和 elasticsearch.yml 里的 cluster.name 一致 .put(cluster.name, my-es-cluster) // 开启 x-pack 安全认证 .put(xpack.security.user, es_read:你的密码) // 信任库路径这里用的是 p12 证书transport 和 http 共用 .put(xpack.ssl.truststore.path, /path/to/elastic-certificates.p12) .put(xpack.ssl.truststore.password, 你的证书密码) .put(xpack.ssl.truststore.type, PKCS12) .build();然后创建客户端TransportClient client new PreBuiltXPackTransportClient(settings) .addTransportAddress(new InetSocketTransportAddress( InetAddress.getByName(es-node-01), 9300));注意这里用的是PreBuiltXPackTransportClient不是原来的PreBuiltTransportClient。如果你继续用老的PreBuiltTransportClient启动时会直接抛异常提示 x-pack 客户端类找不到或者安全配置无法加载。4.3 transport client 认证机制的注意点从代码可以看到用户名密码是通过xpack.security.user这个设置项传进去的。transport client 在跟集群节点握手时会把这个凭证封装进握手消息里。如果密码配错报错信息通常不是密码错误而是类似failed to authenticate, authentication failed或者java.lang.IllegalArgumentException: couldnt authenticate against node这种报错藏在日志里不仔细看根本不知道是密码问题。我第一次遇到时还以为是证书路径写错折腾了半天才发现是密码里有一个特殊字符需要转义在Settings.builder().put()里直接传字符串没问题但如果你是用配置文件加载注意特殊字符要加引号。4.4 transport client 在高版本里的取舍5.6.x 的 transport client 能正常工作但官方已经明确标记为废弃后续到了 6.xtransport client 虽然还能用但不会再支持新的安全特性到 7.x 直接移除。所以如果你是借这次机会考虑未来升级推荐优先把新调用改成 RestClient 方式老系统暂时用 transport client 顶着两条腿走路平滑过渡。5. 改造方案二RestClient 连接方式再说 RestClient。这个是官方主推的方向通过 HTTP 协议访问 9200 端口跟语言无关Java、Python、命令行都适用。x-pack 开启后RestClient 的改造点和 transport client 完全不同核心是构造一个能信任服务端证书 能带上用户凭证的 HTTP 客户端。5.1 依赖引入使用官方 low-level RestClient需要引入dependency groupIdorg.elasticsearch.client/groupId artifactIdrest/artifactId version5.6.16/version /dependency如果你后续想用 high-level client对应 high-level 版本是 5.6.x 的早期形态但它在 5.6 时代还不够成熟建议 low-level 就够用。我这次改造里数据分析应用主要就是调用_search和_bulklow-level RestClient 完全能覆盖。5.2 让 RestClient 信任自签名证书服务端走了 HTTPS 之后RestClient 默认会校验证书除非你把证书加到 JVM 的cacerts里否则请求会直接报 SSL 握手失败。我采用的方式是加载 p12 信任库构造SSLContextPath trustStorePath Paths.get(/path/to/elastic-certificates.p12); char[] trustStorePassword 你的证书密码.toCharArray(); KeyStore trustStore KeyStore.getInstance(PKCS12); try (InputStream is Files.newInputStream(trustStorePath)) { trustStore.load(is, trustStorePassword); } TrustManagerFactory tmf TrustManagerFactory.getInstance( TrustManagerFactory.getDefaultAlgorithm()); tmf.init(trustStore); SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, tmf.getTrustManagers(), null);然后把SSLContext注入 RestClientRestClient restClient RestClient.builder( new HttpHost(es-node-01, 9200, https)) .setHttpClientConfigCallback(clientBuilder - { clientBuilder.setSSLContext(sslContext); return clientBuilder; }) .build();5.3 RestClient 的 Basic 认证接入证书信任解决了通道是否可靠接下来还要解决你是谁。最常用的方式是 Basic AuthString encodedCredentials Base64.getEncoder().encodeToString( es_read:你的密码.getBytes(StandardCharsets.UTF_8)); Request request new Request(GET, /my_index/_search); request.setHeader(Authorization, Basic encodedCredentials);或者用HttpClientConfigCallback里直接加默认凭证提供者setHttpClientConfigCallback(clientBuilder - { clientBuilder.setSSLContext(sslContext); clientBuilder.setDefaultCredentialsProvider(credentialsProvider); return clientBuilder; });其中credentialsProvider基于 Apache HttpAsyncClient 的CredentialsProviderCredentialsProvider credentialsProvider new BasicCredentialsProvider(); credentialsProvider.setCredentials( AuthScope.ANY, new UsernamePasswordCredentials(es_read, 你的密码));两种方式我都试过直接设置Authorization头更直观排查问题的时候一眼能看到请求有没有带凭证。用默认凭证提供者则更客户端化后续如果在同一连接上切换不同用户提供者要重新赋值。5.4 为什么推荐优先改造成 RestClient从这次改造经验看RestClient 有非常明显的好处代码改动小不依赖具体 ES 版本内部协议只要 HTTP 接口兼容后续从 5.6 升到 6.x、7.x 基本不用改调用方。transport client 则绑死了版本升级成本和风险都高很多。如果你所在团队正在维护老系统我的建议是新增功能一律走 RestClient存量功能能改就改改不动就先保留 transport client 顶着但新写的代码不要再用 transport client。6. 常见问题与排查实录整个改造过程里我整理了下面这几个高频问题每一个都是实际踩过的坑。6.1 认证失败但日志不能帮忙定位failed to authenticate是 transport client 最典型的报错但日志里往往不会直接写用户名密码错误。我遇到过一次原因是xpack.security.user的值里包含符号配置解析时被截断了。用Settings.builder().put()传值还好但如果是从 properties 文件加载建议用String完整字符串传入避免解析器按分隔符切割。排查思路先用 curl 验证同一个用户名密码能不能访问 HTTPS 端口。如果 curl 能通说明服务端账号密码没问题问题出在客户端取值或拼装上。6.2 SSLHandshakeException证书信任链断裂RestClient 访问时报javax.net.ssl.SSLHandshakeException: PKIX path building failed99% 的原因是 JVM 里没有导入服务端证书。很多人会去改 JVM 的cacerts我个人不推荐因为这会影响所有 Java 应用而且升级 JVM 后要重新导入。建议像上文那样在代码里显式构造SSLContext只对当前客户端生效安全且可维护。还有一个小坑KeyStore.getInstance(PKCS12)加载 p12 文件时如果你的证书文件实际是 JKS 格式这里会报格式错误。注意服务端certutil生成的是什么格式保持一致。6.3 9300 端口通了但节点发现失败transprot client 连接时报NoNodeAvailableException: None of the configured nodes are available可能是集群名不对。cluster.name必须和elasticsearch.yml里一致这个是 transport client 的老规矩。也可能是只配置了一个 IP而该节点在同一时刻正在重启或者节点间通信由于 TLS 配置不一致导致客户端被拒绝。检查方法curl -k -u elastic:密码 https://es-node-01:9200/_cluster/health?pretty确认集群正常后再用如下地址测试 9300 端口是否可达nc -vz es-node-01 93006.4 HTTP 层 401 但浏览器能访问这个问题很迷惑。原因是浏览器可能缓存了旧的访问状态或者你访问的是 Kibana 的 5601 端口而程序访问的是 ES 的 9200 端口。RestClient 报 401 时先看请求里有没有Authorization头再看用户有没有对应索引的权限。还有一种情况Kibana 用户和 ES 用户的密码都被改了但某个服务还是在用旧配置文件。逐个排查别信肯定改过了这种话用curl直接验证最快。6.5 x-pack 版本与服务端不一致如果你项目里原有的 transport client 是 5.6.0而服务端升级到 5.6.16且开了 x-pack那么客户端必须同步升到 5.6.16 的x-pack-transport。否则可能出现类冲突或者请求数据序列化失败java.io.StreamCorruptedException: invalid internal transport message format这种报错第一反应一般是网络问题实际是版本不兼容。记住一个原则客户端 transport 依赖版本必须和服务端大版本、小版本完全一致这是老版本 ES 的一大痛点。6.6 常见问题速查表现象可能原因首选排查方式transport client 报 failed to authenticate用户名密码错误curl 验证账号RestClient 报 PKIX path building failed证书未信任构造 SSLContext 加载证书9300 连接超时端口被防火墙拦nc 测试端口NoNodeAvailableException集群名不对检查 cluster.name401 Unauthorized未带认证头抓请求头StreamCorruptedException客户端版本与服务端不一致对齐版本7. 实操心得与后续建议这次改造给我的最大体会是ES 5.6.x 的安全改造难点不在服务端配置而在客户端兼容上。服务端只要按部就班启用 x-pack、配证书、设密码基本不会有大坑。真正耗时的是梳理所有调用方哪些走 transport client、哪些走 RestClient各自要准备什么配置、代码要改哪里还要留出足够时间给业务方做回归测试。有一个小技巧可以分享我给每个调用方单独准备了一个只读用户而不是共用一个超级用户。这样不仅权限可控而且哪个服务出问题日志里能直接定位到具体用户排查效率高很多。另外RestClient 是我强烈建议的统一方向。如果你手头的老系统还在犹豫要不要从 transport client 迁移我的建议是趁这次安全改造的窗口期一起迁。虽然迁移的时候要改不少代码但从 5.6.x 迁到后续大版本时RestClient 的兼容性优势会体现得很明显。transport client 虽然是老项目里最常见的方式但继续守着的门槛会越来越高。如果你也在做类似的改造先梳理好客户端清单再一步步改配置、改代码、验证连接就能少走不少弯路。