anntmishra/aegis
GitHub: anntmishra/aegis
Aegis 是一个无需 Kubernetes 和云服务的自愈式分布式系统，通过统计异常检测和可解释规则引擎自动发现、诊断并恢复微服务故障。
Stars: 0 | Forks: 0
# Aegis
**一个具备自愈能力的分布式系统，能够检测故障、解释其推理过程并自动恢复 —— 无需 Kubernetes、无需云服务、无需付费 API。**
Aegis 运行三个微服务，通过统计异常检测（EWMA + Z-score）对其进行监控，并使用基于规则的决策引擎进行修复。该引擎会记录其采取行动的*原因*，而不仅仅是做了*什么*。系统内置了混沌工程，因此你可以故意破坏系统，并实时观察其恢复过程。
[](LICENSE)
**实时演示：** _部署后在此处添加你的 `https://aegis..sslip.io` URL —— 请参阅 [托管公开演示](#hosting-a-public-demo)。_
## 核心亮点
- 设计并构建了一个具备自愈能力的分布式系统，该系统利用统计异常检测和基于规则的决策引擎，自主检测、诊断服务故障并从中恢复。
- 实现了可解释性层，每次自动操作都会记录其症状、根本原因、置信度得分和结果 —— 而非黑盒式的盲目重启。
- 构建了混沌工程测试工具（CLI + 仪表盘内控件），用于触发真实的 container 销毁、延迟注入和内存泄漏，从而验证故障条件下的恢复能力。
- 定量衡量系统弹性：平均检测时间（Mean Time To Detect）和平均恢复时间（Mean Time To Recover），这些指标均根据真实的事件生命周期计算得出，而非静态的占位符。
- 强化并发布了面向公众的演示模式：限速的混沌触发器、允许的操作白名单以及由管理员 token 控制的手动覆盖机制，可安全暴露在公共互联网上。
- 基于 shadcn/ui 重建了仪表盘，采用完全可访问的单色设计系统（明暗主题），将颜色专门保留用于标识真实的严重/故障状态。
## 目录
- [架构](#architecture)
- [工作原理](#how-it-works)
- [快速开始](#quick-start)
- [混沌工程](#chaos-engineering)
- [API 参考](#api-reference)
- [评估指标](#evaluation-metrics)
- [技术栈](#tech-stack)
- [项目结构](#project-structure)
- [托管公开演示](#hosting-a-public-demo)
- [路线图](#roadmap)
- [许可协议](#license)
## 架构
```
flowchart LR
C[Chaos Engine / Dashboard button] --> S[Services A · B · C]
S -- metrics --> M[Monitor
EWMA + Z-score anomaly detection] M -- anomalies --> H[Healer
rule-based decision engine] H -- action --> S H -- explanation --> L[(healing-log.json)] H -- "healing started" --> E[Evaluator
MTTD / MTTR] M & H & E --> D[Dashboard] ``` 五个独立的服务，每个服务各司其职： | 服务 | 职责 | |---|---| | **Service A / B / C** | 可注入故障的 Express 微服务（用户/订单/库存） | | **Monitor** | 轮询服务，维护滚动 EWMA + 方差基线，标记异常 | | **Healer** | 将异常与规则进行匹配，评估置信度，执行操作，并记录推理过程 | | **Evaluator** | 追踪事件生命周期（已检测 → 正在修复 → 已解决）以计算 MTTD/MTTR | | **Dashboard** | React + shadcn/ui，通过轮询实现实时更新，单色设计，仅用一种保留颜色标识真实故障 | ## 工作原理 **1. 监控** —— Monitor 每 5 秒轮询一次每个服务的延迟（P50/P95/P99）、错误率、内存和正常运行时间。 **2. 异常检测** —— 使用 Z-score 阈值（利用 `Welford's algorithm` 进行在线方差计算），将每个指标与各服务独立的 EWMA 基线进行比较，并按严重程度（`low` / `medium` / `high` / `critical`）进行分类。 **3. 决策** —— Healer 的规则引擎将异常模式（类型 + 严重程度 + 数量）匹配到相应的修复操作和置信度得分，并设有冷却时间以防止“重启风暴”。 **4. 操作** —— 通过 `dockerode` 针对真实的 Docker API 执行：重启 container，或在严重程度较低的情况下执行路由/缩放/限流响应。 **5. 可解释性** —— 每次操作都会作为结构化记录写入 `logs/healing-log.json`： ``` { "time": "12:41:02", "service": "service-a", "symptoms": ["latency spike", "error burst"], "root_cause": "memory exhaustion", "action": "restart", "confidence": 0.87 } ``` **6. 评估** —— Healer 在开始处理事件的瞬间就会通知 Evaluator，因此平均检测时间和平均恢复时间是根据真实的时间戳衡量的，而不是事后估算的。 ## 快速开始 **前置条件：** Docker 和 Docker Compose，Node.js 20+ ``` # Backend：services A/B/C、monitor、healer、evaluator docker-compose up --build # Dashboard，在单独的终端中 cd dashboard && npm install && npm run dev ``` 打开终端输出的 Vite URL（通常是 `http://localhost:5173`）。点击 **Inject Chaos** 来销毁 container、增加延迟、泄漏内存，或触发全面的级联故障 —— 然后观察仪表盘如何检测它、解释根本原因并完成修复。 | 服务 | 端口 | |---|---| | Service A (User) | 3001 | | Service B (Order) | 3002 | | Service C (Inventory) | 3003 | | Monitor | 4000 | | Healer | 4001 | | Evaluator | 4002 | | Dashboard (dev) | 5173 | ## 混沌工程 在仪表盘中操作（限速为每 45 秒 1 个场景，适合共享的公开演示）： - **销毁服务 (Kill a Service)** —— 对随机 container 执行 `docker kill` - **注入延迟** —— 真实增加的响应延迟 - **内存泄漏** —— 真实且无限制的堆内存增长，直到触发阈值 - **级联故障** —— 延迟 → 错误激增 → 销毁 container，在所有三个服务之间形成连锁反应 或通过 CLI 执行： ``` chmod +x chaos/inject-failures.sh ./chaos/inject-failures.sh # interactive menu ./chaos/inject-failures.sh kill aegis-service-a ./chaos/inject-failures.sh latency aegis-service-b 2000 ./chaos/inject-failures.sh scenario cascade ``` ## API 参考 **Monitor** (`:4000`) - `GET /status` —— 整体系统及各服务的健康状态和指标 - `GET /anomalies` —— 当前检测到的异常 - `GET /metrics/:serviceName` —— 指标历史记录 - `GET /baselines/:serviceName` —— EWMA 基线 **Healer** (`:4001`) - `GET /status` —— 决策统计信息和成功率 - `GET /decisions/:serviceName` —— 决策历史 - `GET /healing-log` —— 最近的日志可解释性条目 - `POST /heal/:serviceName` —— 手动覆盖（当 `PUBLIC_DEMO=true` 时需要 `X-Admin-Token`） - `POST /chaos/trigger` —— 白名单允许且经过限速的混沌操作（`{ "scenario": "kill-random" | "latency-random" | "memory-leak-random" | "cascade" }`） - `GET /containers` —— container 状态 **Evaluator** (`:4002`) - `GET /metrics` —— 当前的 MTTD / MTTR / 成功率 - `GET /timeline` —— 按时间分桶的指标 - `GET /services` —— 各服务的弹性指标 ## 评估指标 Evaluator 使用 Healer 在采取行动那一刻推送的真实时间戳，追踪每个事件的完整生命周期 —— `detected → healing started → resolved`，因此： - **MTTD** —— 平均检测时间（检测到异常 → Healer 开始采取行动） - **MTTR** —— 平均恢复时间（Healer 开始采取行动 → 确认服务恢复正常） - **成功率** —— 成功解决与失败恢复的比率 - **误报** —— 在 Healer 采取行动之前就自行解决的事件 这些都不是占位符 —— 触发任意混沌场景，就能看到这些数字发生变化。 ## 技术栈 | 层级 | 技术 | |---|---| | 语言 | TypeScript (严格模式), Node.js | | 服务 | Express | | 容器 | Docker, Docker Compose | | 异常检测 | 自定义 EWMA + Z-score，无外部监控技术栈 | | 仪表盘 | React, Vite, shadcn/ui, Radix, Tailwind CSS, Recharts | | 混沌测试 | Bash + 限速的 HTTP API | | 反向代理（公开演示）| Caddy（自动 HTTPS）| | 日志记录 | 结构化 JSON，基于文件 | ## 项目结构 ``` aegis/ ├── services/ # Service A/B/C — fault-injectable microservices ├── src/ │ ├── shared/ # Types, config, logger │ ├── monitor/ # Metrics collector + anomaly detector │ ├── healer/ # Decision engine, actions, chaos API │ └── evaluator/ # Incident tracking, MTTD/MTTR ├── dashboard/ # React + shadcn/ui dashboard ├── chaos/ # Chaos engineering CLI ├── router/ # Routing configuration ├── deploy/ # Public-demo deployment runbook ├── logs/ # Explainability log (healing-log.json) ├── Caddyfile / docker-compose.prod.yml # Public demo hosting └── docker-compose.yml ``` ## 托管公开演示 Aegis 默认在本地运行。[`deploy/runbook.md`](deploy/runbook.md) 详细介绍了如何将一个经过安全加固的实时版本部署到互联网上 —— 只需一台小型的 Azure 虚拟机（学生额度或标准的 12 个月免费套餐均可，无需其他云服务账户）+ `sslip.io`（无需购买域名即可获得真实的 HTTPS 主机名），并由 Caddy 提供前端以实现自动 TLS。公开版本具有以下特点： - 在管理员 token 的控制下启用手动 `/heal` 覆盖机制 - 仅向访问者暴露经过限速的、白名单允许的混沌触发端点 - 运行真实的 Docker 后端修复操作 —— 而非模拟 ## 路线图 这是一个作品集项目的真实状态，并非已完成的最终产品： - [ ] `scale_up` / `scale_down` / `remove_from_routing` 目前仅记录意图，尚未真正重新配置实际基础设施 —— 只有 `restart` 会执行真实的 Docker 操作 - [ ] `router/routing-config.json` 已定义，但尚未被任何服务读取 - [ ] 决策引擎和异常检测器目前尚无自动化测试套件，尽管两者都属于非常适合单元测试的纯函数确定逻辑 - [ ] 指标/事件存储在内存中 —— 重启 Monitor/Healer/Evaluator 会清除学习到的基线和历史记录（磁盘上的可解释性日志是唯一能保存下来的数据） ## 许可协议 MIT
Live data, not a mockup — one service degraded from a real memory-exhaustion anomaly, MTTD/MTTR computed from an actual incident just above.
Light mode
EWMA + Z-score anomaly detection] M -- anomalies --> H[Healer
rule-based decision engine] H -- action --> S H -- explanation --> L[(healing-log.json)] H -- "healing started" --> E[Evaluator
MTTD / MTTR] M & H & E --> D[Dashboard] ``` 五个独立的服务，每个服务各司其职： | 服务 | 职责 | |---|---| | **Service A / B / C** | 可注入故障的 Express 微服务（用户/订单/库存） | | **Monitor** | 轮询服务，维护滚动 EWMA + 方差基线，标记异常 | | **Healer** | 将异常与规则进行匹配，评估置信度，执行操作，并记录推理过程 | | **Evaluator** | 追踪事件生命周期（已检测 → 正在修复 → 已解决）以计算 MTTD/MTTR | | **Dashboard** | React + shadcn/ui，通过轮询实现实时更新，单色设计，仅用一种保留颜色标识真实故障 | ## 工作原理 **1. 监控** —— Monitor 每 5 秒轮询一次每个服务的延迟（P50/P95/P99）、错误率、内存和正常运行时间。 **2. 异常检测** —— 使用 Z-score 阈值（利用 `Welford's algorithm` 进行在线方差计算），将每个指标与各服务独立的 EWMA 基线进行比较，并按严重程度（`low` / `medium` / `high` / `critical`）进行分类。 **3. 决策** —— Healer 的规则引擎将异常模式（类型 + 严重程度 + 数量）匹配到相应的修复操作和置信度得分，并设有冷却时间以防止“重启风暴”。 **4. 操作** —— 通过 `dockerode` 针对真实的 Docker API 执行：重启 container，或在严重程度较低的情况下执行路由/缩放/限流响应。 **5. 可解释性** —— 每次操作都会作为结构化记录写入 `logs/healing-log.json`： ``` { "time": "12:41:02", "service": "service-a", "symptoms": ["latency spike", "error burst"], "root_cause": "memory exhaustion", "action": "restart", "confidence": 0.87 } ``` **6. 评估** —— Healer 在开始处理事件的瞬间就会通知 Evaluator，因此平均检测时间和平均恢复时间是根据真实的时间戳衡量的，而不是事后估算的。 ## 快速开始 **前置条件：** Docker 和 Docker Compose，Node.js 20+ ``` # Backend：services A/B/C、monitor、healer、evaluator docker-compose up --build # Dashboard，在单独的终端中 cd dashboard && npm install && npm run dev ``` 打开终端输出的 Vite URL（通常是 `http://localhost:5173`）。点击 **Inject Chaos** 来销毁 container、增加延迟、泄漏内存，或触发全面的级联故障 —— 然后观察仪表盘如何检测它、解释根本原因并完成修复。 | 服务 | 端口 | |---|---| | Service A (User) | 3001 | | Service B (Order) | 3002 | | Service C (Inventory) | 3003 | | Monitor | 4000 | | Healer | 4001 | | Evaluator | 4002 | | Dashboard (dev) | 5173 | ## 混沌工程 在仪表盘中操作（限速为每 45 秒 1 个场景，适合共享的公开演示）： - **销毁服务 (Kill a Service)** —— 对随机 container 执行 `docker kill` - **注入延迟** —— 真实增加的响应延迟 - **内存泄漏** —— 真实且无限制的堆内存增长，直到触发阈值 - **级联故障** —— 延迟 → 错误激增 → 销毁 container，在所有三个服务之间形成连锁反应 或通过 CLI 执行： ``` chmod +x chaos/inject-failures.sh ./chaos/inject-failures.sh # interactive menu ./chaos/inject-failures.sh kill aegis-service-a ./chaos/inject-failures.sh latency aegis-service-b 2000 ./chaos/inject-failures.sh scenario cascade ``` ## API 参考 **Monitor** (`:4000`) - `GET /status` —— 整体系统及各服务的健康状态和指标 - `GET /anomalies` —— 当前检测到的异常 - `GET /metrics/:serviceName` —— 指标历史记录 - `GET /baselines/:serviceName` —— EWMA 基线 **Healer** (`:4001`) - `GET /status` —— 决策统计信息和成功率 - `GET /decisions/:serviceName` —— 决策历史 - `GET /healing-log` —— 最近的日志可解释性条目 - `POST /heal/:serviceName` —— 手动覆盖（当 `PUBLIC_DEMO=true` 时需要 `X-Admin-Token`） - `POST /chaos/trigger` —— 白名单允许且经过限速的混沌操作（`{ "scenario": "kill-random" | "latency-random" | "memory-leak-random" | "cascade" }`） - `GET /containers` —— container 状态 **Evaluator** (`:4002`) - `GET /metrics` —— 当前的 MTTD / MTTR / 成功率 - `GET /timeline` —— 按时间分桶的指标 - `GET /services` —— 各服务的弹性指标 ## 评估指标 Evaluator 使用 Healer 在采取行动那一刻推送的真实时间戳，追踪每个事件的完整生命周期 —— `detected → healing started → resolved`，因此： - **MTTD** —— 平均检测时间（检测到异常 → Healer 开始采取行动） - **MTTR** —— 平均恢复时间（Healer 开始采取行动 → 确认服务恢复正常） - **成功率** —— 成功解决与失败恢复的比率 - **误报** —— 在 Healer 采取行动之前就自行解决的事件 这些都不是占位符 —— 触发任意混沌场景，就能看到这些数字发生变化。 ## 技术栈 | 层级 | 技术 | |---|---| | 语言 | TypeScript (严格模式), Node.js | | 服务 | Express | | 容器 | Docker, Docker Compose | | 异常检测 | 自定义 EWMA + Z-score，无外部监控技术栈 | | 仪表盘 | React, Vite, shadcn/ui, Radix, Tailwind CSS, Recharts | | 混沌测试 | Bash + 限速的 HTTP API | | 反向代理（公开演示）| Caddy（自动 HTTPS）| | 日志记录 | 结构化 JSON，基于文件 | ## 项目结构 ``` aegis/ ├── services/ # Service A/B/C — fault-injectable microservices ├── src/ │ ├── shared/ # Types, config, logger │ ├── monitor/ # Metrics collector + anomaly detector │ ├── healer/ # Decision engine, actions, chaos API │ └── evaluator/ # Incident tracking, MTTD/MTTR ├── dashboard/ # React + shadcn/ui dashboard ├── chaos/ # Chaos engineering CLI ├── router/ # Routing configuration ├── deploy/ # Public-demo deployment runbook ├── logs/ # Explainability log (healing-log.json) ├── Caddyfile / docker-compose.prod.yml # Public demo hosting └── docker-compose.yml ``` ## 托管公开演示 Aegis 默认在本地运行。[`deploy/runbook.md`](deploy/runbook.md) 详细介绍了如何将一个经过安全加固的实时版本部署到互联网上 —— 只需一台小型的 Azure 虚拟机（学生额度或标准的 12 个月免费套餐均可，无需其他云服务账户）+ `sslip.io`（无需购买域名即可获得真实的 HTTPS 主机名），并由 Caddy 提供前端以实现自动 TLS。公开版本具有以下特点： - 在管理员 token 的控制下启用手动 `/heal` 覆盖机制 - 仅向访问者暴露经过限速的、白名单允许的混沌触发端点 - 运行真实的 Docker 后端修复操作 —— 而非模拟 ## 路线图 这是一个作品集项目的真实状态，并非已完成的最终产品： - [ ] `scale_up` / `scale_down` / `remove_from_routing` 目前仅记录意图，尚未真正重新配置实际基础设施 —— 只有 `restart` 会执行真实的 Docker 操作 - [ ] `router/routing-config.json` 已定义，但尚未被任何服务读取 - [ ] 决策引擎和异常检测器目前尚无自动化测试套件，尽管两者都属于非常适合单元测试的纯函数确定逻辑 - [ ] 指标/事件存储在内存中 —— 重启 Monitor/Healer/Evaluator 会清除学习到的基线和历史记录（磁盘上的可解释性日志是唯一能保存下来的数据） ## 许可协议 MIT
标签：Docker Compose, MITM代理, React, Syscalls, TypeScript, 分布式系统, 响应大小分析, 安全插件, 应用安全, 异常检测, 混沌工程, 版权保护, 自动化攻击, 自愈系统, 请求拦截