项目关键词：Elasticsearch 9.3、ES|QL、Kibana Maps、Kibana Alerting、AI Agent Builder、通义千问、Runbook 语义检索、MCP、A2A、多 Agent 运维分析。
本文介绍一个 "景枢" 的技术设计与实现。它面向多家大型文旅景区购票平台，基于脱敏后的真实 nginx 与 service 日志构建一个 AI 运营值班长：当支付接口变慢、错误码突增或疑似黄牛出现时，系统可以自动完成告警、数据下钻、根因判断、Runbook 检索和分级处置建议。
和普通监控大屏不同，景枢的目标不是"展示更多指标"，而是把 Elastic 的搜索、聚合、语义检索和 Agent 工具调用能力组合起来，让系统能够回答技术团队真正关心的问题：
- 哪个接口真的慢，哪些只是长连接造成的假慢？
- 这次高峰是自然客流、攻击流量，还是内部任务？
- service 侧错误码和 nginx 侧慢请求能否关联起来？
- 历史处置手册能否被 Agent 自动检索并用于生成建议？
- 这些分析能力能否通过 MCP/A2A 暴露给外部 AI 客户端？
1. 场景与数据基础
项目使用的是多景区购票平台的脱敏生产日志，演示窗口包含约 176 万条 nginx 与 service 样本。为避免暴露客户与业务方信息，本文对景区名称、URL slug、订单号、IP、证件号、token 等信息均做匿名化处理。日志覆盖的业务对象抽象如下：
| 匿名景区编号 | 说明 |
|---|---|
park_a |
头部景区 A |
park_b |
头部景区 B |
park_c |
头部景区 C |
park_d |
头部景区 D |
数据源主要分为两类：
- nginx ingress 日志：包含 client_ip、url、status、request_time、upstream_response_time、user_agent、proxy_upstream_name 等字段。
- service 结构化日志：包含 level、error_code、error_message、biz_action、exception_class、stack、order_no 等字段。
这个场景的技术难点在于日志本身不是为比赛准备的"干净数据"。它包含真实世界里的大量噪声：预检请求、nacos 长轮询、WebSocket 长连接、微信订阅消息失败、内部 xxl-job 调度回调、鉴权失败、重复购票错误等。项目的关键不是把日志灌进 Elasticsearch，而是把这些日志清洗成 Agent 可以可靠调用的分析工具。
- 总体架构
景枢采用 "日志治理 + ES|QL 工具 + Agent 编排 + Kibana 可视化 + MCP/A2A 互操作" 的架构。
markdown
`
1. 生产日志
2. ├─ nginx ingress access log
3. └─ service JSON log
4. |
5. v
6. Elasticsearch Ingest Pipeline
7. ├─ 字段解析：park / api_path / error_code / biz_action
8. ├─ 合规脱敏：身份证 / token / openid / orderNo / client_ip
9. ├─ GeoIP 丰富：client_geo.location / region / city
10. ├─ 噪声标记：nacos / websocket / xxl-job / OPTIONS
11. └─ 关联字段：order_no_hash / proxy_upstream_name
12. |
13. v
14. Elasticsearch 索引
15. ├─ nginx_logs
16. ├─ service_logs
17. └─ runbook_kb
18. |
19. v
20. 分析与智能化
21. ├─ ES|QL Tools
22. ├─ Kibana Dashboard / Maps / Alerting
23. ├─ AI Agent Builder
24. └─ Qwen Connector + Embedding
25. |
26. v
27. 对外互操作
28. ├─ MCP：暴露工具给 Claude / Cursor 等客户端
29. └─ A2A：暴露 Agent 给外部 Agent 框架
`AI写代码这套架构里，Elasticsearch 不是单纯的日志存储，而是三类能力的统一底座：
- 结构化分析：ES|QL 聚合、过滤、分桶、TopN。
- 语义检索：Runbook 知识库向量化后供 Agent 检索。
- Agent 工具运行时：Agent Builder 将 ES|QL 查询封装为可调用工具。
- 数据治理：从原始日志到可分析索引
3.1 景区解析
景区 slug 并不总是出现在固定 path 层级。为避免暴露真实路径，下面使用匿名路径示例：
- /gateway/park_a/...
- /gateway/ws/park_a/webSocket?orderId=...
其中 ws 代表 WebSocket 模块，不是景区。因此不能简单取 URL 的固定段作为景区。项目在 pipeline 中使用匿名景区白名单 {park_a, park_b, park_c, park_d} 在整条 path 中匹配，避免把模块名误判为景区。
3.2 脱敏策略
日志中包含真实敏感信息，因此入库前必须完成脱敏，同时保留分析能力。
| 字段 | 风险 | 处理方式 |
|---|---|---|
| 身份证号 | 真实个人身份信息 | mask 或 hash |
| 微信 access_token | 真实密钥 | 整段抹除 |
| openid | 用户标识 | hash 或删除 |
| orderNo | 订单号 | 一致性 hash，保留 join 能力 |
| client_ip | 公网 IP | GeoIP 后降精度，不保留原始 IP |
这里一个重要设计是 orderNo 不直接删除，而是做一致性 hash。这样 nginx 侧 URL 中的 orderId/orderNo 与 service 侧日志中的订单号可以在脱敏后继续关联，用于购票链路下钻。
3.3 噪声标记
项目没有简单删除噪声数据，而是增加 is_noise、noise_reason 等字段。这样做有两个好处：
- Dashboard 可以同时展示"信号 vs 噪声"的对比。
- Agent 可以解释为什么某些监控指标不应触发升级。
典型噪声包括：
- OPTIONS 预检请求。
- /nacos/v1/cs 长轮询。
- /webSocket 出票状态推送长连接。
- xxl-job 调度器回调与 registry。
- 非核心微信订阅消息推送失败。
这一步是项目里非常关键的工程判断。没有噪声建模，后面的 Agent 很容易把"长连接假慢""内部调度高频访问"解释成故障或攻击。
- 索引设计
项目核心索引有三个。
4.1 nginx_logs
用于请求链路、接口耗时、来源地理分布与流量趋势分析。核心字段包括：
markdown
`
1. @timestamp
2. park
3. api_path
4. method
5. status
6. request_time
7. upstream_response_time
8. proxy_upstream_name
9. ua_device
10. is_slow
11. is_noise
12. noise_reason
13. order_no_hash
14. client_geo.country_name
15. client_geo.region_name
16. client_geo.city_name
17. client_geo.location
`AI写代码4.2 service_logs
用于业务错误、异常堆栈和业务动作分析。核心字段包括：
markdown
`
1. @timestamp
2. park
3. level
4. error_code
5. error_message
6. biz_action
7. exception_class
8. stack
9. order_no_hash
10. is_noise
`AI写代码4.3 runbook_kb
用于处置手册语义检索。核心字段包括：
markdown
`
1. symptom
2. root_cause
3. action
4. priority
5. error_code
6. semantic_text
`AI写代码semantic_text 会组合故障现象、根因、错误码和处置动作，再通过通义千问 embedding 写入向量字段。这样用户输入"付款一直转圈"这类自然语言，也能命中"支付接口高峰变慢"相关 Runbook。
- ES|QL Tool 设计
Agent Builder 的关键不是让大模型自由生成查询，而是把高价值分析路径封装成稳定工具。项目中把常用 ES|QL 查询注册为 Agent 可调用的 Tool。
5.1 慢接口分析 slow_api_topn
用于排除长连接噪声后定位真实慢接口。
ini
`
1. FROM nginx_logs
2. | WHERE is_noise == false AND request_time > ?min_seconds
3. | STATS
4. slow_count = COUNT(*),
5. p50 = PERCENTILE(request_time, 50),
6. p90 = PERCENTILE(request_time, 90),
7. p99 = PERCENTILE(request_time, 99)
8. BY api_path
9. | SORT slow_count DESC
10. | LIMIT 10
`AI写代码在演示数据中，该工具定位到 /shop/order/payOrder 是真实业务慢接口，P99 约 6.8 秒。
5.2 景区流量趋势 park_traffic
用于判断流量峰值是否集中在某一景区或某一时间段。
less
`
1. FROM nginx_logs
2. | WHERE is_noise == false
3. | STATS requests = COUNT(*) BY park, ts = BUCKET(@timestamp, 5 minute)
4. | SORT ts
`AI写代码5.3 客流来源 visitor_geo
用于支撑 Kibana Maps 和 Agent 判断"自然高峰 vs 单点攻击"。
sql
`
1. FROM nginx_logs
2. | WHERE is_noise == false AND client_geo.region_name IS NOT NULL
3. | STATS visits = COUNT(*) BY province = client_geo.region_name
4. | SORT visits DESC
5. | LIMIT 20
`AI写代码5.4 业务错误分析 error_breakdown
用于从 service 日志中识别真正影响业务的错误。
ini
`
1. FROM service_logs
2. | WHERE level == "ERROR" AND is_noise == false
3. | STATS errors = COUNT(*) BY error_code, biz_action
4. | SORT errors DESC
`AI写代码5.5 黄牛识别 scalper_detect
用于分析 errorCode=4027 等重复购票错误。
sql
`
1. FROM service_logs
2. | WHERE error_code == "4027"
3. | STATS attempts = COUNT(*) BY order_no_hash
4. | WHERE attempts >= 2
5. | SORT attempts DESC
`AI写代码实际系统中也可以把证件 hash、设备指纹、手机号 hash、IP geo 和时间窗一起纳入聚合。比赛版本保留了脱敏后的最小可演示链路。
- Kibana 可视化与告警
项目构建了一个 Kibana Dashboard，作为运营中枢的第一视图。它包括：
- 总请求量、慢请求量、Geo 坐标点数量。
- 多景区流量排名。
- 5 分钟粒度流量趋势。
- 慢接口 Top10。
- 来源省份 Top10。
- 业务错误码分布。
- 信号与噪声对比。
- 客流来源地图。
其中 Kibana Maps 使用 client_geo.location 字段展示访问来源。演示窗口中有 62,115 个可用坐标点，可以直观看出本地客流与跨区域客流同时存在的分散访问特征。
告警使用 ES|QL 规则监控 payOrder 的 P99 延迟：
ini
`
1. FROM nginx_logs
2. | WHERE api_path == "/shop/order/payOrder"
3. | STATS p99 = PERCENTILE(request_time, 99)
4. | WHERE p99 > 3
`AI写代码这条规则的作用不只是触发告警，而是作为 Agent 分析链路的入口：告警提供时间窗口与异常对象，Agent 再基于工具完成后续诊断。
除了实时 Dashboard，项目还在 ops-platform 中实现了独立的值班交接报告页，对应访问路径为 /report。这不是一份静态模板，而是由后端通过 ES|QL 按班次时间窗聚合 nginx_logs、service_logs 和告警数据后动态生成：报告会汇总总请求、真实业务请求、慢请求比例、核心接口 P99、真实业务错误、客流坐标点、噪声过滤比例、风控信号和 401 鉴权热点，并基于规则化逻辑自动给出"告警 / 关注 / 正常"的健康分级、根因研判、分级处置建议和遗留交接事项。页面采用 A4 文档式布局，支持值班主管补充、处置状态编辑、签核确认，并可直接通过浏览器打印或导出 PDF，从而把 Kibana 监控、Agent 诊断和人工值班流程沉淀为可归档、可复盘的运维闭环。
- Agent Builder 实现
项目设计了四类 Agent。
7.1 技术诊断 Agent
挂载工具：
- slow_api_topn
- error_breakdown
- search_runbook
职责是从接口耗时、业务错误与历史处置方案三条线定位根因。它的输出不是日志列表，而是结构化诊断：
markdown
`
1. 慢接口：/shop/order/payOrder
2. 现象：P99 超过 6s
3. 关联错误：创建订单 / 未支付订单 / 系统维护类错误
4. Runbook 命中：支付接口高峰变慢
5. 建议：扩容支付服务、提高连接池、调整限流、必要时降级非核心能力
`AI写代码7.2 业务洞察 Agent
挂载工具：
- park_traffic
- visitor_geo
职责是判断异常是否由自然客流导致。它会看峰值倍率、景区分布、来源地域分布等指标。演示中 06-04 上午 10 点达到约 136,378 请求/小时，是低谷时段的约 7 倍，并且来源省份分散，因此判断为真实高峰。
7.3 风控哨兵 Agent
挂载工具：
- scalper_detect
- auth_anomaly
职责是识别重复购票、鉴权异常、高频访问等风险。它不会把所有高频访问都判定为黑产，而会结合 UA、路径、错误码和业务语义排除内部调度器等噪声。
7.4 运营总管 Agent
总管 Agent 挂载全部核心工具，负责将三类分析结果汇总成值班报告。
在 Elastic 9.3 环境中，Workflow 能力仍属于预览性质，因此项目采用更稳定的 GA 实现：让总管 Agent 挂载所有工具，由大模型根据系统指令完成自路由和综合推理。概念上仍然是多专家分工，但现场演示时以"总管 + 工具编排"的稳定链路为主。
总管输出包含：
- 性质判定：真实高峰、技术瓶颈、非攻击。
- 根因定位：payOrder 支付链路在高峰期 P99 升高。
- 风险信号：少量 4027 重复购票。
- 分级处置：P0 扩容支付服务，P1 调整限流策略，P2 高频证件加验证码。
8. Runbook 语义检索
传统 Runbook 往往以文档形式存在，人需要自己搜索。景枢把 Runbook 做成可检索知识库，并注册为 Agent Tool。
实现流程：
- 编写处置知识：symptom、root_cause、action、priority、error_code。
- 拼接 semantic_text。
- 调用通义千问 text-embedding-v3 生成向量。
- 写入 runbook_kb。
- Agent 根据用户问题或诊断结果调用 search_runbook。
这样一来，技术诊断 Agent 在定位到 payOrder 慢之后，可以进一步检索"支付接口高峰变慢"的历史处置方案。它不是只告诉你"哪里慢"，而是能把"上次怎么处理"带回来。
- MCP 与 A2A：从系统内部能力到外部生态
这个项目还验证了 Agent Builder 的互操作能力。
9.1 MCP 暴露工具
Agent Builder 内置 MCP 端点：
bash
`/api/agent_builder/mcp`AI写代码项目通过该端点把 6 个景区分析工具开放给外部 MCP 客户端。外部客户端可以完成：
- initialize
- tools/list
- tools/call
例如 Claude Desktop 或 Cursor 可以发现 slow_api_topn 并直接调用它，拿到 Elasticsearch 中真实数据的分析结果。这里 MCP 暴露的是工具能力。
9.2 A2A 暴露 Agent
A2A 暴露的是完整 Agent，而不是单个工具。项目验证了：
bash
`
1. GET /api/agent_builder/a2a/{agent_id}.json
2. POST /api/agent_builder/a2a/{agent_id}
`AI写代码外部 A2A 客户端可以先发现 Agent Card，再向技术诊断 Agent 或运营总管 Agent 发送任务。项目中使用官方 A2A SDK 客户端完成了发现与调用验证，返回的是千问驱动的真实诊断结果。
这部分的意义在于：景枢不是一个封闭的 Kibana Demo，而是可以把日志分析工具和智能诊断 Agent 作为能力节点接入外部 AI 工作流。
- 一个完整诊断链路
以 "06-04 上午 10 点支付为什么慢" 为例，系统链路如下：
- Kibana Alerting 触发 payOrder P99 告警。
- 用户向运营总管 Agent 提问。
- 总管调用 park_traffic 与 visitor_geo，判断这是自然客流高峰。
- 调用 slow_api_topn，排除长连接噪声，定位 payOrder 真实慢。
- 调用 error_breakdown，查看 service 侧错误码与业务动作。
- 调用 search_runbook，命中支付高峰处置方案。
- 调用 scalper_detect，识别少量重复购票信号。
- 汇总输出结构化值班报告。
最终输出不是"日志摘要"，而是可执行判断：
markdown
`
1. 性质：真实高峰导致支付链路瓶颈，非攻击。
2. 根因：payOrder 在高峰期 P99 约 6.8s。
3. 影响：购票支付体验下降，伴随少量重复购票风险。
4. 处置：
5. P0：扩容支付服务实例，检查连接池和下游支付依赖。
6. P1：调整高峰限流阈值与排队策略。
7. P2：对高频证件或账号增加验证码与风控拦截。
`AI写代码- 技术收益与工程经验
这个项目带来的最大经验是：AI Agent 做运维分析时，关键不在于让模型"看更多日志"，而在于给它高质量、可控、可解释的工具。
几个工程结论比较明确：
- 日志治理要前置。没有脱敏、字段标准化和噪声标记，Agent 很容易基于错误信号做错误判断。
- ES|QL Tool 要小而稳定。让模型调用明确工具，比让模型临时生成复杂查询更可靠。
- 业务语义要进入索引。is_noise、biz_action、error_code、park、order_no_hash 这些字段决定了 Agent 能不能说出有价值的结论。
- 可视化仍然重要。Kibana Maps 和 Dashboard 可以让人快速建立信任，Agent 则负责继续下钻和解释。
- Runbook 是 Agent 落地的关键。没有处置知识库，Agent 最多定位问题；有了 Runbook，Agent 才能给出可执行建议。
- MCP/A2A 让能力可复用。工具和 Agent 可以被外部客户端调用，这比单一演示页面更接近实际工程集成方式。
总结
景枢的技术价值在于把 Elastic Stack 的几类能力连接成一条完整链路：
rust
`
1. 日志采集治理 -> Elasticsearch 索引 -> ES|QL 分析工具 -> Kibana 告警与地图
2. -> Agent Builder 工具调用 -> Runbook 语义检索 -> MCP/A2A 对外互操作
`AI写代码它验证了一个面向真实业务系统的 AI 运维范式：让大模型不直接 "猜日志"，而是通过受控工具查询真实数据，通过业务字段理解上下文，通过 Runbook 生成可执行建议。
对于技术团队来说，这类系统的重点不是把监控大屏做得更漂亮，而是把可观测数据、业务语义和处置经验组织成 Agent 可以调用的工程化能力。景枢正是沿着这条路径，把一个景区购票平台从 "被动告警" 推进到了 "智能值班"。
参考
刘晓国老师编写的以下文档