AlbertoRomaris/incidenthub

# IncidentHub IncidentHub 是一个事件驱动、面向 SRE 的后端平台，可将来自分布式服务的运营信号转化为可执行的操作事件、告警和运行手册。 该项目专注于后端架构、运营推理、异步处理、事件管理和云原生系统设计。 它被有意设计为一个非 CRUD 应用程序。其目的是对真实系统如何产生运营噪音以及后端平台如何接收、处理并最终将这些噪音转换为有用的运营状态进行建模。 ## 当前状态 ### ✅ V1 – 本地信号接收平台 已完成。 V1 构建了 IncidentHub 的基础： - 接收来自外部服务的运营信号 - 验证并持久化信号 - 暴露信号查询接口 - 提供发出信号的演示支付服务 - 使用 PostgreSQL 和 Docker Compose 在本地运行 当前流程： ``` Demo Payment Service ↓ IncidentHub API ↓ PostgreSQL ``` 文档： - [V1 – 本地信号接收](docs/v1-local-signal-ingestion.md) ### ✅ V2 – 异步规则评估与事件生命周期 已完成。 V2 将原始运营信号转化为去重后的事件，并附带证据和生命周期状态。 已实现： - 基于数据库的信号处理任务 - 独立的 IncidentHub Worker 应用程序 - 计划 Worker 轮询 - 使用数据库锁的安全任务声明 - 规则评估 - 事件创建 - 事件去重 - 事件证据 - 事件查询接口 - 事件生命周期：`OPEN → ACKNOWLEDGED → RESOLVED` - 规则查询接口 当前流程： ``` Demo Payment Service ↓ IncidentHub API ↓ PostgreSQL signal processing tasks ↓ IncidentHub Worker ↓ Rule Evaluation ↓ Incidents + Evidence ``` 文档： - [V2 – 异步规则评估与事件生命周期](docs/v2-async-rule-evaluation.md) ### ✅ V3 – 告警、运行手册与运营工作流 已完成。 V3 将 IncidentHub 从事件检测演进为运营响应。 已实现： - 事件时间线事件 - 按事件类型关联运行手册 - 事件开启时创建告警请求 - 基于日志的告警发送器 - 告警传递状态：`PENDING → SENT` - 事件告警接口 - 运营仪表盘摘要接口 - 初始事件运行手册 - 使用多种事件类型进行端到端验证： - `HIGH_LATENCY` - `HIGH_ERROR_RATE` - `TIMEOUT_SPIKE` 当前流程： ``` Demo Payment Service ↓ IncidentHub API ↓ Signal Processing Task ↓ IncidentHub Worker ↓ Rule Evaluation ↓ Incident + Evidence ↓ Timeline + Runbook ↓ Alert Requested ↓ Alert Sent ↓ Dashboard Summary ``` 文档： - [V3 – 告警、运行手册与运营工作流](docs/v3-alerting-runbooks-and-operational-workflows.md) - [运行手册](docs/runbooks) ### ✅ V4 – SRE 指标、SLO 与自观测能力 已完成。 V4 使 IncidentHub 具备内部可观测性。 它增加了内部运营指标、SLO 评估以及兼容 Prometheus 的端点，使平台能够报告自身的健康状况。 已实现： - 内部运营指标模型 - 指标名称、类型和单位 - 信号处理任务指标 - 信号处理成功率 - 信号处理平均延迟 - 最早的待处理任务时间 - 事件状态指标 - 告警传递指标 - 告警传递成功率 - SLO 定义和评估 - JSON 运营指标接口 - JSON SLO 摘要接口 - 兼容 Prometheus 的指标接口 - 低基数指标命名 当前流程： ``` IncidentHub API / Worker ↓ Operational Repositories ↓ Metrics Summary Use Case ↓ Operational Metrics ↓ SLO Evaluations ↓ JSON Metrics + Prometheus Output ``` 关键接口： ``` GET /metrics/operational GET /slo/summary GET /metrics/prometheus ``` 示例 SLO： ``` signal-processing-success-rate >= 99% alert-delivery-success-rate >= 99% pending-task-backlog <= 50 oldest-pending-task-age <= 60 seconds signal-processing-average-latency <= 10000 ms ``` 文档： - [V4 – SRE 指标、SLO 与自观测能力](docs/v4-sre-metrics-slos-self-observability.md) ### ✅ V5 – AWS 云端部署 已完成并验证。 - Terraform 管理的 AWS 基础设施 - 用于 API 和 Worker 镜像的 ECR 仓库 - ECS Fargate API 服务 - ECS Fargate Worker 服务 - 用于公共 API 访问的应用程序负载均衡器 - RDS PostgreSQL 托管数据库 - API 和 Worker 的 CloudWatch 日志组 - CloudWatch 运行时健康告警 - SQS 信号处理队列基础 - SQS 死信队列基础 - SNS 告警基础 - 用于 ECS 任务执行和运行时访问的 IAM 角色 - 手动 Docker 镜像发布至 ECR - 手动 AWS 部署流程 - AWS 部署验证脚本 - 在 AWS 中验证了端到端的事件检测 - 通过部署的 API 暴露运营指标、SLO 和 Prometheus 端点 已验证场景： - 由重复的延迟信号创建的 HIGH_LATENCY 事件 - 由重复的错误信号创建的 HIGH_ERROR_RATE 事件 - 由重复的超时信号创建的 TIMEOUT_SPIKE 事件 - 附加到事件的证据 - 与事件关联的运行手册 - 记录的时间线事件 - 已请求并发送的告警 - 成功更新的指标和 SLO 尚未包含： - 使用 OIDC 的 GitHub Actions CI/CD - 远程 Terraform 状态 - HTTPS 自定义域 - 由 Terraform 管理的 CloudWatch 仪表盘 - SNS 告警发送器实现 文档： - [V5 – AWS 云端部署](docs/v5-aws-cloud-deployment.md) ### ✅ V6 – 交付自动化与高级云运维 已完成并验证。 - 由 Terraform 管理的 CloudWatch 运行时仪表盘 - SNS 告警传递实现 - 已验证的 SNS 电子邮件传递 - 可配置的告警渠道和告警发送器 - 改进的 ECR 发布脚本错误处理 - GitHub Actions CI 工作流 - GitHub Actions OIDC 与 AWS 集成 - GitHub Actions Docker 镜像发布至 ECR - 镜像发布后的 GitHub Actions ECS 重新部署 - 已验证的自动化构建、发布和重新部署流程 已验证流程： - 推送至 main 分支 - 在 GitHub Actions 中进行 Maven 构建 - 在 GitHub Actions 中构建 Docker 镜像 - API 和 Worker 镜像推送至 ECR - ECS API 和 Worker 服务重新部署 - 等待 ECS 服务直至稳定 - 从 Worker 发送 SNS 告警 - 成功接收 SNS 电子邮件 文档： - [V6 – 交付自动化与高级云运维](docs/v6-delivery-automation-and-advanced-cloud-operations.md) ### ✅ V7 – Web 仪表盘 已完成并验证。 - React + TypeScript + Vite web 仪表盘 - 通过 Vite 代理进行真实 API 集成 - 包含实时事件、指标和 SLO 状态的运营仪表盘 - 带有搜索和过滤功能的事件页面 - 包含时间线、证据和告警的事件详情视图 - SLO 和指标页面 - 带有搜索和过滤功能的告警页面 - 仪表盘各部分之间的侧边栏导航 - 新增全局告警接口：`GET /alerts?limit=100` - 使用 `npm run build` 验证了前端构建 - 针对真实 API 和 PostgreSQL 数据验证了端到端本地流程 已验证流程： - 在本地启动 PostgreSQL - 使用 `local` 配置文件启动 API - 使用 `local` 配置文件启动 Worker - 使用 Vite 启动 React UI - 仪表盘从 API 加载真实事件 - 事件页面展示并过滤真实事件 - 事件详情加载了时间线、证据和告警 - SLO 页面加载了运营指标和 SLO 摘要 - 告警页面通过 `/alerts` 加载了全局告警历史 - 相关的告警事件从 UI 中正确打开 - 前端生产构建成功完成 文档： - [V7 – Web 仪表盘](docs/v7-web-dashboard.md) ## 本地快速入门 ### 前置条件 - Java 21 - Maven - Docker Desktop - Node.js 20.19+ 或 22+ - npm - IntelliJ IDEA 或其他 Java IDE - Git ### 1. 启动 PostgreSQL ``` docker compose up -d postgres ``` 本地 PostgreSQL 实例暴露于： ``` localhost:5434 ``` 默认凭据： ``` Database: incidenthub User: incidenthub Password: incidenthub ``` ### 2. 启动 IncidentHub API 运行： ``` com.incidenthub.api.IncidentHubApiApplication ``` 使用 Spring 配置文件： ``` local ``` API 运行于： ``` http://localhost:8080 ``` 健康检查： ``` curl http://localhost:8080/actuator/health ``` ### 3. 启动 IncidentHub Worker 运行： ``` com.incidenthub.worker.IncidentHubWorkerApplication ``` 使用 Spring 配置文件： ``` local ``` Worker 处理待处理的信号任务、评估规则、创建或更新事件、附加证据、记录时间线事件以及发送待处理的告警。 ### 4. 启动演示支付服务 运行： ``` com.incidenthub.demo.payment.DemoPaymentServiceApplication ``` 演示服务运行于： ``` http://localhost:8090 ``` ### 5. 启动 IncidentHub Web 仪表盘 ``` cd incidenthub-ui npm install npm run dev ``` 仪表盘运行于： ``` http://localhost:5173 ``` UI 通过 Vite 代理调用 API： ``` /api/* → http://localhost:8080/* ``` ### 6. 模拟高延迟 ``` curl -X POST http://localhost:8090/simulate/failure-mode \ -H "Content-Type: application/json" \ -d '{ "mode": "HIGH_LATENCY", "latencyMs": 2500, "failureRate": 0.0 }' ``` ### 7. 支付扣款 ``` curl -X POST http://localhost:8090/payments/charge \ -H "Content-Type: application/json" \ -d '{ "customerId": "customer-123", "amount": 49.99, "currency": "EUR", "correlationId": "checkout-req-001" }' ``` ### 8. 查询近期信号 ``` curl http://localhost:8080/signals?limit=10 ``` ### 9. 查询事件 ``` curl http://localhost:8080/incidents?limit=10 ``` ### 10. 查询事件时间线 ``` curl http://localhost:8080/incidents/{incidentId}/timeline ``` ### 11. 查询事件证据 ``` curl http://localhost:8080/incidents/{incidentId}/evidence ``` ### 12. 查询事件告警 ``` curl http://localhost:8080/incidents/{incidentId}/alerts ``` ### 13. 查询全局告警 ``` curl http://localhost:8080/alerts?limit=100 ``` ### 14. 查询仪表盘摘要 ``` curl http://localhost:8080/dashboard/summary ``` ### 15. 查询运营指标 ``` curl http://localhost:8080/metrics/operational ``` ### 16. 查询 SLO 摘要 ``` curl http://localhost:8080/slo/summary ``` ### 17. 查询兼容 Prometheus 的指标 ``` curl http://localhost:8080/metrics/prometheus ``` ### 18. 验证前端构建 ``` cd incidenthub-ui npm run build ``` ## 当前架构 ``` Client / React Web Dashboard ↓ IncidentHub API ↓ PostgreSQL ↓ Signal Processing Tasks ↓ IncidentHub Worker ↓ Rule Evaluation ↓ Incidents + Evidence + Timeline + Alerts ↓ Operational Metrics + SLOs ↓ Web Dashboard Views ``` 启用演示服务后： ``` Client ↓ Demo Payment Service ↓ IncidentHub API ↓ PostgreSQL ↓ Signal Processing Tasks ↓ IncidentHub Worker ↓ Rule Evaluation ↓ Incidents + Evidence + Timeline + Alerts ↓ Operational Metrics + SLOs ↓ React Web Dashboard ``` ## 仓库结构 ``` incidenthub/ ├── incidenthub-core/ ├── incidenthub-infrastructure/ ├── incidenthub-api/ ├── incidenthub-worker/ ├── incidenthub-ui/ ├── demo-services/ │ └── demo-payment-service/ ├── infra/ │ └── aws/ │ └── stack/ ├── docs/ ├── requests/ ├── scripts/ ├── docker-compose.yml ├── docker-compose-app.yml └── pom.xml ``` ## 设计原则 - 架构重于功能数量 - 运营领域建模 - 本地优先开发 - 核心独立于框架 - 基础设施隐藏于端口/适配器之后 - 信号是原始的运营观测数据 - 事件是派生的运营状态 - 运行手册应使事件具有可操作性 - 事件响应应可通过时间线进行审计 - 平台应暴露其自身的运营健康状况 - 指标应使用低基数命名 - 运营数据应可通过 Web 仪表盘进行探索 - 事件应可从告警到证据和时间线进行追踪 - UI 应使用真实的 API 数据，而不是重复后端逻辑 - 系统应能在本地和云端进行端到端演示

标签：Amazon CloudWatch, Amazon SNS, AWS ECS, AWS Fargate, Docker, Docker Compose, EC2, ECS, GitHub Actions, IaC, PostgreSQL, Runbook, Spring Boot, SRE, Terraform, 事件响应平台, 事件驱动架构, 云计算, 信号处理, 偏差过滤, 分布式系统, 后端开发, 告警去重, 告警收敛, 告警系统, 响应大小分析, 安全防御评估, 库, 应急响应, 异步处理, 故障响应, 无服务器, 测试用例, 生命周期管理, 站点可靠性工程, 自动笔记, 自定义请求头, 规则引擎, 请求拦截, 运维平台, 运维自动化