通過應用程式串連叢集 - Elasticsearch

本文介紹如何使用Java、Python、Go語言串連Elasticsearch叢集（ES）。

準備工作

擷取叢集串連地址

您可以通過VPC私網或公網地址串連到ES叢集。

VPC私網串連地址：通過VPC私網地址訪問ES叢集，延遲低，穩定性高。該地址在叢集建立成功後預設開啟。
公網串連地址：通過公網訪問ES叢集，需手動開啟。

如何開啟公網訪問：

登入ES控制台，進入執行個體基本資料頁面。
單擊左側導覽列 配置與管理>安全配置，開啟公網訪問。待叢集狀態由生效中變更為生效時，表示公網訪問已成功開啟。

公網訪問開啟後，公網地址格式為 es-cn-<執行個體ID>.public.elasticsearch.aliyuncs.com，公網訪問白名單預設為空白，需手動設定。

重要
公網地址會降低ES叢集的安全性，如果使用公網地址，請務必配置IP白名單，並在使用完畢後及時關閉公網訪問。

設定IP白名單

為保障叢集安全，您需要將待訪問裝置的IP地址加入ES叢集的VPC私網或者公網白名單，該IP地址所屬的裝置才能訪問ES叢集。

擷取待訪問裝置IP。

您可以參照以下情境，擷取待訪問裝置的IP地址。

情境	需擷取的IP地址	擷取方式
在本地裝置中串連ES叢集	本地裝置公網IP。如果本地裝置位於區域網路（如家庭或公司網路）內，需將該區域網路的公網出口IP地址添加到ES叢集的公網白名單中。	通過`curl ipinfo.io/ip`查詢本地裝置公網IP。
在不同VPC的ECS執行個體中串連ES叢集	ECS執行個體的公網IP	登入ECS控制台，在執行個體列表查看。
在相同VPC的ECS執行個體中串連ES叢集	ECS執行個體的私網IP	登入ECS控制台，在執行個體列表查看。

將擷取到的IP地址添加到白名單分組中。

登入ES控制台，進入執行個體基本資料，單擊左側導覽列 配置與管理>安全配置，單擊修改在彈窗中設定VPC私網或者公網訪問白名單。

單擊default分組右側的配置，在彈出的對話方塊中添加VPC私網或者公網白名單。單個叢集最多可配置300個IP或者IP網段，多個IP或者IP網段之間用英文逗號隔開，且逗號前後不能有空格。

也可單擊新增IP白名单分组，自訂分組名稱。
白名單分組僅用於IP地址管理，不影響存取權限。所有分組內的IP地址許可權相同。

配置類別

格式和樣本值

重要注意事項

IPv4地址格式

單個IP：192.168.0.1
網段：192.168.0.0/24

禁止訪問：127.0.0.1
允許所有訪問：0.0.0.0/0

重要
存在高危風險，強烈建議不要配置 0.0.0.0/0。

部分叢集版本（如7.16/8.5）和地區不支援 0.0.0.0/0，請以控制台介面或者報錯提示為準。

IPv6地址格式

（僅v2部署架構且所屬地區為杭州的叢集支援）

單個IP：2401:XXXX:1000:24::5
網段：2401:XXXX:1000::/48

禁止所有訪問：::1
允許所有訪問::/0

重要
存在高危風險，強烈建議不要配置 ::/0。

部分叢集版本不支援 ::/0，請以控制台介面或者配置提示資訊為準。

配置完成後，單擊確認。

協議與認證說明

為確保相容性，建議用戶端使用的 Java、Python 或 Go 語言版本與ES叢集底層運行時的版本保持一致。
公網HTTPS：使用權威CA簽發的認證，用戶端無需特殊配置，直接使用 https:// 協議串連即可。
私網HTTPS：使用自我簽署憑證加密傳輸，用戶端需配置跳過認證校正，詳見各語言樣本中的私網HTTPS配置。

串連叢集

Java

安裝Java JDK，JDK版本為1.8及以上。

配置pom依賴。

重要

請將version設定為正確的ES版本號碼，只有當version設定正確時才能拉取相關依賴，本樣本ES版本為8.17.0。

<dependency>
    <groupId>co.elastic.clients</groupId>
    <artifactId>elasticsearch-java</artifactId>
    <version>8.17.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.12.3</version>
</dependency>

配置YML參數，開啟自動建立索引：action.auto_create_index: true。以下樣本將串連ES叢集並建立名為hr_test的索引。

基礎串連樣本

以下樣本適用於公網HTTPS或私網HTTP情境：

package org.example;
import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch.cat.IndicesResponse;
import co.elastic.clients.elasticsearch.indices.*;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.ElasticsearchTransport;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.elasticsearch.client.*;
import java.io.IOException;
public class RestClientTest {
    public static void main(String[] args) {
        final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{UserName}", "{YourPassword}"));
        // 公網HTTPS使用 "https"，私網HTTP使用 "http"
        RestClient restClient = RestClient.builder(new HttpHost("{YourEsHost}", 9200, "https"))
                .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
                    @Override
                    public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
                        return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
                    }
                }).build();

        ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
        ElasticsearchClient elasticsearchClient = new ElasticsearchClient(transport);
        try {
            CreateIndexResponse indexRequest = elasticsearchClient.indices().create(createIndexBuilder -> createIndexBuilder
                    .index("hr_test")
                    .aliases("foo", aliasBuilder -> aliasBuilder.isWriteIndex(true))
            );
            System.out.println("Index document successfully! " + indexRequest.acknowledged());
            transport.close();
            restClient.close();
        } catch (IOException ioException) {
            // 異常處理
        }
    }
}

私網HTTPS串連樣本

私網HTTPS需額外配置跳過認證校正：

package org.example;
import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.ElasticsearchTransport;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.conn.ssl.NoopHostnameVerifier;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.apache.http.ssl.SSLContexts;
import org.elasticsearch.client.*;
import javax.net.ssl.SSLContext;

public class RestClientTestPrivateHttps {
    public static void main(String[] args) throws Exception {
        final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{UserName}", "{YourPassword}"));
        // 建立信任所有認證的 SSLContext
        SSLContext sslContext = SSLContexts.custom()
          .loadTrustMaterial(null, (chain, authType) -> true)  // 信任所有認證
          .build();
        RestClient restClient = RestClient.builder(new HttpHost("{YourEsHost}", 9200, "https"))
                .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
                    @Override
                    public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
                        return httpClientBuilder
                            .setDefaultCredentialsProvider(credentialsProvider)
                            .setSSLContext(sslContext)                          // 設定 SSLContext
                            .setSSLHostnameVerifier(NoopHostnameVerifier.INSTANCE);  // 跳過主機名稱驗證
                    }
                }).build();

        ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
        ElasticsearchClient elasticsearchClient = new ElasticsearchClient(transport);
        
        // 執行操作...
        System.out.println(elasticsearchClient.info());
        
        transport.close();
        restClient.close();
    }
}

Python

以下代碼以ES 8.17.0版本為例，請根據實際ES版本替換版本號碼。

基礎串連樣本

以下樣本適用於公網HTTPS或私網HTTP情境：

pip install elasticsearch==8.17.0from elasticsearch import Elasticsearch
es = Elasticsearch(
    hosts=['https://<YourEsHost>:9200'],  # 公網HTTPS使用https://，私網HTTP使用http://
    basic_auth=('<UserName>', '<YourPassword>'),
)
print(es.info())

私網HTTPS串連樣本

from elasticsearch import Elasticsearch
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)  # 關閉SSL警告（可選）

es = Elasticsearch(
    hosts=['https://<YourEsHost>:9200'],
    basic_auth=('<UserName>', '<YourPassword>'),
    verify_certs=False,           # 跳過認證校正
    ssl_show_warn=False,          # 關閉SSL警告
)
print(es.info())

Go

以下以ES 8.x版本為例介紹如何通過Go串連ES，更多Go API Client的使用特性，請參見Elasticsearch Go Client。

基礎串連樣本

以下樣本適用於公網HTTPS或私網HTTP情境：

go get github.com/elastic/go-elasticsearch/v8
package main

import (
    "github.com/elastic/go-elasticsearch/v8""log"
)

func main() {
    cfg := elasticsearch.Config{
        Addresses: []string{"https://<YourEsHost>:9200"},  // 公網HTTPS使用https://，私網HTTP使用http://
        Username:  "<UserName>",
        Password:  "<YourPassword>",
    }
    es, _ := elasticsearch.NewClient(cfg)
    res, _ := es.Info()
    defer res.Body.Close()
    log.Println(res)
}

私網HTTPS串連樣本

package main

import (
    "crypto/tls""net/http""github.com/elastic/go-elasticsearch/v8""log"
)

func main() {
    cfg := elasticsearch.Config{
        Addresses: []string{"https://<YourEsHost>:9200"},
        Username:  "<UserName>",
        Password:  "<YourPassword>",
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},  // 跳過認證校正
        },
    }
    es, _ := elasticsearch.NewClient(cfg)
    res, _ := es.Info()
    defer res.Body.Close()
    log.Println(res)
}

參數說明

參數	說明
UserName	預設訪問使用者名稱為elastic，該使用者具有叢集最高許可權（可理解為管理員賬戶）。出於安全考慮，不建議在生產環境中直接使用此預設管理員賬戶，您可以通過Elasticsearch X-Pack的RBAC（Role-based Access Control）機制，自訂角色並分配許可權，然後將角色指派給使用者，實現許可權精細化管控，具體操作請參見通過Elasticsearch X-Pack角色管理實現使用者權限管控。
YourPassword	UserName對應的密碼。
HTTPS	訪問協議，http協議預設開啟。為了保障叢集安全性，建議使用HTTPS協議，需手動開啟。登入ES控制台進入執行個體基本資料，單擊左側導覽列配置與管理>安全配置，開啟HTTPS協議。重要啟用HTTPS協議前，請務必更新應用程式代碼以支援HTTPS串連方式。否則，現有使用HTTP協議的代碼將無法建立安全連線，導致串連失敗。私網HTTPS使用自我簽署憑證，用戶端需配置跳過認證校正，詳見上方各語言串連樣本。
YourEsHost	準備工作中已擷取的叢集串連地址： VPC私網串連地址公網串連地址
9200	叢集的訪問連接埠，VPC私網和公網預設連接埠號碼均為9200。

FAQ

叢集狀態健康但用戶端無法串連時，按以下方法排查。

路由表診斷

同一VPC下ES串連不通時，檢查路由表。Docker安裝會修改路由資訊，使ES網段路由缺失或指向錯誤網關。在ECS上執行以下命令查看路由表：

route -n

檢查輸出中到達ES網段的路由是否存在。如果路由缺失或網關錯誤，需修複路由配置後重試串連。同時檢查企業防火牆是否攔截ES網段流量。

網域名稱與連接埠校正

使用curl命令驗證網域名稱與連接埠拼接是否正確：

curl -u {UserName}:{YourPassword} https://{YourEsHost}:9200

返回"Could not resolve host"表示網域名稱拼字錯誤。常見錯誤包括網域名稱缺少字母、未加連接埠號碼。

用戶端逾時參數配置

Java用戶端預設不設定連線逾時和Socket逾時時間。網路不穩定時串連會長時間阻塞。通過setRequestConfigCallback設定逾時參數：

RestClient restClient = RestClient.builder(new HttpHost("{YourEsHost}", 9200, "https"))
    .setRequestConfigCallback(builder -> builder
        .setConnectTimeout(10000)
        .setSocketTimeout(30000))
    .setHttpClientConfigCallback(httpClientBuilder ->
        httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider))
    .build();

ConnectTimeout控制建立串連的逾時時間，設為10000毫秒（10秒）。SocketTimeout控制資料讀取的逾時時間，設為30000毫秒（30秒）。根據網路環境調整這兩個值。

如何測試ECS串連Elasticsearch執行個體的網路延遲及公網訪問說明

外部ECS可以通過ES執行個體的公網串連地址訪問Elasticsearch，公網訪問是受支援的串連方式，使用前需確認執行個體已開啟公網訪問，且該ECS的公網IP已加入公網訪問白名單（叢集串連地址的擷取與IP白名單配置見本文「準備工作」）。公網鏈路經過的網路跳數更多、路徑更長，相比同一VPC內的私網串連存在明顯更高的網路延遲，也更容易受鏈路抖動影響，因此生產環境優先使用VPC私網串連地址，公網串連僅用於測試、臨時排查或確實無法打通私網的情境。在ECS上可以通過以下兩種方法測量到ES執行個體的網路延遲：

ping：驗證基礎連通性並觀察往返時延（RTT）。在ECS上執行以下命令，將{YourEsHost}替換為ES執行個體的串連地址：
```
ping {YourEsHost}
```
重點關注平均RTT與丟包率：RTT明顯偏高或存在丟包，說明ECS到ES之間的鏈路品質較差。部分網路環境或安全性原則會禁用ICMP，此時ping不通並不代表ES服務不可用，應改用「網域名稱與連接埠校正」中的curl命令確認連接埠連通性。
MTR：逐跳追蹤鏈路，定位網路瓶頸。MTR是通用的鏈路診斷工具，阿里雲ECS鏡像不保證預裝，需先在ECS上自行安裝，安裝完成後執行以下命令：
```
mtr -r -c 100 {YourEsHost}
```
逐跳查看每一跳的丟包率與延遲：若從某一跳開始丟包率或延遲持續升高，則瓶頸位於該跳及其之後的鏈路，據此可以判斷問題出在ECS出口、中間公網鏈路還是ES接入側。

如果測得的延遲偏高且業務對時延敏感，改用同地區、同一VPC的私網串連地址；如需進一步收斂網路不穩定帶來的請求阻塞，可參考「用戶端逾時參數配置」調整用戶端的連線逾時與讀取逾時。

頻繁出現No alive nodes found報錯且升級配置無效的排查方法

用戶端反覆拋出No alive nodes found報錯時，通常並非叢集資源不足，而是用戶端在其維護的節點列表中找不到任何可用節點，多由用戶端到叢集之間的網路連接不穩定、請求逾時或路由異常導致，因此僅升級叢集配置往往無法解決問題，應優先從網路連接層面排查。按以下三步定位：

確認用戶端到ES的網路拓撲路徑。先明確用戶端使用的是VPC私網串連地址還是公網串連地址，再檢查是否存在跨地區訪問、跨VPC訪問或公網長鏈路等情境，這些情境更容易出現鏈路抖動，導致節點探測失敗。若當前走公網或跨地區串連，可參考本文「如何測試ECS串連Elasticsearch執行個體的網路延遲及公網訪問說明」測量鏈路品質，條件允許時優先改用同地區、同一VPC的私網串連地址。
檢查用戶端日誌上下文。不要只看No alive nodes found這一行，向上查看與之伴隨出現的具體錯誤，確認是否存在連線逾時（connect timeout）、讀取逾時（socket timeout）、SSL/TLS握手失敗或認證校正失敗等資訊。伴隨錯誤決定後續動作方向：如果是逾時類錯誤，進入第3步的逾時參數調整；如果是SSL/TLS或認證類錯誤，參考本文「協議與認證說明」以及各語言串連樣本中的私網HTTPS配置，修正協議與認證配置。
結合本文已有章節做綜合排查。參考「路由表診斷」檢查ECS到ES網段的路由是否缺失或網關錯誤（例如Docker安裝修改了路由），以及企業防火牆是否攔截ES網段流量；參考「用戶端逾時參數配置」為用戶端顯式設定連線逾時與Socket逾時，避免網路不穩定時請求長時間阻塞並被判定為節點不可用。

若以上網路層面的排查均無異常，再結合叢集監控確認是否確實存在資源瓶頸，避免直接以升級配置作為首選手段。