> 9.0 起，用证书模式配置远程集群会在弃用日志里产生警告。官方说它"将在未来主版本移除"，推荐迁移到 API key 模式——理由是后者能做**细粒度访问控制**。如果你在用跨集群，这条值得排进计划。

## **说明**

本文描述问题及解决方法同样适用于 [腾讯云 Elasticsearch Service（ES）](https://cloud.tencent.com/document/product/845)。

**本文基于 `v9.4.2` 的 changelog、官方文档与服务端源码**。文中引用的行号都来自这个 tag，点链接能看到对应原文。

**迁移的具体步骤本文未展开**（官方有专门的迁移文档）；**示例命令按通用写法给出，未在集群上执行**。

## 官方条目

9.0 的 changelog 标为 deprecation（[9.0.0.yml 第 1785–1796 行 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/release-notes/changelog-bundles/9.0.0.yml#L1785-L1796)），**PR 120806**，`area: Security`。

（上一版把这条写成 PR 120807，实际 **120807 是 "Remove INDEX_REFRESH_BLOCK after index becomes searchable"**，见第 1797–1799 行；本条是 120806。）

details 说明了处置和方向：

> Certificate-based remote cluster security model is deprecated and will be removed in a future major version. Users are encouraged to migrate remote clusters from certificate to API key authentication. The API key-based security model is preferred way to configure remote clusters, as it allows to follow security best practices when setting up remote cluster connections and defining fine-grained access control.

impact 说了实际表现：

> If you have configured remote clusters with certificate-based security model, you should migrate remote clusters from certificate to API key authentication. Configuring a remote cluster using certificate authentication, generates a warning in the deprecation logs.

拆开：

* **证书模式已弃用**，将在**未来主版本移除**（没说是哪个版本）；
* 官方鼓励**迁移到 API key 认证**；
* 推荐理由：**能遵循安全最佳实践、能定义细粒度访问控制**；
* **当前的实际影响**：配置证书模式的远程集群会**在弃用日志里产生警告**。

## 两种模式是什么

远程集群（跨集群搜索/复制）需要解决一个问题：**怎么证明"我是谁"，以及"我能看什么"**。

ES 提供了两套安全模型：

**证书模式（certificate-based）**：靠 TLS 证书建立信任。配置了 CA 或者 truststore，远端集群就可信。

**API key 模式（API key-based）**：用专门的跨集群 API key 认证。这个 key 在创建时就绑定了**权限范围**。

官方推荐后者的关键理由是那句 `defining fine-grained access control`——**细粒度访问控制**。

这个差别值得展开：

* 证书模式证明的是"**这个集群是谁**"——身份层面的信任；
* API key 模式还能表达"**这个集群能访问什么**"——权限层面的控制。

举例：你可以给远程集群创建一个只能读某几个索引的 key。证书模式下做不到这一点——**证书能证明身份，但不携带权限信息**。

## 源码里的落点

上一版说"没找到弃用标记的位置"——**它在 `RemoteConnectionManager` 里**，不在 `x-pack` 的安全扩展里，所以按 security 相关的类名去搜搜不到。

**一，弃用告警的完整实现**（[`RemoteConnectionManager.java` 第 110–138 行 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/transport/RemoteConnectionManager.java#L110-L138)）：

```java
@Override
public void openConnection(DiscoveryNode node, @Nullable ConnectionProfile profile, ActionListener<Transport.Connection> listener) {
    assert profile == null || profile.getTransportProfile().equals(getConnectionProfile().getTransportProfile())
        : "A single remote connection manager can only ever handle a single transport profile";
    delegate.openConnection(
        node,
        profile,
        listener.delegateFailureAndWrap(
            (l, connection) -> l.onResponse(
                maybeLogDeprecationWarning(wrapConnectionWithRemoteClusterInfo(connection, clusterAlias, credentialsManager))
            )
        )
    );
}

private InternalRemoteConnection maybeLogDeprecationWarning(InternalRemoteConnection connection) {
    if (connection.getClusterCredentials() == null
        && (false == REMOTE_CLUSTER_PROFILE.equals(this.getConnectionProfile().getTransportProfile()))) {
        deprecationLogger.warn(
            DeprecationCategory.SECURITY,
            "remote_cluster_certificate_access-" + connection.getClusterAlias(),
            "The remote cluster connection to [{}] is using the certificate-based security model. "
                + "The certificate-based security model is deprecated and will be removed in a future major version. "
                + "Migrate the remote cluster from the certificate-based to the API key-based security model.",
            connection.getClusterAlias()
        );
    }
    return connection;
}
```

**三点值得留意**：

* **判据和文档一致**：`getClusterCredentials() == null`，也就是 keystore 里没有 `cluster.remote.<alias>.credentials` → 证书模式 → 打告警。这和文档第 50 行说的是同一条规则，源码是它的实现。
* **告警的 key 是 `remote_cluster_certificate_access-<别名>`**，分类是 `DeprecationCategory.SECURITY`。**排查时可以直接按这个 key 在弃用日志里 grep**，比按消息正文搜靠谱。
* **触发时机是每次建连**（`openConnection` 的回调里），**不是配置时打一次**。所以在用的集群会持续看到它，不用等到重启或改配置。

**二，还有一个会让它不出现的条件**：第二个判断是 `false == REMOTE_CLUSTER_PROFILE.equals(...)`，而 `REMOTE_CLUSTER_PROFILE` 的值是 `"_remote_cluster"`（[`RemoteClusterPortSettings.java` 第 42 行](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/transport/RemoteClusterPortSettings.java#L42)）。**也就是说，走 remote cluster server port（`_remote_cluster` 这个 transport profile）的连接，即便用证书模式也不会打这条告警**——判断用的是 transport profile，不是"有没有配证书"。

**所以"配了证书模式就一定有告警"这句话要打个折**：告警的有无取决于连接走的 profile。

## 怎么判断自己在用哪种

文档里有一条明确的判定规则（[remote-clusters.md 第 50 行 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/reference/elasticsearch/configuration-reference/remote-clusters.md#L50)），说的是 `cluster.remote.<cluster_alias>.credentials` 这个设置：

> The presence (or not) of this setting determines which model a remote cluster uses. **If present, the remote cluster uses the API key based model. Otherwise, it uses the certificate based model.**

**判断标准就一条**：

* **配了 `credentials`** → API key 模式；
* **没配** → 证书模式。

所以排查很简单——看 keystore 里有没有这个设置：

```sh
/usr/share/elasticsearch/bin/elasticsearch-keystore list | grep -i "cluster.remote"
```

如果只看到 `cluster.remote.<alias>.seeds` 之类、没有 `credentials`，那就在用证书模式。

（说明：这个设置是 **keystore 里的安全设置**，不在 `elasticsearch.yml` 里，所以 grep 配置文件找不到。这一点和 [discovery-ec2 换 SDK v2](./es9-91-discovery-ec2-aws-sdk-v2.md) 里的 `discovery.ec2` 系统属性类似——**有些配置不在常规位置**。）

## 迁移要做什么

按官方的说法，迁移方向是"从证书到 API key"。具体步骤官方有专门文档（changelog 里链到了 `remote-clusters-migrate`），**具体步骤以官方文档为准**。

能确定的两点：

**一，要创建跨集群 API key。** ES 提供了专门的 API（`security.create_cross_cluster_api_key`，文档里有链接）。创建时指定权限范围——这就是"细粒度"的由来。

**二，把它配到 `cluster.remote.<alias>.credentials`。** 按文档的说明，这个值放在 **keystore** 里，并且**每个节点都要配**。

文档还提到一个便利之处（同一段说明）：

> If the setting is added, removed, or updated in the ES keystore and reloaded via the Nodes reload secure settings API, the cluster will automatically rebuild its connection to the remote.

**改完可以热加载**——通过 reload secure settings API 触发，集群会自动重建连接，不用重启节点。这对生产环境挺重要，省掉一次滚动重启。

## 为什么细粒度控制更合适

官方那句"细粒度访问控制"值得再展开，因为它是这次迁移**真正的价值所在**。

用证书模式配置远程集群时，典型的形态是：**信任了远端集群，它就能查它能查的东西**。权限的边界在远端集群侧——本地集群没法限制"对方只能看我这几个索引"。

API key 模式把这个边界**移到了本地**：创建 key 的时候就写清楚"这个 key 能读哪些索引"。远端拿着这个 key 过来，超出范围的请求会被拒绝。

这个差别在多团队协作或者合规要求下很重要：

* **多团队**：不同业务线的集群互相连接时，你不希望 A 团队能看 B 团队的全部数据；
* **合规**：数据访问范围需要可审计、可证明。key 上绑定的权限是**显式的**，比"配了证书所以能访问"更容易说明白。

**第二点在审计场景里价值最明显**——当被问到"这个远程集群能访问什么"时，证书模式要翻 TLS 配置和远端权限设置才能回答，API key 模式看 key 的定义就行。

## 迁移前要想清楚的一件事

要迁的话，先做一件事：**盘一遍现有的跨集群访问需求**。

因为 API key 要绑定权限，你得先知道每个远程集群**实际需要访问什么**。如果从没梳理过，直接迁很可能会：

* 权限给大了 → 等于没迁移，白做；
* 权限给小了 → 业务查询开始报错。

做法是**先从宽松起步，再逐步收紧**：创建时给一个比实际需要稍大的范围，观察一段时间（看有没有越界访问），再收到合适的范围。

这个办法慢，但**比"一步到位"安全**。权限收紧导致的故障排查起来很花时间——报错信息通常只说"没权限"，不会告诉你应该要什么权限。

## 迁移时的两个容易踩的点

**一是别只验正向，要验反向。** 迁移完成后，很多人只试"该查的能查到"，这是不够的。API key 的价值在于**限制**，所以要专门试一次**访问未授权的索引，确认被拒**。

只验正向不验反向，等于没验证权限是否真的生效——万一 key 上绑的权限比预想的宽，正向测试全通过，但边界根本没设住。

**二是权限要按用途分开。** 如果这个 key 同时用于 CCS（搜索）和 CCR（复制），要注意两者对权限的要求不完全一样。做法是**搜索和复制用两个 key**——用途不同、生命周期不同、审计需求也不同。

还有一点：**API key 可以设过期时间**。给跨集群用的 key 建议**明确设过期并纳入轮换流程**，别建完就忘——长期不轮换的凭据本身就是风险，而跨集群 key 通常权限范围较大，更不该一直放着。

## 如果暂时迁不了怎么办

现实里跨集群配置常牵扯多个团队，不是想迁就能立刻迁。这期间可以做几件事降低风险：

**一，把证书模式的权限影响面摸清楚。** 证书模型下远端用户的权限会带过来，所以要知道"远端有哪些人、他们有什么权限"。这份清单是评估风险的基础——如果远端有很宽的权限，说明当前的跨集群边界比想象中宽。

**二，在远端收紧权限。** 迁移之前，可以先在远端把不需要跨集群访问的用户权限收窄。这是证书模型下唯一能控制边界的手段，虽然粗，但总比什么都不做强。

**三，给跨集群连接单独建模。** 如果条件允许，让跨集群访问走专门的账号/角色，而不是让所有人的权限都无条件带过去。

**四，把迁移排进版本计划。** 官方已明确"未来主版本会移除"，所以不是"要不要做"的问题，是"什么时候做"。建议在下一个主版本升级之前完成。

**第二条最值得先做**：在证书模型下主动收紧远端权限，既降低当前风险，也让后续迁移时的"应授予什么权限"有参考——**你现在实际用到了哪些索引，就是迁移后 API key 该声明的范围**。

这个思路挺实用：迁移前先收紧，能同时解决两个问题（当前风险 + 迁移时的权限依据）。

## 值得排进计划，但不用紧急处理

这条是 **deprecation**，不是 breaking。实际影响目前只有一条：**弃用日志里多一条警告**。

功能照常可用。官方说"将在未来主版本移除"，但**没说是哪个版本**——可能是 10，也可能更远。

所以建议是：

* **不要**把它放进当前升级窗口（9.0 升级本身的 breaking 已经够多了）；
* **要**记进待办，在下一个主版本升级前处理掉；
* 如果你们本来就在规划安全改造（比如收紧跨集群权限），那可以**顺势一起做**——这次迁移正好能带来权限细化。

最后一条是最实际的切入点：**不要为了消除警告而迁移，要为了拿到细粒度控制而迁移**。前者是被动应付，后者有实际收益。

## 和别的"弃用"条目放一起看

9.x 的 deprecation 我写过几条，它们的共同模式值得总结：

| 条目 | 弃用什么 | 建议方向 |
|---|---|---|
| 本篇 | 远程集群证书模式 | 迁移到 API key |
| [lenient boolean 弃用](./es9-55-lenient-boolean-deprecated.md) | lenient booleans | 只用严格 `true`/`false` |
| [reporting_user 角色弃用](./es9-56-reporting-user-role-deprecated.md) | `reporting_user` 角色 | 换角色 |

三条的共同点是：**都给了明确的替代方案**。

这是 ES 弃用条目的一贯做法——**不会只说"这个要没了"，而会说"用这个代替"**。所以读 deprecation 时，重点不是"什么时候会移除"，而是**"我现在该往哪个方向改"**。

因为替代方案通常是更好的做法（这次的细粒度控制就是），**早改早受益**，不用等到非改不可。

## 检查清单

* 证书模式在 9.0 被标为 deprecation（changelog 第 1785–1796 行，**PR 120806**），当前影响只是**弃用日志里一条警告**，功能照常。
* **判断用哪种模式只按一条**：keystore 里有没有 `cluster.remote.<alias>.credentials`。有 → API key 模式；没有 → 证书模式。它是安全设置，不在 `elasticsearch.yml` 里。
* 弃用告警在源码里的位置是 `RemoteConnectionManager.maybeLogDeprecationWarning`（第 125–138 行），条件是 `getClusterCredentials() == null` **且** profile 不是 `_remote_cluster`。
* 告警 key 是 `remote_cluster_certificate_access-<别名>`，分类 `SECURITY`，**每次建连都打**——按这个 key grep 弃用日志最直接。
* **走 remote cluster server port 的连接不打这条告警**，所以"配了证书却没有告警"不代表不在证书模式。
* 迁移前先盘一遍实际访问需求：先给稍宽的范围、观察越界情况、再收紧；权限收紧导致的报错通常只说"没权限"，排查很花时间。
* 验证要**正向 + 反向都做**：除了"该查的能查到"，要专门试一次访问未授权索引确认被拒。
* 搜索（CCS）与复制（CCR）用两个 key；给 key 设过期并纳入轮换。

## 写在最后

这条 deprecation 当前影响很小——只是一条弃用日志。

写它的主要理由是**它的替代方案有实际价值**：API key 模式能做细粒度访问控制，而证书模式只能证明身份。如果你们的跨集群连接比较随意（一个远程集群能看全部索引），这次迁移正好是个收紧的机会。

**一，判断自己在用哪种模式，看 keystore 里有没有 `cluster.remote.<alias>.credentials`。** 有就是 API key 模式，没有就是证书模式。

**二，当前只是弃用日志警告，不用紧急处理。** 但记进待办，下个主版本前处理掉。

**三，迁移的收益不只是消除警告。** 细粒度访问控制是实打实的安全改进——如果本来就该收紧跨集群权限，这就是最好的时机。

## 参考

- [changelog 9.0.0：Deprecate certificate based remote cluster security model（第 1786–1796 行）@ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/release-notes/changelog-bundles/9.0.0.yml#L1786-L1796)
- [`remote-clusters.md`：`cluster.remote.<alias>.credentials` 决定使用哪种安全模型（第 50 行）@ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/reference/elasticsearch/configuration-reference/remote-clusters.md#L50)
- [`remote-clusters.md`：跨集群请求签名相关设置 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/reference/elasticsearch/configuration-reference/remote-clusters.md)
- [PR 120806](https://github.com/elastic/elasticsearch/pull/120806)
* [`RemoteConnectionManager.java` 第 110–138 行 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/transport/RemoteConnectionManager.java#L110-L138)
* [`RemoteClusterPortSettings.java` 第 42 行 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/server/src/main/java/org/elasticsearch/transport/RemoteClusterPortSettings.java#L42)

> 本文对照 Elasticsearch `v9.4.2` 标签的 changelog、官方文档与服务端源码核对，引文逐字取自原文或源码。**迁移的具体操作步骤本文未展开**，需参考官方的远程集群迁移文档；**示例命令未在集群上执行**；**"证书模式已被弃用"** 的依据除 changelog 与文档外，源码里也找到了告警实现（`RemoteConnectionManager` 第 125–138 行）；**"走 `_remote_cluster` profile 的连接不打这条告警"** 由该方法的第二个判断条件推出，**未实测**；**"权限收紧导致的报错只说没权限"** 是按一般现象的描述，未见官方说明；本文撰写时未启动集群、未运行测试。


9.0 起，用证书模式配置远程集群会在弃用日志里产生警告。官方说它"将在未来主版本移除"，推荐迁移到 API key 模式——理由是后者能做细粒度访问控制。如果你在用跨集群，这条值得排进计划。

ES 远程集群的证书模式被弃用，换成 API key 还能收紧访问范围

9.0 起，用证书模式配置远程集群会在弃用日志里产生警告。

官方产研

云计算

后端

大数据

Elasticsearch 9.0起，基于证书的远程集群安全模型已弃用，未来主版本将移除。官方推荐迁移至API key认证，支持细粒度访问控制。当前仅产生弃用日志警告，功能不受影响。判断依据：keystore中是否存在cluster.remote.<alias>.credentials。建议规划迁移，利用API key绑定权限范围，实现更精细的安全管控。

Elasticsearch 

代码解释

TLS证书

Java

2026上云采购 | AI焕新·智启新局

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Elasticsearch 9.0起，基于证书的远程集群安全模型已弃用，未来主版本将移除。官方推荐迁移至API key认证，支持细粒度访问控制。当前仅产生弃用日志警告，功能不受影响。判断依据：keystore中是否存在cluster.remote.<alias>.credentials。建议规划迁移，利用API key...

ES 远程集群的证书模式被弃用，换成 API key 还能收紧访问范围-腾讯云开发者社区-腾讯云

ES 远程集群的证书模式被弃用，换成 API key 还能收紧访问范围

ES 远程集群的证书模式被弃用，换成 API key 还能收紧访问范围

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐