alibabacloud-elasticsearch-instance-diagnose

Alibaba Cloud Elasticsearch 实例诊断

从 Alibaba Cloud OpenAPI（控制平面） 和 Elasticsearch REST API（数据平面） 收集信号，结合 references/ 下的 SOP 知识库，生成根因分析、证据链、按优先级排序的修复指导；如果有多个维度触发，则生成按时间新近程度排序的事件时间线（时间窗口内的严重程度与时间；参见 §5 第 4 步中的时间线与新近程度（必须））。

架构：Alibaba Cloud Elasticsearch OpenAPI + Alibaba CloudMonitor（CMS）+ Elasticsearch REST API + 诊断 SOP

闭环要求：如果适用 MUST 且已设置 ES_*，则在最终报告前完成经过身份验证的 ES API 证据收集（参见 §5 中的可行性顺序）。

---

1. 前提条件

1.1 Aliyun CLI

预检查：必须使用 Aliyun CLI >= 3.3.1（用于 RAM 权限检查和 OpenAPI CLI 回退方案） 运行 aliyun version，确认版本 >= 3.3.1。如果尚未安装 CLI 或版本过旧，请参阅 references/cli-installation-guide.md。 安装后，运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件（不要在此命令行中传入明文 AccessKey 对；参见 §1.2）。

1.2 Alibaba Cloud 账户身份验证与安全（必须）

安全规则（强制）：

• 绝不要读取、回显或打印 AccessKey ID 或 AccessKey Secret 值。
• 绝不要提示或要求用户在对话中粘贴明文 AccessKey。
• 绝不要在脚本、CLI 参数或 curl URL 中嵌入 AccessKey。
• 绝不要使用 aliyun configure set（或类似命令）在命令行中传入字面值 AccessKey ID/Secret。
• 绝不要接受用户粘贴到聊天中的 AccessKey，即使是用户主动提供的也不行。
• 只能使用已配置的 CLI 配置文件（aliyun configure），或使用用户在本地 shell 中设置的环境变量，例如 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET（Agent 不得在会话中回显这些值）。

⚠️ 如果用户在聊天中提供 AccessKey（例如“我的 AK 是 xxx”）

1. 立即停止：不要运行任何需要凭据的 Alibaba Cloud 命令。
2. 礼貌拒绝，并且只提供获准的配置方式名称（不要复述用户可能泄露的任何秘密）：
   • 推荐：在本地终端运行 aliyun configure，并在提示时输入凭据；凭据会存储在本地配置文件中。
   • 或者：在本地 shell 中设置 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET（用户只能在终端中输入值，不要在聊天中输入）。
3. 只有在凭据正确配置后，才能继续诊断请求。

在不暴露秘密的情况下验证凭据：

aliyun configure list
aliyun --profile <profile_name> sts get-caller-identity

凭据策略：

1. 优先使用 aliyun configure 配置文件（默认配置文件或 --profile）。
2. 如果没有有效身份（configure list / get-caller-identity 失败），则停止并指导用户在本地配置；不要猜测或伪造凭据。
3. 绝不要通过对话传递明文 AccessKey。

1.3 Elasticsearch 直连凭据边界

• 绝不要要求用户在聊天中粘贴 ES_PASSWORD；绝不要回显、打印或记录密码；绝不要将聊天中的密码复制到命令、钩子或仓库文件中。
• 如果变量已由用户在本地 shell 中预先导出，则允许通过 curl -u "$ES_USERNAME:$ES_PASSWORD"（或等效方式）进行 shell 展开；绝不要在聊天中、提交到仓库的脚本中或命令输出中写入字面形式的秘密。
• 如果用户试图在聊天中发送密码，也要停止，并要求他们仅在本地通过 export 设置 ES_PASSWORD（参见 §2.2）。

---

2. 环境设置

2.1 控制平面 OpenAPI（通过 Aliyun CLI）

此技能的所有控制平面和 CMS 数据采集均使用 Aliyun CLI。

[MUST] elasticsearch / cms — 仅使用插件模式 shell（避免使用旧版 CLI）
每当 Agent 输出可执行的 aliyun 命令行（聊天、可复现性导出或复制粘贴步骤）时，都应使用插件子命令（小写加连字符）和 kebab-case 标志——与 scripts/openapi_cli_collect.py 和 references/verification-method.md 中的格式一致。

• 不要使用旧版 POP 风格调用：在同一条 aliyun 命令行中，紧跟在 elasticsearch 或 cms 后的帕斯卡命名法动词（旧的“操作名称 = 子命令”风格），或在新命令中使用 --InstanceId、--Namespace、--StartTime 这类 CamelCase 标志。仅使用插件动词（describe-instance、describe-metric-list，等等）。
• 命名区分：DescribeInstance、ListSearchLog、DescribeMetricList 等是 OpenAPI 操作名称（帕斯卡命名法——用于文档、RAM、控制台）。在 shell 中，aliyun elasticsearch 或 aliyun cms 后面的词必须是 CLI 插件名称（describe-instance、list-search-log、describe-metric-list，等等）。
• 优先使用 python3 scripts/check_es_instance_health.py 执行标准控制平面 + CMS 检查，以使子进程调用与此仓库保持一致。
• CLI 参考：Elasticsearch CLI 中心、云监控 CLI 中心。

AI-Mode 和插件基线（必需）——对每个运行 aliyun OpenAPI/CMS 命令的诊断会话，都使用以下包装：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-diagnose"
aliyun plugin update
# … diagnosis: aliyun / python3 scripts/check_es_instance_health.py …
aliyun configure ai-mode disable

configure ai-mode 缺失或失败：跳过上述包装；改用 ALIBABA_CLOUD_USER_AGENT（下一代码块）。记录 CLI 故障（例如子命令不可用）。配置文件是否有效仅由 aliyun configure list 和 sts get-caller-identity 决定——使用“valid” / “validity”，不要写成 vaild。

User-Agent（必需）：为 Alibaba Cloud API 调用设置 User-Agent：

export ALIBABA_CLOUD_USER_AGENT="AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-diagnose"

CLI 加固（建议）：编写原始 aliyun 命令时，先采用 §2.1 MUST 插件格式，然后添加 --connect-timeout 3 --read-timeout 10（对于大型响应或 CMS，可增大 read-timeout），与实例管理技能示例保持一致，以避免网络故障导致命令无限期挂起。如果未设置全局 User-Agent，则在每次调用中添加 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-diagnose。对于 check_es_instance_health.py 中的可选 Elasticsearch 探测（设置了 ES_* 时），该脚本也支持 --connect-timeout / --read-timeout 这两个参数——它们仅映射到引擎调用的 curl，不会传递给 Aliyun OpenAPI 客户端。

诊断前运行：

aliyun version
aliyun configure list
aliyun --profile <profile_name> sts get-caller-identity

2.2 Elasticsearch API 直接访问（curl）

确认 Elasticsearch 端点（VPC 或公网）和管理员凭据后，让用户在本地终端中设置连接变量——不要在聊天中硬编码用户特定的值：

export ES_ENDPOINT="http://<elasticsearch-endpoint-ip>:9200"
export ES_USERNAME="elastic"
export ES_PASSWORD="<elasticsearch-admin-password>"

公网访问以及 http 与 https： 从 DescribeInstance 获取 publicDomain / domain 和报告的 protocol。当 protocol 为 HTTP（典型的公网监听器）时，将 ES_ENDPOINT 设置为 http://<publicDomain>:9200。对仅支持 HTTP 的端点使用 https:// 会导致 TLS 错误（例如 WRONG_VERSION_NUMBER）。仅当 protocol 为 HTTPS（或你使用的端口实际启用了 TLS）时才使用 https://，并按照下文的 HTTPS 选项提供 CA / 指纹选项。

如果 http://“无法使用”——何时尝试 https://： 将 DescribeInstance 的 protocol 视为 REST 监听器的事实依据。当 protocol 仍为 HTTP 时，http:// 返回 000、超时或连接被拒绝，通常意味着网络路径 / 允许列表 / 安全组 / 主机或端口错误——而不是“接下来尝试 HTTPS”。当 protocol 为 HTTPS（或控制台 / 产品文档说明该端点使用 TLS），且 http:// 出现的故障是 TLS 或协议方案问题时（例如 WRONG_VERSION_NUMBER、error:0A00010B，或使用错误协议方案探测时立即收到 SSL 警报），应切换到 https://。如果 protocol 为 HTTP 且仅声明支持普通 TCP，那么 HTTPS 不能作为连通性的备用方案。

凭据安全

• 绝不回显、打印或记录 ES_PASSWORD；绝不将聊天中的凭据复制到 shell 历史记录或保存的文件中。
• 绝不要求用户在聊天中以明文粘贴密码。
• 仅使用以下检查来验证变量是否已设置：

[[ -n "$ES_ENDPOINT" ]] && echo "ES_ENDPOINT: $ES_ENDPOINT" || echo "ES_ENDPOINT: NOT SET"
[[ -n "$ES_PASSWORD" ]] && echo "ES_PASSWORD: SET" || echo "ES_PASSWORD: NOT SET"

网络连接与访问控制

问题	检查方法	缓解措施
已禁用公网访问	Elasticsearch 控制台 → 网络	启用公网访问或使用 VPC 端点
公网访问允许列表	控制台 → 安全 → 公网访问允许列表	添加 Agent 主机的公网 IP
VPC 隔离	例如：telnet <ES_IP> 9200	使用 VPC 对等连接、专线连接或同等方式
安全组	托管 Elasticsearch 的 ECS / 安全组的入站规则	允许 TCP 9200（或已配置的端口）

连通性探测：curl -sS -o /dev/null -w "%{http_code}" --connect-timeout 5 "${ES_ENDPOINT}" — HTTP 状态码 000 通常表示网络路径不可达。不带 -u 时返回 401 属于正常情况（需要身份验证）；如果 ES_PASSWORD 已设置，请继续执行经过身份验证的 GET /_cluster/health（§7）。带 -u 时返回 401 → 凭据错误。000 / 连接被拒绝 / 超时 → 网络、允许列表或 TLS / 协议方案不匹配。 HTTPS — 前提条件（必须满足）

1. 监听器：你调用的 Elasticsearch HTTP 端口（除非已更改，否则为 9200）必须实际使用 TLS — 与 DescribeInstance protocol（HTTPS）或控制台／网络文档保持一致。
2. **URL：**使用 https://<host>:<port>，并确保 host 与 HTTP 使用的相同（例如 publicDomain）。
3. 客户端信任服务器证书：客户端必须信任集群的证书链（集群／云 CA PEM，或 TLS 被拦截时使用企业代理 CA）。curl：优先使用 curl --cacert /path/to/ca.crt ...；-k / --insecure 仅用于短暂的非生产环境诊断。
4. **身份验证：**与 HTTP 使用相同的 ES_USERNAME / ES_PASSWORD（通过 TLS 使用 Basic 身份验证）。

HTTPS — 本技能中的文档说明

• **手动使用 curl（§7 和 es-api-call-failures.md）：**使用 https:// 时，如果默认信任库不包含集群 CA，则为每个 curl 添加 --cacert（或测试时使用 -k）。
• **check_es_instance_health.py 可选 ES 探测：**此脚本调用 curl 时仅使用 -u；不会读取 ES_CA_CERTS / ES_SSL_FINGERPRINT / ES_VERIFY_CERTS（这些名称常见于 Python Elasticsearch 客户端）。对于 HTTPS 实例，进行深度检查时请使用带 --cacert 的 §7 curl，或者稍后扩展脚本，以便从环境变量传递 --cacert。
• Python 风格的环境变量（供其他工具参考）：ES_CA_CERTS、ES_SSL_FINGERPRINT、ES_VERIFY_CERTS=false（仅用于测试）— 当前未接入本仓库的可选 curl 路径。

---

3. RAM 权限检查

[MUST] RAM 权限预检查

运行此技能前，请确认主体拥有所需的 RAM 权限。 完整列表请参阅 references/ram-policies.md。 如果用户报告权限不足，请引导他们在 RAM 控制台中附加相应策略。

---

4. 参数确认

重要：参数确认 在执行任何命令或 API 调用之前，请与用户确认以下内容。 不要假设未声明的默认值，也不要硬编码特定于用户的参数。

边界控制（必须）

• 不得猜测 Region 和 instance-id，也不得使用未经验证的默认值；如果它们与 DescribeInstance 的结果或用户的明确说明不一致，请再次确认。
• 不得将实例 A的指标、日志或 DescribeInstance 结论应用于实例 B；ES_ENDPOINT 必须与正在诊断的实例相符（请参阅下文的 Elasticsearch API 预检验证）。
• 本技能仅用于只读诊断：不得调用会修改状态的控制平面 API（创建、调整大小、重启、删除实例等）。如果用户要求更改，请仅提供建议；实际操作应在控制台或经批准的变更工作流中执行。

参数	必需	描述	默认值
instance-id	是	Elasticsearch 实例 ID，例如 es-cn-xxxxx。aliyun 标志为 --instance-id（不是 --InstanceId）。	-
region	是	Region ID（例如 cn-hangzhou）。aliyun 标志为 --region（不是 --region-id）。	-
profile	否	Aliyun CLI 配置文件（建议显式指定 --profile）	default
ES_ENDPOINT	否	Elasticsearch 端点（仅用于直接 API 访问）	-
ES_PASSWORD	否	Elasticsearch 管理员密码（仅用于直接 API 访问）	-
--window	否	check_es_instance_health.py：分析时间窗口，单位为分钟（默认值为 60）	60
--connect-timeout、--read-timeout	否	check_es_instance_health.py：设置可选 ES 引擎探测的 curl 超时（需设置 ES_*）；--connect-timeout → curl --connect-timeout；--read-timeout 与连接超时共同决定 curl -m。默认值分别为 5 / 10 秒。	5 / 10

---

5. 端到端诊断工作流

Agent 硬性规则（不可协商）

Aliyun CLI 格式： 对于 aliyun elasticsearch 和 aliyun cms，每条新执行的命令都必须遵循 §2.1 MUST（仅插件模式）——不要在会话导出或面向用户的步骤列表中恢复旧版 DescribeInstance / ListSearchLog 子命令行或 --InstanceId 之类的标志（这些内容与 openapi_cli_collect.py 不一致，且无法通过静态检查）。

OpenAPI/CMS 不能替代 MUST 引擎 API。 对于任何 §5 MUST 表格行或 check_es_instance_health.py 规则引擎 MUST，Alibaba Cloud OpenAPI 和 CloudMonitor 都不能替代所列的 Elasticsearch REST 调用来查明引擎层面的根因——只要可行性条件满足，就运行这些 curl 端点（见 §7）；它们属于互补层，不可互换。

可行性只能通过检查来判定，不能凭假设。 Agent 是否可以调用 Elasticsearch，必须通过实际执行 可行性检查顺序（§5）来判定：至少要按照 §2.2 验证 ES_ENDPOINT / ES_PASSWORD，将 ES_ENDPOINT 与 DescribeInstance 的结果对齐，然后执行经过身份验证的 GET /_cluster/health。不要在会话中未执行这些步骤的情况下，就假设 ES_* 未设置或路径不可达。

处理 Elasticsearch 事件时，请遵循以下四个步骤；每一步都有不同的作用。

执行策略（根因驱动）

完整策略：es-api-diagnosis-strategy.md

数据平面 curl 收集必须同时满足以下条件：

1. 可行性：已设置 ES_ENDPOINT 和 ES_PASSWORD，且网络路径正常。
2. 必要性：根因分析需要数据平面证据，而控制平面或 CMS 无法单独提供这些证据。

对于触发的 MUST 表格行 或 规则引擎 MUST 下列出的端点，这些调用的必要性已由触发条件满足——仍须满足可行性（参见可行性顺序）。对于不在这些列表中的可选引擎 curl，请按照 es-api-diagnosis-strategy.md 分别判断可行性和必要性。

MUST 触发条件（如果以下任一 CMS 条件成立，则收集所列的 Elasticsearch 证据）：

触发条件	场景	所需的 Elasticsearch 证据
ClusterStatus 最大值 ≥ Yellow / Red	集群健康状况	allocation/explain、_cat/shards
NodeCPUUtilization 最大值 > 80%	CPU 过载	_nodes/hot_threads、_tasks
NodeHeapMemoryUtilization 最大值 > 85%	内存压力	_nodes/stats/breaker、GET /_cluster/settings?include_defaults=true（ transient / persistent 中的 indices.breaker.*）
线程池 rejected > 0	性能	_nodes/hot_threads、_nodes/stats/thread_pool
节点间资源 CV > 0.3	负载不均衡	_cat/shards、_cat/allocation
写入失败或索引只读	磁盘 / watermark / 阻止	_cluster/settings、_all/_settings?filter_path=*.settings.index.blocks、_cat/allocation
Elasticsearch API 间歇性超时 + CMS CPU > 80%	可能发生级联故障	_nodes/hot_threads、_nodes/stats/thread_pool、_tasks

线程池行：请参照 sop-query-thread-pool.md 与 sop-write-performance.md，区分 search 和 write / bulk（另请参见下文的写入路径 / bulk 饱和）。

**规则引擎 MUST：**如果 check_es_instance_health.py 针对本次运行输出了 §5 MUST / §5–§7 提示，则按上述表格行处理——在满足可行性的情况下，收集该提示列出的 ES 证据。

约束规则（MUST 触发条件）：如果上述任一 MUST 触发行或规则引擎 MUST 行适用，则该证据集的必要性已满足——对于引擎级根因，OpenAPI / CMS 无法替代这些调用（集群健康状况：Yellow / Red 时调用 allocation/explain + _cat/shards）。请根据下文的可行性顺序确认可行性。如果经过身份验证后可以访问，请在并行收集控制平面信息的同时，于步骤 2 中运行 MUST 列出的端点。如果经过身份验证的 GET /_cluster/health 仍受阻，请在开头说明阻塞原因：未设置 ES_*；传输失败（000、拒绝连接、超时）；带 -u 时返回 401；协议方案 / TLS 不匹配——而不是在 ES_PASSWORD 已设置时对未认证探测返回的 401。

写入路径 / bulk 饱和

如果 ThreadPool.WriteRejected 或 write 池压力与高 QPS bulk 索引写入相符，请阅读并遵循 references/sop-write-performance.md — §2 中的 “证据解读：bulk QPS → write pool” 小节，了解证据链、rejected 的含义（节点启动以来的累计值）、报告顺序与 Old GC / heap 的关系（因果链或双重 P0——写入路径优先于仅关注 JVM 的标题）、每节点的 rejected / completed 数值（拒绝占比）、节点间不对称情况，以及仅写入与搜索的区别。当该小节适用时，不要以仅关注 JVM 的叙述开篇。对于写入队列式验收提示，开篇结论应从写入容量角度表述（数据平面计数器 + 可选的 CMS 规则名称），而不能只以 GC / heap 为标题。

Search 为主还是 write 为主（两个线程池均显示累计 rejected）

当同一节点（或多个节点）的 _nodes/stats/thread_pool 显示 search.rejected ≫ write.rejected，且适用 ThreadPool.SearchRejected / query-driven 过载时，执行摘要和 P0 排序应以 search 为主因（高并发查询 / terms / 慢查询；经核实后可包括热点索引），而非优先归因于 write。write.rejected 仍可作为并行或次要原因列为 P0/P1（批量写入、追赶）；Old GC / CPU / 节点断连则保持为共同压力因素或级联因素。检查器的列出顺序不能证明叙述顺序 — 参见 acceptance-criteria.md §6.5 和 sop-query-thread-pool.md 报告叙述。

存在按时间解析的证据时，近期性优先于这一幅度默认规则：不要仅凭 search.rejected 与 write.rejected 的对比来排列开篇的原因 — 累计计数器没有时间戳。完整判断标准见：acceptance-criteria.md §6.5（P0 / 执行摘要顺序与 search ≫ write：除非按时间看 write 占主导）和 §6.6（执行摘要顺序、不得从计数器误判近期性）。强制要求：下文的时间线和近期性（MUST）（同一技能）。

activating / 变更工作流卡住（跨层根因）

当实例持续处于 activating、变更尚未完成，且同时存在 Red 或未分配分片时，必须端到端遵循 references/sop-activating-change-stuck.md（MUST 包括 ListActionRecords、修复前后调用 DescribeInstance、收集顺序第 3.1 节、报告要求第 4 节）。

Elasticsearch API 的飞行前验证

[IMPORTANT] ES_ENDPOINT 必须与正在诊断的实例一致

将 DescribeInstance 返回的 publicDomain / domain 和 protocol 与 ES_ENDPOINT 比较。 如果不一致，请警告：⚠️ ES_ENDPOINT does not match the current instance; run export ES_ENDPOINT="http://{publicDomain}:9200"，其中 protocol 为 HTTP 时使用 http://；只有 protocol 为 HTTPS 时才使用 https://…（调整主机和端口以匹配部署）。

Elasticsearch 凭证缺失或连接失败时

[CRITICAL] 明确指导用户修复连通性；对失败模式进行分类（不要默认把持续超时归为“仅白名单问题”）。不要暗示 Agent“忘记了” Elasticsearch — 如果首个答复侧重 CMS/OpenAPI，应依据下文的可行性顺序说明阻塞原因：未设置 ES_*；传输错误；使用有效 -u 时返回 401；TLS/协议方案问题 — 而不是在 ES_PASSWORD 已设置时，对未使用 -u 的探测结果直接认定为 401（先使用经过身份验证的 curl）。

渐进式操作手册（按顺序阅读）：references/es-api-call-failures.md（第 1 → 4 节）。
MUST / 策略背景：references/es-api-diagnosis-strategy.md（第 1–3 节和 3.5 汇总表）。

MUST 适用但未配置 Elasticsearch 时的强制警告

[CRITICAL] 如果触发了 MUST 条件，但缺少数据面证据，请在报告顶部添加警告：遵循 references/es-api-call-failures.md 的第 4 节（先说明阻塞原因，再列出 MUST 项和缺失证据；如果未设置 ES_*，指向本 SKILL 的第 2.2 节；如果已设置变量，则使用 es-api-call-failures 的第 1–2 节区分身份验证与传输问题）。

步骤 1：快速健康扫描（初始信号）

运行轻量级规则引擎（17 条指标规则），列出 P0 / P1 / P2 发现，并指导后续深入收集：

python3 scripts/check_es_instance_health.py -i <InstanceId> -r <RegionId> [--window <minutes, default 60>] [--profile <profile_name>]

可行性判断顺序（Agent）

1. 运行 §2.2 ES_* 检查（密码仅检查是否已设置）—不得跳过；未执行此步骤，绝不能推断可行性。
2. ES_ENDPOINT 与 DescribeInstance 的 domain / publicDomain 匹配（协议/端口）。
3. 经过身份验证的 GET /_cluster/health—如果已设置 ES_PASSWORD，未经身份验证的探测即使返回 401，也不要就此停止。
4. 必须限定范围：§5 中的表格行和/或规则引擎 MUST 行。

步骤 2：并行收集证据

根据步骤 1，并行运行收集操作（优先处理有信号的维度）。
如果适用某个 MUST 触发行或规则引擎 MUST：运行可行性判断顺序，然后在同一轮中通过 curl 运行所需的 Elasticsearch 证据收集（见 §7）。如果没有适用的 MUST，则仅当根据策略文档同时满足可行性和必要性时，才添加可选的数据平面 curl。

按照与步骤 1 相同的调用模式重新运行 check_es_instance_health.py；此并行轮次通常使用 --window 120 和显式的 --profile <profile_name>。

若要补充控制平面证据（DescribeInstance、ListSearchLog、CMS 风格的调用），请使用 references/verification-method.md 中的 aliyun 模式（纪元时间、配置档案、命名空间）。

注意：数据平面访问仍需要 ES_ENDPOINT / ES_PASSWORD；Aliyun CLI 不能代替 curl 访问集群。

对于 MUST 触发行，其中列出的端点的必要性已经确定—只要可行性（包括可达性）成立，不得跳过这些端点。对于这些行以外的情况，不要仅因已设置 ES_* 就执行无关的大批量 curl；应改用策略文档中的可行性 + 必要性测试。

步骤 3：根据观察到的信号阅读 SOP

将信号对应到 SOP 并阅读，以进行深入分析。如果有多个信号，先按严重性依次处理 P0 → P1 → P2，然后在步骤 4 中应用时间线和近期性（MUST），使叙述顺序与信号在时间窗口内的重要时间点相符，而不只是遵循规则引擎的静态输出顺序。

观察到的信号	阅读
集群 Red/Yellow、节点丢失、待处理任务	references/sop-cluster-health.md
长时间处于 activating 状态、未完成的变更记录、Red / 未分配分片	references/sop-cluster-health.md + references/sop-activating-change-stuck.md
CPU 使用率高、负载高、负载不均	references/sop-cpu-load.md
节点间负载不均（CPU/内存/磁盘/分片数）	references/sop-node-load-imbalance.md
JVM 压力、GC、熔断器、OOM	references/sop-memory-gc.md
磁盘水位线、IO、写入失败（只读）	references/sop-disk-storage.md
水位线配置错误、索引块、“磁盘使用率正常”但写入失败	references/sop-disk-storage.md（第 3 节 — 水位线配置错误）
写入超时 / 拒绝 / 延迟 / QPS 下降	references/sop-write-performance.md
查询超时 / 拒绝 / 慢查询	references/sop-query-thread-pool.md
节点看似宕机但仍报告 CPU；all shards failed	references/sop-service-avalanche.md
Elasticsearch 间歇性超时 + CMS CPU > 80%	references/sop-service-avalanche.md
高风险设置、Ngram 问题、API 异常	references/sop-configuration.md
事件代码定义	references/health-events-catalog.md

第 4 步：综合并撰写结构化报告

验收式可选检查清单： references/acceptance-criteria.md §6.1–§6.6 — Red/Yellow；读密集型 CPU + search 池（+ CMS 对齐）；JVM / 熔断器 / fielddata；写入队列与 GC + rejected/completed；读密集型 search 池与仅 GC 标题（详见 sop-query-thread-pool.md 报告叙述：search 池与 GC / CPU 标题）；时间线/近期性。批量写入： references/sop-write-performance.md §2。分片 reroute： references/sop-node-load-imbalance.md §1.3（仅限分配器 / 变更控制）。

[CRITICAL] 补救措施必须与诊断出的根本原因相符 — 避免使用通用模板。错误的熔断器或并发修复（例如将 in_flight_requests 与 request 混淆，或在问题出于并发时提出“拆分查询”）→ 参阅 sop-memory-gc.md 和触发信号对应的 SOP。

activating + 数据平面异常：请包含一行跨层根本原因；参阅 references/sop-activating-change-stuck.md 第 4 节。

报告模板（复制/填写）： references/report-template.md。

时间线与时效性（合成报告中必须遵循）

问题： check_es_instance_health.py 和 P0/P1/P2 分级表达的是严重程度，而非某个信号在分析窗口内何时最为重要。引擎的累计计数器（search.rejected、write.rejected）不包含时效信息——写入和搜索问题可能都“真实存在”，但近期只有一个路径占主导（例如，相比写入压力，搜索压力更接近窗口结束时）。

Agent 必须遵循的规则：

1. 两个维度——将严重程度（P0/P1/P2）与时间相关性（距窗口结束 /“当前”的远近）视为相互独立。如果有按时间变化的证据表明并非如此，不要仅凭优先级推断时效性（例如：“写入是 P0，所以当前报告重点一定是写入”）。
2. 必须提供面向用户的章节——当出现多个主要发现时（例如写入线程池 + 搜索线程池 + GC/CPU），合成报告必须在执行摘要之前或紧接其后包含一个 ### Incident timeline (recency-ordered)（或等效）区块，除非用户明确要求精简报告。在该区块中：
   • 按时间先后排序项目符号或行（较早 → 较晚），或说明在 {begin} ~ {end} 的后段，哪个信号簇达到峰值 / 持续存在。
   • 指出分歧：例如，若 CMS 或日志支持，则说明“窗口前段存在写入路径压力；搜索路径 / CPU 压力更近期”。
3. 时效性证据（使用已有证据；不要编造时间戳）：
   • CloudMonitor：各指标的时间序列——如果采集的 JSON 中提供了 NodeCPUUtilization、NodeHeapMemoryUtilization、GC 相关指标、ThreadPool.* 的速率或非累计序列，请注明峰值时间戳或持续偏高的时间区间。
   • 慢日志 / ListSearchLog：将查询与索引慢日志条目按分钟关联。
   • 引擎（可选）：在已知时间采集两次 _nodes/stats/thread_pool，展示 rejected / completed 的增量；或者使用 _tasks / _nodes/hot_threads，查看与历史累计计数器相比的当前倾斜情况。
4. 执行摘要的排序——开头 2–4 句应体现按时效性加权的用户影响：如果搜索压力比写入压力更接近当前，应优先说明搜索 / 查询并发压力及相关的共同压力（如 GC/CPU），并将历史写入饱和作为背景或第二波问题——如果 P0 写入问题仍需要纳入修复待办，不要将其省略。
5. 明确说明不确定性——如果只有累计计数器，且没有能区分不同路径的时间序列，请用一行说明：无法区分近期性；建议下次运行时使用更窄的窗口、慢日志或增量采样。

---

6. 数据采集详情（CLI OpenAPI + 注入输入）

单次运行入口

使用与 §5 Step 1 相同的 check_es_instance_health.py 命令（可选 --window / --profile；若未指定，默认窗口为 60 分钟）。

注入输入模式（与 CLI 配合使用）

check_es_instance_health.py 接受外部 JSON，以避免重复调用：

python3 scripts/check_es_instance_health.py \
  -i <InstanceId> -r <RegionId> \
  --data-source input \
  --input-json-file /path/to/diag-input.json

输入 JSON 结构：

{
  "status_info": {},
  "metrics": {},
  "events": [],
  "logs": []
}

--data-source 模式：

• auto：优先使用注入字段；通过 Aliyun CLI 补齐缺失数据。
• cli：忽略注入数据；通过 CLI 获取所有数据。
• input：仅使用注入数据；不调用 OpenAPI。

手动补充控制面 CLI 数据

如需了解更多 OpenAPI 示例，请参阅 references/verification-method.md。

7. Elasticsearch 直接 API 访问（数据面深入分析）

当可行性成立（包括可达性）时，执行任何 MUST 触发项（§5）要求的 REST 调用。对于未列在已触发 MUST 项中的端点，仅当策略文档中可行性和必要性都成立时才调用。

ES_ENDPOINT 可以是 host:port 或完整 URL。对于以下示例，请规范化为 http://${ES_ENDPOINT#http://}（当集群使用 TLS 时，请统一使用 https://）。

超时：每个 curl 都必须使用 --connect-timeout 10 --max-time 30。

红色 / 黄色（MUST）— 推荐集合

范围：集群健康状态 MUST 项使用最大值 ≥ Yellow 的 ClusterStatus（包含 Red）。使用此集合排查引擎中的未分配 / 分配错误分片根因。

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cluster/health?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  -H "Content-Type: application/json" \
  -X POST "http://${ES_ENDPOINT#http://}/_cluster/allocation/explain?pretty" \
  -d '{}'

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cluster/pending_tasks?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/stats/thread_pool?pretty"

查询 / 写入性能（MUST）— 推荐集合

如果在步骤 1 中触发了 heap / GC / breaker 规则，或 _nodes/stats/breaker 显示存在隐患，请包含 _cluster/settings — 读取 transient 和 persistent 的 indices.breaker.* / network.breaker.*。

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/hot_threads?threads=3"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/stats/breaker?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cluster/settings?include_defaults=true&pretty"

/_cluster/pending_tasks 和 GET /_nodes/stats/thread_pool 也列在上面的**红色 / 黄色（MUST）**项下——当两个部分都适用时，每个会话各调用一次。如果你只运行此性能区块，请从该区块添加这两行 curl 命令。

无闭环的资源异常（SHOULD）— 推荐集合

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cat/nodes?v&s=cpu:desc&h=name,ip,cpu,heap.percent,ram.percent,load_1m"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/stats/jvm?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cat/allocation?v&bytes=gb"

GET /_cluster/settings?include_defaults=true 也出现在上面的**查询 / 写入性能（MUST）**项下——当两个区块都适用时，复用同一响应。如果你只运行此 SHOULD 区块，请从该区块添加相同的 curl 命令行。

协议检查（避免 WRONG_VERSION_NUMBER）：通常是 ES_ENDPOINT 的 http/https 协议不匹配 — 修正协议 / 端口后重试。

场景 → 端点索引：references/es-api-catalog.md。

---

8. 诊断覆盖范围

知识库涵盖 48+ 条健康事件类规则和串联场景（例如：磁盘压力 → 分配 → 红色）。各类别计数、P0/P1/P2 分布和事件代码：references/health-events-catalog.md — 场景操作手册：references/sop-*.md（索引：references/README.md）。

---

9. 最佳实践

**只读：**不调用会修改状态的控制面 API；不执行拆除操作。

1. 分层 + 证据支撑：扫描 → 深入 SOP；每个结论都要引用指标 / 日志 / 事件；如果 ES 无法访问，请说明限制（es-api-call-failures.md）。
2. 优先级与叙述：紧急程度按 P0→P2；当多个维度在时间上存在差异时，使用事件时间线（步骤 4）。凭据 / TLS / 参数：§1–2 和 §4。
3. 绿色不代表“一切正常” — 水位线、区块和设置错误的限制仍然重要；**MUST + ES 可达：**即使集群为绿色，或 OpenAPI “解释”了症状，也不要跳过 §5/§7 中的证据。
4. 线程池 rejected：除非展示增量，否则它是累计值 — sop-query-thread-pool.md §1–2；写入 / bulk：sop-write-performance.md §2。

---

10. 参考链接

• references/verification-method.md — 验证（如何验证诊断结果；指标、API、工作流）
• references/report-template.md — 结构化诊断报告模板
• references/README.md — 语言映射（参考资料和 sop-*.md 操作手册；此仓库使用英文）
• references/ram-policies.md — RAM 策略列表
• references/acceptance-criteria.md — 正确/错误模式与验收（包括凭证和安全反模式）
• references/cli-installation-guide.md — Aliyun CLI 安装
• references/es-api-catalog.md — Elasticsearch REST API 目录
• references/health-events-catalog.md — 健康事件目录
• references/sop-*.md — 场景 SOP（例如，sop-activating-change-stuck.md 用于排查 activating / 变更卡住和跨层根因）
• references/es-api-diagnosis-strategy.md — Elasticsearch API 诊断策略