ElasticLens：让 Elasticsearch 集群巡检不再 “裸眼读日志“

Elasticsearch
0 阅读11分钟

作者：来自 上海悦高软件股份有限公司 · 大数据团队

一、写在前面

如果你也维护过 Elasticsearch 集群，大概率会遇到这样的场景：

  • 客户报障 "集群慢"，你需要在十几个节点之间逐一排查；
  • 上线前要做一次 "健康巡检"，但官方只给了一个 support-diagnostics 工具，导出的是一坨 ZIP 文件；
  • 报告要写中文版给运维、英文版给海外客户、还要给一份 Word 给老板……

为了把这件 "重复、枯燥、又必须做 "的事情自动化，上海悦高软件股份有限公司大数据团队 研发并开源了一款 Elasticsearch 集群巡检结果可视化分析平台  ——  ElasticLens。

简单一句话概括：

把官方 support-diagnostics 工具导出的 ZIP 包丢进去，几分钟后你拿到的是一份带健康评分、分级告警、可视化图表的多语言巡检报告。

项目当前版本 v1.0.9，已在 GitHub 完整开源：github.com/YogooSoft/E…，欢迎 Star、Issue 和 PR。

二、ElasticLens 是什么

ElasticLens 是一款面向 Elasticsearch 集群巡检结果的可视化与深度分析平台。它专为处理 Elastic 官方诊断工具 导出的诊断 ZIP 包而设计，能够：

  1. 自动解析诊断数据；
  2. 基于规则引擎进行集群健康深度分析；
  3. 生成 HTML / Word / JSON 三种格式的多维度巡检报告；
  4. 支持 7 种语言（中文简繁、英、日、法、德、俄）一键切换；
  5. 提供完整的 Web 平台 + CLI 命令行两种使用方式。

它解决的核心痛点是：让运维人员不再手动翻 JSON、查日志、对阈值，而是通过直观的可视化界面，一眼看出集群健康状态、潜在风险与优化建议。

三、核心特性一览

1. 全栈 Web 平台

基于 React 18 + Flask 3.0 构建的现代化 Web 应用，支持：

  • 拖拽式上传诊断包（最大 2GB）；
  • 后台异步任务处理，长时间分析不阻塞前端；
  • 任务列表、历史记录、统计面板一应俱全；
  • 报告内嵌 iframe 直接预览，亦可一键下载。

2. 多格式报告输出

格式特点
HTML紫色渐变主题、圆形健康评分仪表盘、响应式卡片布局、分级告警
Word (.docx)专业排版、支持表格与色彩编码（✅ 绿 / ❌ 红）、便于交付客户
JSON结构化数据，含完整 check_results，方便二次开发

3. 11 大类 30+ 项检查指标

ElasticLens 内置 50+ 条规则，覆盖以下 11 大类巡检项（每项均配置了独立权重）：

类别权重主要检查项
集群健康30%集群状态、活跃分片占比、未分配分片、初始化/迁移分片
节点资源25%磁盘、JVM 堆、CPU、系统负载、单节点分片数
索引健康20%大索引、段数、分片数、文档数等异常
分片检查5%单分片大小、分布均衡性
恢复检查5%恢复中分片、平均进度
ILM 策略3%生命周期策略状态
快照检查3%快照配置与执行状态
安全检查2%X-Pack 安全特性是否启用
模板与映射2%索引模板、组件模板、字段数
日志与错误2%GC 次数与时间统计
性能信息展示项集群文档总数、总存储（不计分）

4. 量化健康评分

ElasticLens 提供 0–100 分 的量化健康评分：

`Score = 100 - (严重告警 × 20) - (警告告警 × 5) - (信息告警 × 1)` AI写代码
分数区间健康等级
90-100优秀（Excellent）
75-89良好（Good）
60-74一般（Fair）
40-59较差（Poor）
0-39严重（Critical）

5. 三级告警机制

从 v1.0.5 起引入 severity_level 三级告警分类，并在报告中按级分组展示：

  • 🔴 Level 3（必须处理）：严重问题，影响集群可用性；
  • 🟡 Level 2（建议处理）：一般性问题，需关注；
  • 🔵 Level 1（优化建议）：非紧急的优化项。

6. 真正的多语言（i18n）支持

这是 ElasticLens 区别于很多同类工具的一大亮点 —— 不仅前端 UI 多语言，连后端生成的报告也是多语言的。

当前已完整支持 7 种语言：

  • 🇨🇳 简体中文（zh-CN，默认）
  • 🇹🇼 繁体中文（zh-TW）
  • 🇺🇸 英语（en-US）
  • 🇯🇵 日语（ja-JP）
  • 🇫🇷 法语（fr-FR）
  • 🇩🇪 德语（de-DE）
  • 🇷🇺 俄语（ru-RU）

亮点能力：

  • ✅ 前端 UI 动态切换，首页、任务、报告、上传、历史、设置全覆盖；
  • ✅ HTML / Word 报告按所选语言生成，不是简单替换标签；
  • ✅ 内置智能翻译函数，能处理动态内容（例如 5 indices → 5 インデックス → 5 indices）；
  • ✅ Ant Design 组件库自动适配多语言；
  • ✅ 语言偏好自动持久化，下次访问无感切换。

对于需要给海外客户交付报告的团队，这一点尤为珍贵。

7. 高性能与可扩展

  • 后台异步任务队列，支持 2GB 大文件上传 与长时分析；
  • SQLite 持久化任务与报告元数据，零配置即用；
  • 阈值配置全部走 YAML，不改代码即可调优；
  • 规则引擎可插拔，方便扩展自定义检查项。

四、系统架构

ElasticLens 采用经典的"前端 + 后端 + 核心引擎 + 存储"四层架构：

`

1.  ┌─────────────────┐      REST API      ┌─────────────────┐
2.  │   Frontend      │ ◄───────────────►  │   Backend       │
3.  │   (React)       │                    │   (Flask)       │
4.  │                 │                    │                 │
5.  │ - 文件上传       │                    │ - 任务管理       │
6.  │ - 任务跟踪       │                    │ - 异步处理       │
7.  │ - 报告展示       │                    │ - 报告生成       │
8.  │ - 历史记录       │                    │ - 文件管理       │
9.  └─────────────────┘                    └────────┬────────┘
10.                                                  │
11.                                                  ▼
12.                                      ┌────────────────────┐
13.                                      │  es_insight 核心    │
14.                                      │                    │
15.                                      │ - 诊断数据解析       │
16.                                      │ - 规则引擎检查       │
17.                                      │ - 健康分数计算       │
18.                                      │ - HTML/Word 生成    │
19.                                      └────────┬───────────┘
20.                                               │
21.                                               ▼
22.                                      ┌────────────────────┐
23.                                      │   SQLite 数据库     │
24.                                      │                    │
25.                                      │ - 任务元数据         │
26.                                      │ - 报告元数据         │
27.                                      │ - 查询与统计         │
28.                                      └────────┬───────────┘
29.                                               │
30.                                               ▼
31.                                      ┌────────────────────┐
32.                                      │   文件系统          │
33.                                      │                    │
34.                                      │ - 上传 ZIP          │
35.                                      │ - JSON / HTML /    │
36.                                      │   Word 报告         │
37.                                      └────────────────────┘

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

各层职责清晰：前端只负责交互，后端只负责调度，真正的"重活"全部在 es_insight 核心引擎中完成，便于独立维护与单元测试。

五、技术栈选型

后端

组件版本用途
Flask3.0.0Web 框架
Flask-CORS4.0.0跨域支持
python-docx≥ 1.0.0Word 报告生成
loguru0.7.2日志管理
weasyprint≥ 60.0PDF 渲染（可选）
orjson≥ 3.6.0高性能 JSON
SQLite3Python 内置数据存储

前端

组件版本用途
React18.2UI 框架
TypeScript5.2类型系统
Ant Design5.12组件库
Vite5.0构建工具
Axios1.6HTTP 客户端
Zustand4.4状态管理
Recharts2.10图表库

整体选型偏向"主流、稳定、社区活跃"，方便接手、二次开发和企业落地。

六、5 分钟快速上手

ElasticLens 提供两种开箱即用的部署方式。

方式一：Docker 一键部署（推荐生产）

`

1.  # 在项目根目录执行
2.  git clone https://github.com/YogooSoft/ElasticLens.git
3.  cd ElasticLens

5.  # 一键启动前后端
6.  ./start.sh

8.  # 或手动启动
9.  docker compose up -d

`AI写代码

启动完成后：

优势：

  • ✅ 无需安装 Python、Node.js 环境；
  • ✅ 数据持久化（数据库、上传文件、报告全部挂载卷）；
  • ✅ 健康检查与自动重启；
  • ✅ 支持内网离线部署，对金融、政企客户特别友好。

方式二：本地开发模式

`

1.  # 后端
2.  cd backend
3.  pip install -r requirements.txt
4.  python app.py        # 默认 http://localhost:5000

6.  # 前端（新开终端）
7.  cd frontend
8.  npm install
9.  npm run dev          # 默认 http://localhost:5173

`AI写代码

方式三：纯命令行（CLI）

适合做 CI/CD 集成或批量巡检：

`

1.  pip install -r requirements.txt
2.  pip install -e .

4.  # 解析诊断包并生成报告
5.  es-insight data/local-diagnostics-*.zip

7.  # 指定输出目录与格式
8.  es-insight data/local-diagnostics-*.zip -o ./reports -f html,json

10.  # 使用自定义阈值
11.  es-insight data/local-diagnostics-*.zip -c configs/checkpoints_thresholds_complete.yaml

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

七、阈值如何配置

所有规则阈值都集中放在 configs/checkpoints_thresholds_complete.yaml，举几个例子：

`

1.  # 集群健康
2.  cluster:
3.    status:
4.      green: none       # GREEN 不告警
5.      yellow: warning   # YELLOW 警告
6.      red: critical     # RED 严重
7.    active_shards_percent:
8.      warning: 95       # 低于 95% 警告
9.      critical: 90      # 低于 90% 严重

11.  # 节点资源
12.  node:
13.    disk_usage_percent:
14.      warning: 70
15.      alert: 80
16.      critical: 85     # 触发拒写水位
17.    heap_used_percent:
18.      warning: 70
19.      critical: 85     # OOM 风险

21.  # 索引健康
22.  index:
23.    size_gb:
24.      warning: 50
25.      critical: 100
26.    docs_count:
27.      warning: 100000000      # 1 亿
28.      critical: 500000000     # 5 亿

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

业务方完全可以根据自家集群规模调整这些阈值，无需改一行 Python 代码。

八、API 一览

ElasticLens 后端暴露了一组 RESTful API，方便与现有运维平台集成：

任务管理

方法路径说明
POST/api/v1/upload上传诊断 ZIP，创建异步任务
GET/api/v1/tasks获取任务列表（分页）
GET/api/v1/tasks/<task_id>获取单个任务详情
DELETE/api/v1/tasks/<task_id>软删除任务（级联删报告）

报告管理

方法路径说明
GET/api/v1/reports报告列表（支持筛选与分页）
GET/api/v1/reports/statistics报告统计信息
GET/api/v1/reports/<report_id>报告 JSON 数据
GET/api/v1/reports/<report_id>/html获取 HTML 内容字符串
GET/api/v1/reports/<report_id>/view直接预览 HTML 报告
GET/api/v1/reports/<report_id>/download?format=word下载 Word 报告
GET/api/v1/reports/<report_id>/download?format=json下载 JSON 报告
GET/api/v1/reports/<report_id>/download?format=html下载 HTML 报告

完整的 API 设计与字段说明见 doc/Frontend Design/Backend Service Design.md。

九、典型使用场景

ElasticLens 既适合个人学习，也适合企业级落地，以下是几个典型场景：

  1. 运维日常巡检
    每周/每月跑一次诊断 + ElasticLens，自动出健康评分趋势，做"集群健康月报"。
  2. 故障应急排查
    线上告警时，先跑一次诊断 + ElasticLens 快速定位是磁盘、JVM、还是分片分布的问题。
  3. 乙方/服务商交付
    给客户做 ES 集群健康咨询时，一键产出多语言、专业排版的 Word 报告。
  4. CI/CD 集成
    在自动化测试或灰度发布流水线中调用 CLI，把巡检结果写入流水线产物。
  5. 离线/内网环境
    通过 Docker 镜像离线打包后部署到金融、政企等隔离网络环境。

十、版本演进（节选）

ElasticLens 迭代非常活跃，以下是几个关键版本：

  • v1.0.9 · 2026-05-06：新增 Docker 部署支持，提供内网离线部署完整方案；
  • v1.0.8 · 2026-04-30：新增法语、德语、俄语国际化支持，覆盖 1000+ 翻译键；
  • v1.0.7 · 2026-04-30：完善日语翻译，优化索引数据源（改用 indices_stats.json）；
  • v1.0.6 · 2026-04-29：新增日语支持，修复 Word 报告语言切换 Bug；
  • v1.0.5 · 2026-04-27：引入三级告警分类系统（severity_level）；
  • v1.0.4 · 2026-04-27：新增 5 个高级分析组件（线程池积压、分片热点、JVM 画像、配置漂移、分片分配）；
  • v1.0.3 · 2026-04-27：引入 6 大维度加权评分体系；
  • v1.0.2 · 2026-04-22：实现报告 SQLite 持久化，支持 Word 报告下载。

完整变更日志见仓库中的 backend/CHANGELOG.md 与 frontend/CHANGELOG.md。

十一、关于团队与开源

ElasticLens 由 上海悦高软件股份有限公司大数据团队 研发并维护。我们长期深耕大数据基础设施与可观测性领域，希望通过开源把内部沉淀的一线运维经验回馈给社区。

我们非常欢迎社区参与：

  • 🐛 提 Issue：报告 Bug、提需求、问问题；
  • 🚀 提 PR：新增检查规则、新增语言、修复 Bug、改进文档；
  • ⭐ 点 Star：是对我们持续投入的最大鼓励；
  • 💬 共建生态：欢迎与可观测性、ES 运维相关项目联动。

十二、结语

Elasticsearch 在搜索、日志、向量检索领域占据了大半江山，但围绕"巡检"和"健康评估"的工具一直比较散乱。ElasticLens 想做的，是把这块拼图补上 —— 用一份开箱即用的开源工具，让每一个 ES 用户都能轻松看清自己集群的"体检报告"。

如果你正在维护 Elasticsearch 集群，或者正在为客户做 ES 相关咨询服务，不妨试一下 ElasticLens：

👉 GitHub 地址：github.com/YogooSoft/E…
👉 当前版本：v1.0.9
👉 协议：MIT License
👉 作者：上海悦高软件股份有限公司 · 大数据团队

如果它帮到了你，请给我们一个 ⭐ Star，让更多 ES 运维同行看到它。

Made with ❤️ by ElasticLens Team

avatar
文章
阅读
粉丝