Python 同时适配 Elasticsearch 与 Easysearch 实战复盘

所以若希望同一套代码同时支持 ES 和 Easysearch，应锁定到 7.13.1。

3.2 NumPy 2.0 兼容

NumPy 2.0 移除了 np.float_ 和 np.int_，而 elasticsearch 7.13 仍在使用，需要在导入 elasticsearch 之前做兼容：

import numpy as _np
if not hasattr(_np, "float_"):
    _np.float_ = _np.float64
if not hasattr(_np, "int_"):
    _np.int_ = _np.int64
from elasticsearch import Elasticsearch

这样在 NumPy 2.0 下也能正常使用。

3.3 HTTPS 自签名证书

使用 HTTPS 且证书自签名时，常见错误：

SSLError: certificate verify failed: self-signed certificate in certificate chain

处理方式：在创建客户端时关闭证书校验（仅适合内网 / 自建环境）：

kwargs = {
    "hosts": [{"host": host, "port": port, "scheme": scheme}],
    "timeout": 30,
    "max_retries": 3,
    "retry_on_timeout": True,
}
if scheme == "https" and not verify_certs:
    kwargs["verify_certs"] = False
# 如 7.x 的默认 Transport 仍报错，可改用 RequestsHttpConnection
from elasticsearch import RequestsHttpConnection
client = Elasticsearch(
    hosts=hosts,
    connection_class=RequestsHttpConnection,
    http_auth=http_auth,
    use_ssl=True,
    verify_certs=False,
    timeout=30,
)

并配合 urllib3.disable_warnings() 抑制 SSL 告警。

3.4 依赖约束

elasticsearch==7.13.1
numpy<2  # 若使用 NumPy 2.0，则需上面的补丁
requests>=2.26.0

四、我们走过的几种方案

方案 A：双客户端（ES 8.x + opensearch-py）

• Elasticsearch：使用 elasticsearch>=8
• Easysearch：使用 opensearch-py

问题：两个包、两套 API、分支多，维护成本高，我也明确不希望引入 opensearch。

方案 B：单客户端 8.x + 禁用产品校验

尝试在 8.x 中通过自定义 Transport 或 monkey-patch 禁用产品校验。

问题：依赖非官方实现，升级风险大，不够稳妥。

方案 C：单客户端 7.13.1（最终采用）

• 固定使用 elasticsearch==7.13.1
• 同时连接 Elasticsearch 8.x / 9.x 和 Easysearch
• 无产品校验，API 稳定，依赖简单

结论：方案 C 最符合当前需求。

五、示例：统一的客户端创建逻辑

# 1. NumPy 兼容（若使用 NumPy 2.0）
import numpy as _np
if not hasattr(_np, "float_"):
    _np.float_ = _np.float64
if not hasattr(_np, "int_"):
    _np.int_ = _np.int64

from elasticsearch import Elasticsearch
from elasticsearch.helpers import bulk as helpers_bulk

def create_es_client(host, port, scheme="http", http_auth=None, verify_certs=True):
    hosts = [{"host": host, "port": port, "scheme": scheme}]
    kwargs = {
        "hosts": hosts,
        "timeout": 30,
        "max_retries": 3,
        "retry_on_timeout": True,
    }
    if http_auth:
        kwargs["http_auth"] = http_auth
    if scheme == "https" and not verify_certs:
        kwargs["verify_certs"] = False
    try:
        client = Elasticsearch(**kwargs)
    except TypeError:
        # 某些 7.x 版本参数不同
        kwargs.pop("verify_certs", None)
        from elasticsearch import RequestsHttpConnection
        import urllib3
        urllib3.disable_warnings()
        client = Elasticsearch(
            hosts=hosts,
            connection_class=RequestsHttpConnection,
            http_auth=http_auth,
            use_ssl=True,
            verify_certs=False,
            timeout=30,
        )
    if not client.ping():
        client.info()  # 兜底
    return client

前端/配置中只需区分 product: "elasticsearch" 或 "easysearch"，后端都用同一套 elasticsearch 7.13.1 客户端即可。

六、总结

1. 单客户端： elasticsearch==7.13.1 可同时支持 Elasticsearch 8.x/9.x 和 Easysearch。
2. 产品校验： 7.13.1 无校验，7.14+ 会校验，这是选 7.13.1 的核心原因。
3. NumPy： 在 NumPy 2.0 下需补回 np.float_ / np.int_。
4. HTTPS： 自签名证书时设置 verify_certs=False，必要时用 RequestsHttpConnection。
5. 不引入 opensearch-py： 减少依赖和复杂度，保持实现简单。

如果后续需要同时使用 8.x 的新特性并支持 Easysearch，再考虑引入 opensearch-py 或按产品类型切换不同客户端会比较合适；目前以兼容性和维护成本为主时，7.13.1 单客户端方案是更稳妥的选择。