ES 7.x 必用 olivere/elastic/v7，8.x 必用 elastic/go-elasticsearch/v8；二者API、认证、错误结构完全不兼容，混用导致401或406错误。
连不上 Elasticsearch，90% 不是网络问题，而是客户端版本错配、Addresses 格式错误、或 TLS/认证配置漏在 Transport 层——Username/Password 字段只加 Header，不解决证书校验；v7 和 v8 客户端 API 完全不兼容，混用直接 panic 或 401。
怎么选对客户端：olivere/elastic/v7 还是 elastic/go-elasticsearch/v8？
v7 和 v8 客户端不能共存，API 行为、错误结构、默认请求头、认证要求全部不同：
- ES 是 7.x（如 7.17.12）→ 必须用
github.com/olivere/elastic/v7；用go-elasticsearch/v8会报406 Not Acceptable（Accept 头不匹配） - ES 是 8.x（包括阿里云/腾讯云新版托管实例）→ 必须用
github.com/elastic/go-elasticsearch/v8；Username和Password字段不可省，哪怕你关了xpack.security.enabled，ES 8 默认启用内置安全，elastic用户始终存在 -
go-elasticsearch/v7是过渡包，不支持 ES 8 的 runtime_mappings、_source压缩等新特性，新项目别用
Addresses 写错一个字符就连接失败
地址看着简单，但错一点就会触发重定向失败、协议降级或 DNS 解析卡死：
- 错误写法：
"http://localhost:9200/"→ 末尾斜杠可能让某些版本重定向后失败；应写成"http://localhost:9200" - 错误写法：
"localhost:9200"→ 缺协议头，客户端行为不一致；必须显式声明"http://"或"https://" - Docker 场景下，
localhost在容器内指向自己，不是宿主机；要用"host.docker.internal"（Mac/Win）或宿主机真实 IP - ES 启动时没设
http.host: "0.0.0.0"，即使地址写对，也会因绑定127.0.0.1导致 Go 客户端连不上
HTTPS + Basic Auth 下 x509 错误怎么解？
Username/Password 只影响 HTTP Header，不触达 TLS 层；x509 报错必须从 http.Transport 入手：
- 用自签名证书或私有 CA：通过
TLSClientConfig.RootCAs加载信任根证书 - 仅测试跳过验证：设
InsecureSkipVerify: true，但生产环境禁用 - v8 客户端默认 TLS 检查更严格，v7 可能“侥幸”通过，别依赖这种行为
- v8 初始化默认发 HEAD / 健康检查，若 TLS 配错，
NewClient()会直接 panic；建议初始化时加Healthcheck: false，之后用Ping()主动探测
Index 创建和文档写入最容易踩的坑
v7 和 v8 对 mapping 结构、body 传参方式、ID 生成逻辑要求差异极大：
- v8 已彻底移除
_type，mapping 中不能再出现"_doc"；正确结构是"mappings": {"properties": {...}}，不是"mappings": {"_doc": {"properties": {...}}} -
indices.Create().Body()（v8）必须传io.Reader，别直接传字符串；要用bytes.NewReader(jsonBytes)或strings.NewReader(stringJson) - 文档 ID 推荐用业务主键（如
order_id），别依赖 ES 自动生成；Index().Id("")返回的 base64 随机串不利于调试和幂等更新 - Bulk 写入必须调
Do(ctx)才真正发出请求；不调等于白写；执行后还要检查response.Errors == true，遍历response.Items看每个子请求状态码（409/429/503可重试，400要修数据）
最常被忽略的是：v8 客户端强制要求 Username 和 Password 字段非空，哪怕你连的是本地单节点且未开启安全模块；以及 bulk 请求必须按字节切分（比如 10MB），而不是硬写“每 1000 条 flush 一次”——嵌套文档体积波动极大，按条数切极易触发 circuit_breaker。
