必须用elasticsearch/elasticsearch v8.x官方客户端，因其深度适配Workerman常驻进程：支持连接池复用、429/503指数退避重试、协程钩子、SSL校验及结构化响应解析；手写cURL或Guzzle易导致卡死、漏重试、静默失败。
必须用 elasticsearch/elasticsearch v8.x 官方客户端，手写 cURL 或 file_get_contents 在 Workerman 常驻进程下会卡死、漏重试、连不上就崩——这不是 Elasticsearch 问题，是客户端选错了。
为什么不能用裸 cURL 或 GuzzleHttp 手动封装？
Workerman（以及 Webman）是常驻内存的长生命周期框架，而 Elasticsearch 的健康探活、连接复用、429 自动退避、503 重试、连接池管理这些能力，v8 客户端已通过 GuzzleHttp\Client + Swoole 协程钩子（co::set(['hook_flags' => SWOOLE_HOOK_ALL])）深度适配。手写请求会丢失：
-
setRetries(3)对 429/503 的指数退避重试 - 连接池复用（避免
Too many open files） - SSL 证书校验失败时的明确错误（
setSSLVerification(false)在 Swoole 下会静默断连） - v8 响应结构变更（如
hits.hits→hits.hits不变，但_shards和错误格式已重构，手动解析易错）
初始化 client 必须显式配置 timeout 和 retry
默认 30 秒超时在高延迟网络或慢查询下，会直接拖垮整个 Worker 进程。v8 客户端不设超时就等于没设防。
正确初始化示例：
$client = \Elasticsearch\ClientBuilder::create()
->setHosts(['http://elasticsearch:9200']) // Docker 内别写 localhost
->setBasicAuthentication('elastic', 'changeme')
->setSSLVerification('/etc/elasticsearch/certs/http_ca.crt') // 生产必须传 PEM
->setConnectionPool(\Elasticsearch\ConnectionPool\StaticConnectionPool::class, [
'connectionPoolParams' => ['maxConnections' => 15]
])
->setRetries(3)
->setConnectionParams([
'timeout' => 4.0,
'connect_timeout' => 2.0
])
->build();
- 若运行在 Docker，
hosts必须填容器名（如http://elasticsearch:9200），不是localhost -
setRetries(3)能覆盖 429（限流）、503（节点忙）、部分网络抖动 -
timeout控制整个请求耗时上限；connect_timeout单独控建连阶段，防止 DNS 卡住
实时推送场景下必须避开 index refresh 延迟
Elasticsearch 默认 1 秒 refresh，新写入文档不能立刻搜到。实时搜索推送（比如用户发消息后立即可被搜到）必须强制刷新：
- 写入单条文档时加
'refresh' => 'true'参数：$client->index(['index' => 'messages', 'id' => $id, 'body' => $data, 'refresh' => 'true']) - 批量写入用
bulk时，每条 action 都可带refresh，但更推荐 bulk 后单独调一次$client->indices()->refresh(['index' => 'messages']) - 注意：频繁
refresh = true会增加 segment 生成压力，QPS > 500 时建议改用refresh_interval调小（如500ms），而非每次强刷
最容易被忽略的是连接生命周期和 SSL 校验——Workerman 不重启就不会重连，一旦证书过期或 ES 地址变更，client 实例会一直拿着旧连接直到超时或报错；而 setSSLVerification(false) 在协程环境下不报错、不断开、也不返回结果，只默默失败。务必把 CA 证书路径写对，且定期检查有效期。
