AnirudhS3110/Sentinel-AI
GitHub: AnirudhS3110/Sentinel-AI
一个基于多智能体协作的生产级 AI 事件响应平台，通过 LangGraph 编排六个专职智能体自动完成基础设施事件的根因分析、修复与复盘。
Stars: 0 | Forks: 0
# SentinelAI
面向生产环境的 AI 驱动的事件编排系统。提交包含日志的事件；六个专门的 agent 负责规划、分类、分析、验证、修复和报告——并将实时进度流式传输到指挥中心仪表板。
技术栈：Next.js, NestJS, TypeScript, PostgreSQL, Prisma, Redis, BullMQ, Socket.IO, LangGraph, LangChain, Google Gemini, Tailwind CSS, Framer Motion, Recharts, Firebase Auth, Railway, Vercel, Neon, Upstash
**在线演示：** [sentinel-ai-v1.vercel.app](https://sentinel-ai-v1.vercel.app/)
## 目录
- [概述](#overview)
- [架构](#architecture)
- [Monorepo 结构](#monorepo-structure)
- [AI agent](#ai-agents)
- [工作流 pipeline](#workflow-pipeline)
- [技术栈](#tech-stack)
- [数据模型](#data-model)
- [实时更新](#real-time-updates)
- [身份验证](#authentication)
- [前置条件](#prerequisites)
- [本地设置](#local-setup)
- [环境变量](#environment-variables)
- [脚本](#scripts)
- [部署](#deployment)
- [应用路由](#app-routes)
## 概述
SentinelAI 实现了事件生命周期的自动化：
1. 用户通过 Web UI 创建事件（标题、描述、原始日志）。
2. **API** 持久化事件，并将首个任务加入 **BullMQ** (Redis) 队列。
3. **worker** 按顺序运行六个由 **Gemini** 驱动的 agent，更新 PostgreSQL 并发布事件。
4. **API** 通过 **Socket.IO** 转发事件，以便仪表板实时更新。
编排是**队列驱动**的 (BullMQ)。**LangGraph** 仅用于验证路由（重试分析 vs. 继续 vs. 失败）。
## 架构
```
flowchart TB
subgraph Client["Browser (Next.js)"]
UI[Dashboard / Incidents]
REST[REST client]
SIO[Socket.IO client]
end
subgraph API["apps/api — NestJS"]
HTTP[REST + Auth]
GW[IncidentsGateway]
SUB[Redis subscriber]
PROD[Queue producer]
end
subgraph Worker["apps/worker — NestJS"]
PROC[BullMQ processors ×6]
AGT[Gemini agents ×6]
LG[LangGraph router]
PUB[Redis publisher]
end
subgraph Data["Infrastructure"]
PG[(PostgreSQL)]
RD[(Redis)]
end
UI --> REST --> HTTP
UI --> SIO --> GW
HTTP --> PG
PROD --> RD
RD --> PROC
PROC --> AGT
AGT --> LG
PROC --> PG
PROC --> PUB --> RD --> SUB --> GW
```
| 服务 | 端口 (本地) | 角色 |
|---------|----------------|------|
| **web** | `3000` | Next.js UI；将 `/backend/*` 代理到 API |
| **api** | `3001` | REST API, Firebase auth, BullMQ **producer**, Socket.IO |
| **worker** | — | BullMQ **consumer**, Gemini LLM 调用, 工作流路由 |
本地运行必须同时启动这三个进程（或在生产环境中单独部署），才能实现端到端的编排。
## Monorepo 结构
```
sentinel-ai/
├── apps/
│ ├── web/ # Next.js 16 dashboard & marketing
│ ├── api/ # NestJS API + WebSockets + queue producer
│ └── worker/ # NestJS worker + agents + queue consumers
├── packages/
│ └── shared/ # Enums, Zod schemas, queue names, events, prompts
├── railway.toml # Railway build/start for API
├── DEPLOYMENT.md # Production deploy checklist
└── package.json # npm workspaces root
```
| 包 | npm 名称 | 描述 |
|---------|----------|-------------|
| `apps/web` | `web` | React 19, TanStack Query, Firebase client, Recharts |
| `apps/api` | `api` | Prisma, BullMQ producer, Firebase Admin, Socket.IO |
| `apps/worker` | `worker` | LangChain + Gemini, LangGraph, BullMQ consumer |
| `packages/shared` | `@sentinel/shared` | 共享类型、常量、agent 输出 schema |
## AI agent
六个 agent 在固定的 pipeline 中运行。每个 agent 都通过 LangChain 使用 **Google Gemini**（默认为 `gemini-2.5-flash-lite`），并在 `packages/shared` 中定义了 **Zod 校验的 JSON** 输出。
| # | Agent | 队列 | 目的 | 关键输出 |
|---|--------|-------|---------|------------|
| 1 | **Planner** | `planner` | 根据事件上下文和日志构建调查计划 | `steps`, `focusAreas`, `estimatedDurationMinutes` |
| 2 | **Classification** | `classification` | 分配严重性、类别和事件类型 | `severity`, `category`, `incidentType`, `confidence` |
| 3 | **Analysis** | `analysis` | 带有证据的根本原因分析 | `rootCause`, `affectedServices`, `evidence`, `confidence` |
| 4 | **Validation** | `validation` | 检查分析的安全性和正确性 | `valid`, `issues`, `safetyScore`, `requiresRetry` |
| 5 | **Remediation** | `remediation` | 提出修复步骤和回滚计划 | `steps`, `rollbackPlan`, `requiresHumanApproval` |
| 6 | **Report** | `report-generation` | 编写最终的复盘报告 | `summary`, `rootCause`, `remediation`, `timeline` |
**实现路径**
| Agent | Worker 源码 |
|-------|----------------|
| Planner | `apps/worker/src/agents/planner/planner.agent.ts` |
| Classification | `apps/worker/src/agents/classification/classification.agent.ts` |
| Analysis | `apps/worker/src/agents/analysis/analysis.agent.ts` |
| Validation | `apps/worker/src/agents/validation/validation.agent.ts` |
| Remediation | `apps/worker/src/agents/remediation/remediation.agent.ts` |
| Report | `apps/worker/src/agents/report/report.agent.ts` |
**LLM 层：** `apps/worker/src/common/llm.service.ts` — 结构化 JSON schema → JSON 模式 → 手动提取兜底。
**Prompt 与 schema：** `packages/shared/src/llm/agent-prompts.ts`, `packages/shared/src/schemas/agent-outputs.ts`
## 工作流 pipeline
### 阶段
| 阶段 | `IncidentStatus` | 设置者 |
|-------|------------------|--------|
| 规划 | `PLANNING` | Planner |
| 分类 | `CLASSIFICATION` | Classification |
| 分析 | `ROOT_CAUSE_ANALYSIS` | Analysis |
| 验证 | `VALIDATION` | Validation |
| 修复 | `REMEDIATION` | Remediation |
| 人工审批 | `HUMAN_APPROVAL` | Remediation（目前会自动推进） |
| 报告 | `REPORT_GENERATION` | Report agent |
| 完成 | `RESOLVED` | 报告已存储 |
| 失败 | `FAILED` | Agent 错误或验证耗尽 |
### 控制流
```
POST /incidents (API)
→ enqueue planner
→ Planner → Classification → Analysis → Validation
↑_________________________| (retry, max 3)
→ Remediation → Report → RESOLVED
```
- **BullMQ** 链式任务：每个处理器完成后，会将下一个任务加入队列 (`apps/worker/src/common/queue-dispatcher.service.ts`)。
- **API** 仅将第一个任务加入队列 (`apps/api/src/queues/queue-producer.service.ts`)。
- **LangGraph** (`apps/worker/src/workflows/workflow-router.service.ts`) 在验证后做出决定：
- `retry_analysis` — 重新运行分析（最多 `MAX_VALIDATION_RETRIES` 次，默认为 3 次）
- `remediation` — 继续 pipeline
- `failed` — 标记事件为失败
验证后规则还会在 `safetyScore < 0.5` 或分析 `confidence < 0.4` 时强制重试。
## 技术栈
| 层 | 技术 |
|-------|----------------|
| **Frontend** | Next.js 16, React 19, Tailwind CSS 4, TanStack Query, Framer Motion, Socket.IO client, Recharts, XYFlow |
| **API** | NestJS 11, Prisma 7, PostgreSQL, BullMQ, Socket.IO, Firebase Admin |
| **Worker** | NestJS 11, BullMQ, LangChain, `@langchain/google-genai`, LangGraph, Zod |
| **Shared** | TypeScript, Zod 4, 共享枚举和事件类型 |
| **Infra** | PostgreSQL, Redis（队列 + pub/sub） |
| **AI** | Google Gemini API |
| **Auth** | Firebase Authentication |
## 数据模型
Prisma schema：`apps/api/prisma/schema.prisma`
| 模型 | 目的 |
|-------|---------|
| `User` | 关联到 Firebase UID |
| `Incident` | 标题、日志、严重性、类别、状态 |
| `WorkflowExecution` | 单个事件的运行，`currentStage`，`retryCount` |
| `AgentExecution` | 单个 agent 的输入/输出、持续时间、状态 |
| `IncidentReport` | 最终生成的报告 |
## 实时更新
1. Worker/API 将 `WorkflowEventPayload` 发布到 Redis 频道 `sentinel:workflow:events`。
2. API 的 `RedisSubscriberService` 接收事件，并通过 Socket.IO 广播。
3. Web 客户端连接到命名空间 `/incidents`，加入房间 `incident:{id}`，并监听 `workflow.event`。
| 组件 | 路径 |
|-----------|------|
| 事件类型 | `packages/shared/src/events/workflow-events.ts` |
| Gateway | `apps/api/src/websocket/incidents.gateway.ts` |
| Client hook | `apps/web/hooks/use-workflow-socket.ts` |
## 身份验证
- **生产环境：** 在 `Authorization: Bearer` 头中携带 Firebase ID token；API 使用 Firebase Admin 进行验证，并将 `User` upsert 到 PostgreSQL 中。
- **本地开发（无 Firebase）：** Web 使用开发专用的 bearer token；API 在未验证的情况下解码 JWT payload (`apps/web/lib/dev-auth.ts`)。
在客户端配置 Firebase Web 密钥 (`NEXT_PUBLIC_FIREBASE_*`)，并在 API 上配置 Admin 凭据 (`FIREBASE_*`)。
## 前置条件
- **Node.js** 20+（推荐 22）
- **npm** 10+
- **PostgreSQL** 14+
- **Redis** 6+
- **Google Gemini API key** (`GEMINI_API_KEY`) — worker 必需
- **Firebase project**（使用 dev-auth 绕过的本地开发可选）
## 本地设置
### 1. 克隆并安装
```
git clone https://github.com/AnirudhS3110/Sentinel-AI.git
cd sentinel-ai # or your clone directory name
npm install
```
### 2. 配置环境
**API** — 复制并编辑：
```
cp apps/api/.env.example apps/api/.env
```
**Worker** — 使用相同的 `.env` 或一个专用文件，至少需包含：
```
DATABASE_URL=postgresql://user:password@localhost:5432/sentinel
REDIS_URL=redis://localhost:6379
GEMINI_API_KEY=your_gemini_api_key
```
**Web** — 创建 `apps/web/.env.local`：
```
NEXT_PUBLIC_API_URL=http://localhost:3000/backend
NEXT_PUBLIC_WS_URL=http://localhost:3001
NEXT_PUBLIC_WEB_URL=http://localhost:3000
# 可选：Firebase（省略以使用 dev-auth）
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
```
Next.js 开发服务器将 `/backend/*` 代理到 API（`apps/web/next.config.ts`，可通过 `API_PROXY_TARGET` 覆盖）。
### 3. 数据库
```
npm run db:generate
npm run db:push # quick start
# 或
npm run db:migrate # with migrations
```
### 4. 构建 shared 包
```
npm run build --workspace=@sentinel/shared
```
### 5. 运行所有服务（需三个终端）
```
npm run dev:api # http://localhost:3001
npm run dev:worker # BullMQ consumers + Gemini
npm run dev:web # http://localhost:3000
```
### 6. 验证
```
curl http://localhost:3001/health
# → {"ok":true}
```
打开 [http://localhost:3000](http://localhost:3000)，登录并从仪表板创建一个事件。
## 环境变量
### API (`apps/api`)
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 |
| `REDIS_URL` | 是 | 用于 BullMQ 和 pub/sub 的 Redis |
| `PORT` | 否 | HTTP 端口（默认 `3001`；由 Railway 设置） |
| `CORS_ORIGIN` | 生产 | 逗号分隔的允许来源（例如 Vercel URL） |
| `FIREBASE_PROJECT_ID` | 生产 | Firebase Admin |
| `FIREBASE_CLIENT_EMAIL` | 生产 | Firebase Admin |
| `FIREBASE_PRIVATE_KEY` | 生产 | Firebase Admin（在 PEM 中转义 `\n`） |
### Worker (`apps/worker`)
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `DATABASE_URL` | 是 | 与 API 相同的数据库 |
| `REDIS_URL` | 是 | 与 API 相同的 Redis |
| `GEMINI_API_KEY` | 是 | Google AI API key |
| `GEMINI_MODEL` | 否 | 默认为 `gemini-2.5-flash-lite` |
| `GEMINI_TEMPERATURE` | 否 | 默认为 `0` |
| `MAX_VALIDATION_RETRIES` | 否 | 默认为 `3` |
### Web (`apps/web`)
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `NEXT_PUBLIC_API_URL` | 是 | REST 基础 URL（本地：`http://localhost:3000/backend`） |
| `NEXT_PUBLIC_WS_URL` | 是 | Socket.IO 服务器（本地：`http://localhost:3001`） |
| `NEXT_PUBLIC_WEB_URL` | 否 | 公网站点 URL |
| `NEXT_PUBLIC_FIREBASE_*` | 生产 | Firebase web SDK 配置 |
| `API_PROXY_TARGET` | 否 | Next rewrite 目标（默认为 `http://localhost:3001`） |
## 脚本
| 命令 | 描述 |
|---------|-------------|
| `npm run dev:web` | 启动 Next.js dev server |
| `npm run dev:api` | 以 watch mode 启动 API |
| `npm run dev:worker` | 以 watch mode 启动 worker |
| `npm run build` | 构建 shared → api → worker |
| `npm run db:generate` | 生成 Prisma client |
| `npm run db:push` | 将 schema 推送到数据库 |
| `npm run db:migrate` 运行 Prisma 迁移 |
各工作区的构建：
```
npm run build --workspace=@sentinel/shared
npm run build --workspace=api
npm run build --workspace=worker
npm run build --workspace=web
```
## 部署
生产环境需要**三个**部署目标：**Vercel (web)**、**Railway (API)** 和 **一个 worker 进程**（Railway 第二个服务、Render、Fly.io 等）。
### API (Railway)
有关故障排除（例如“Failed to fetch”），请参阅 [DEPLOYMENT.md](./DEPLOYMENT.md)。
- 服务根目录：**monorepo 根目录**
- 构建：`npm ci && npm run build --workspace=@sentinel/shared && npm run build --workspace=api`
- 启动：`npm run start:prod --workspace=api`
- 健康检查：`GET /health`
- 公网 URL：使用 HTTPS，**不带** `:3001`（例如 `https://sentinalai-apiservice.up.railway.app`）
### Worker（独立服务）
与 API 使用相同的 `DATABASE_URL`、`REDIS_URL` 和 `GEMINI_API_KEY`：
```
npm ci
npm run build --workspace=@sentinel/shared
npm run build --workspace=worker
npm run start:prod --workspace=worker
```
### Web (Vercel)
| 变量 | 示例 |
|----------|---------|
| `NEXT_PUBLIC_WEB_URL` | `https://sentinel-ai-v1.vercel.app` |
| `NEXT_PUBLIC_API_URL` | `https://sentinalai-apiservice.up.railway.app` |
| `NEXT_PUBLIC_WS_URL` | `https://sentinalai-apiservice.up.railway.app` |
| `NEXT_PUBLIC_FIREBASE_*` | 你的 Firebase web app |
更改环境变量后请重新部署。
## 应用路由
| 路由 | 描述 |
|-------|-------------|
| `/` | 着陆页 |
| `/login` | Firebase 登录 |
| `/dashboard` | 指挥中心，实时活动 |
| `/incidents/[id]` | 事件详情、agent 网格、时间线 |
| `/workflows` | 工作流可视化 |
| `/agents` | Agent 集群指标 |
| `/reports` | 事件报告 |
| `/architecture` | 应用内架构概览 |
## License
除非代码库中另有说明，否则为私有/无特殊许可证。
标签：BurpSuite集成, LLM, NestJS, Unmanaged PE, 搜索引擎查询, 测试用例, 特征库, 自动化攻击, 自动化编排, 运维监控