jaya6400/openmetadata-incident-bot

# OM Incident Bot OM Incident Bot 是一个构建在 OpenMetadata 之上的 AI 辅助事件响应层。它将数据质量故障转化为感知负责人的 Slack 告警、基于血缘的影响上下文，以及用于更快分类的清晰事件仪表盘。 ## 1. 关于本项目 数据质量事件通常会在分析、数据工程和业务团队中引发连锁反应。仅仅一个失败的测试本身并不能提供足够的信息。团队仍然需要回答： - 具体是什么失败了？ - 谁负责它？ - 哪些下游资产受到了影响？ - 应该优先处理什么？ OM Incident Bot 通过将 OpenMetadata 作为上下文系统，并将其与 Slack 和 AI 结合以创建实用的事件响应工作流来解决这一问题。 该项目包含两个主要部分： - 一个用于事件分类、血缘检查和负责人可见性的 React 仪表盘 - 一个接收 OpenMetadata 事件、使用元数据上下文丰富事件并发送 Slack 告警的 Express 后端 ## 2. 在线链接 - 前端: [网站链接](https://openmetadata-incident-bot-jd.vercel.app/) - 演示视频: [视频链接](https://youtu.be/M84QhdeTKWc?si=0faRELARzTOCbNHU) ## 3. 解决的问题 该项目解决了一个核心问题： **OpenMetadata 可以检测数据质量问题，但团队在做出响应之前，仍需耗费时间手动收集负责人、血缘和操作上下文。** OM Incident Bot 通过以下方式缩小了这一差距： - 接收来自 OpenMetadata 的测试用例失败事件 - 识别表负责人 - 获取血缘以了解爆炸半径 - 生成简短的 AI 摘要进行分类 - 发送富文本 Slack 告警 - 在响应式 UI 中展示事件以便后续跟进 简而言之，它将失败的数据质量信号转化为可操作的事件工作流。 ## 4. 使用的技术栈 ### 前端 - React 19 - TypeScript - Vite - Framer Motion - CSS ### 后端 - Node.js - Express - TypeScript - Axios - body-parser - cors ### 集成 - OpenMetadata APIs - Slack API - Google Gemini API ## 5. 项目架构 ## 高层流程 1. OpenMetadata 发出测试用例事件。 2. 后端接收 webhook。 3. 后端从 OpenMetadata 获取元数据上下文。 4. 解析血缘和所有权。 5. Gemini 生成简短的分类摘要。 6. 将 Slack 告警发送到正确的频道，并附上负责人上下文。 7. 前端仪表盘展示事件、血缘和负责人。 8. 用户还可以将最近的 OpenMetadata 事件/结果记录拉取到仪表盘中。 ## 仓库结构 ``` openmetadata-incident-bot/ ├─ client/ │ ├─ public/ │ ├─ src/ │ │ ├─ components/ │ │ ├─ styles/ │ │ ├─ types/ │ │ ├─ utils/ │ │ └─ App.tsx │ └─ package.json ├─ server/ │ ├─ src/ │ │ ├─ controllers/ │ │ ├─ models/ │ │ ├─ routes/ │ │ ├─ services/ │ │ └─ index.ts │ └─ package.json └─ README.md ``` 后端遵循简洁的受 MVC 启发的结构： - `routes/` 定义 API 端点 - `controllers/` 处理请求/响应逻辑 - `models/` 管理事件数据结构和存储逻辑 - `services/` 包含 OpenMetadata、Slack 和 Gemini 的集成逻辑 这使得项目模块化、易读且更易于维护。 ## 前端架构 前端是一个 Vite + React 仪表盘，包含三个主要视图： - Incident Feed - Lineage - Owners 该 UI 为操作使用进行了优化： - 粘性顶部栏操作 - 移动端侧边栏菜单 - 按状态过滤的事件流 - 负责人和血缘上下文 - 适用于桌面和移动端的响应式布局 ## 后端架构 后端暴露 REST 端点和集成处理器： - `POST /api/webhook` - `POST /api/slack/commands` - `GET /api/incidents` - `GET /api/om-incidents` - `GET /api/lineage` - `GET /api/owners` - `GET /health` 后端负责： - 接收 webhook 事件 - 使用 OpenMetadata 数据丰富事件 - 发送 Slack 告警 - 生成 Gemini 摘要 - 将规范化的事件数据提供给前端 ## OpenMetadata 认证与 API 使用 本项目通过以下方式使用 OpenMetadata 个人访问令牌： - `OPMD_JWT_TOKEN` 该令牌从后端在 Authorization 头中发送： ``` Authorization: Bearer ``` ### 使用的 OpenMetadata APIs #### 1. 测试用例事件状态 API 用于从 OpenMetadata 进行基于拉取的事件/结果同步： ``` GET /api/v1/dataQuality/testCases/testCaseIncidentStatus ``` 目的： - 获取最近的 OpenMetadata 事件状态记录 - 在仪表盘中显示失败和已解决/通过的记录 #### 2. 测试用例详情 API 用于使用负责人和实体详情丰富 webhook 事件： ``` GET /api/v1/testCases/name/:fqn?fields=owner,testDefinition,entityLink ``` 目的： - 解析测试用例的负责人详情 - 将失败的测试用例映射回其元数据上下文 #### 3. 表详情 API 在多处使用： ``` GET /api/v1/tables/name/:tableFqn?fields=owners GET /api/v1/tables/name/:tableFqn?fields=owners,tags,description,testSuite ``` 目的： - 在测试用例查找不可用时作为后备负责人查找方案 - Slack 斜杠命令响应 - 表描述、标签和测试套件丰富 #### 4. 表血缘 API 用于影响分析： ``` GET /api/v1/lineage/table/name/:tableFqn ``` 目的： - 查找上游依赖 - 查找受影响的下游表 - 支持仪表盘血缘视图 - 支持 Slack 血缘命令 ## PAT 如何在系统中流转 1. 您在 OpenMetadata 中生成一个 PAT。 2. 该 PAT 作为 `OPMD_JWT_TOKEN` 存储在后端环境变量中。 3. 后端使用 Axios 调用 OpenMetadata APIs。 4. 前端从不直接存储或暴露 PAT。 5. 前端仅通过 `VITE_API_URL` 与您的后端通信。 这使得 OpenMetadata 的访问控制在服务器端进行。 ## 6. 本地设置 ### 克隆仓库 ``` git clone https://github.com/jaya6400/openmetadata-incident-bot.git cd openmetadata-incident-bot ``` ### 启动后端 ``` cd server npm install npm run dev ``` ### 启动前端 ``` cd client npm install npm run dev ``` ### 后端环境变量 创建 `server/.env`： ``` PORT=3001 OPMD_URL=https://sandbox.open-metadata.org OPMD_JWT_TOKEN=YOUR_OPENMETADATA_PAT OWNER_EMAIL=owner@example.com SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN SLACK_CHANNEL_ID=YOUR_SLACK_CHANNEL_ID GEMINI_API_KEY=YOUR_GEMINI_API_KEY ``` ### 前端环境变量 创建 `client/.env`： ``` VITE_API_URL=http://localhost:3001 VITE_OM_URL=https://sandbox.open-metadata.org ``` ### 常用的本地 URL - 前端：`http://localhost:5173` - 后端：`http://localhost:3001` - 健康检查：`http://localhost:3001/health` ## 7. 部署 ## 前端部署 前端旨在部署在 Vercel 上。 步骤： 1. 将 `client` 应用导入 Vercel。 2. 将 `VITE_API_URL` 设置为您部署的后端 URL。 3. 如有需要，设置 `VITE_OM_URL`。 4. 部署并将最终链接添加到 README 中。 前端链接： `ADD_VERCEL_LINK_HERE` ## 后端部署 后端部署在 Railway 托管平台上。 必需的环境变量： - `PORT` - `OPMD_URL` - `OPMD_JWT_TOKEN` - `OWNER_EMAIL` - `SLACK_BOT_TOKEN` - `SLACK_CHANNEL_ID` - `GEMINI_API_KEY` 重要的部署说明： - 仅将 OpenMetadata PAT 保留在后端 - 切勿在前端暴露 `OPMD_JWT_TOKEN` ## 8. 截图 ### 前端 UI - Incident Feed 桌面视图 - 移动端响应式视图 - Lineage 页面 - Owners 页面 ### Slack App - Slack 事件告警消息 - Slack `/om-status` 命令输出 - Slack `/om-lineage` 命令输出 - Slack `/om-owner` 命令输出 ## 9. 使用的编码助手： - Claude Code, VS code copilot ## 10. 作者 **Jaya Dubey** - 作品集：[链接](https://jaya-dubey-resume.netlify.app/) - LinkedIn：[链接](https://www.linkedin.com/in/jaya6400)

为 [OpenMetadata Hackathon](https://www.wemakedevs.org/hackathons/openmetadata) 而建。

标签：AI摘要, API集成, Express, GNU通用公共许可证, MITM代理, Node.js, OpenMetadata, React, Slack集成, Syscalls, TypeScript, Vite, 事故管理, 人工智能辅助, 仪表盘, 可观测性, 告警通知, 安全插件, 影响分析, 数据工程, 数据治理, 数据血缘, 数据质量, 自动化攻击