Saikarthik-kammari/cyepro-mern
GitHub: Saikarthik-kammari/cyepro-mern
基于 MERN 技术栈和 Claude AI 的智能通知分类系统，通过三级优先级（立即/稍后/忽略）和多层过滤机制解决告警疲劳问题。
Stars: 0 | Forks: 0
# Cyepro 通知优先级引擎 — MERN 技术栈
## 在线地址
| 服务 | URL |
|---------|-----|
| 前端 | https://cyepro-frontend.vercel.app |
| 后端 | https://cyepro-mern-production.up.railway.app |
| 健康检查 | https://cyepro-mern-production.up.railway.app/health |
## 演示账号
这些信息直接显示在登录页面上 —— 无需在 README 中查找。
| 角色 | 邮箱 | 密码 | 权限说明 |
|------|-------|----------|-----------------|
| 管理员 (Admin) | admin@cyepro.com | Admin@123 | 所有权限 — 规则、设置、审计日志 |
| 操作员 (Operator) | operator@cyepro.com | Operator@123 | 提交事件、查看仪表盘 |
## 系统功能 —— 通俗版
想象一下，你的公司每天收到 500 条通知 —— 安全警报、支付失败、会议提醒、营销邮件。大多数都是干扰信息。该系统会自动读取每条通知并做出决定：
- 🟢 **NOW (立即)** —— 立即发送（例如：“有人入侵了你的账户”）
- 🟡 **LATER (稍后)** —— 稍后批量发送（例如：“你的周报已准备好”）
- 🔴 **NEVER (从不)** —— 丢弃（例如：垃圾邮件、重复内容、促销信息）
每个决定都会记录原因。管理员可以通过 UI 创建规则。AI 负责处理规则未覆盖的情况。
## 技术栈 —— 按技术、版本、选择原因排序
| 技术 | 版本 | 选择原因 |
|------------|---------|-----------------|
| Node.js | 24.x | 非阻塞异步 I/O —— 非常适合高吞吐量的通知处理 |
| Express | 4.x | 极简、快速的 HTTP 框架 —— 无额外开销 |
| MongoDB | Atlas | 灵活的模式，适合具有不同元数据的半结构化通知数据 |
| Mongoose | 8.x | 开箱即用的模式验证 + 索引 + 软删除 |
| Next.js | 16.x | App Router、服务端组件、内置 TypeScript —— 生产级前端 |
| Tailwind CSS | 4.x | 实用优先、移动优先的样式方案，无需自定义 CSS |
| Claude AI | claude-3-5-haiku | 快速、便宜，擅长处理结构化 JSON 输出的分类任务 |
| @anthropic-ai/sdk | Latest | 官方 SDK，具备完善的错误处理 |
| Socket.IO | 4.x | 实时双向事件通信 —— 仪表盘更新无需轮询 |
| node-cron | 3.x | 轻量级 cron 调度器，用于 LATER 队列后台任务 |
| string-similarity | 4.x | 基于 Dice 系数算法的近重复检测 |
| jsonwebtoken | 9.x | 无状态 JWT 认证 —— 支持水平扩展 |
| bcryptjs | 2.x | 安全的密码哈希 |
## 架构概览
```
┌─────────────────────────────────────────────────────┐
│ Next.js Frontend │
│ Login │ Dashboard │ Simulator │ Audit │ Rules │ ... │
└────────────────────┬────────────────────────────────┘
│ HTTP + Socket.IO
┌────────────────────▼────────────────────────────────┐
│ Express Backend │
│ │
│ Auth Routes → JWT Middleware → Protected Routes │
│ │
│ POST /api/notifications/submit │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ Decision Pipeline │ │
│ │ │ │
│ │ 1. Deduplication Service │ │
│ │ 2. Alert Fatigue Service │ │
│ │ 3. Rule Engine │ │
│ │ 4. Claude AI + Circuit Breaker │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ MongoDB (6 collections) │
│ Background Job (every 5 min) │
└─────────────────────────────────────────────────────┘
```
### 层级通俗说明（面向非开发人员）
**前端 (Next.js)** —— 用户交互的网站。共 7 个页面。通过互联网与后端通信。
**Express 后端** —— 接收并处理通知的服务器。就像一个分拣邮件的邮局。
**决策流水线** —— 对每条通知按顺序执行 4 项检查。就像机场的安全检查站。
**MongoDB** —— 永久存储所有数据的数据库。6 个“文件柜”用于存储不同类型的数据。
**后台任务** —— 一个每 5 分钟唤醒一次以处理延迟通知的工作进程。自动运行。
## AI 集成（我使用的 AI）
**提供商：** Anthropic
**模型：** claude-3-5-haiku-20241022
**选择原因：** 快速（低延迟）、便宜（对于大流量很重要）、擅长返回结构化 JSON
### 我发送的确切 Prompt
```
You are a Notification Prioritization Engine.
Analyze this notification and classify it.
Notification Details:
- Event Type: {event_type}
- Message: {message}
- Source: {source}
- Priority Hint: {priority_hint}
- Channel: {channel}
Classification Rules:
- NOW: Urgent, needs immediate attention (security alerts, payment failures, critical errors)
- LATER: Important but not urgent (meeting reminders, project updates, weekly reports)
- NEVER: Spam, promotions, duplicates, irrelevant (marketing, discount offers)
Respond ONLY with valid JSON like this:
{
"classification": "NOW",
"confidence": 0.95,
"reasoning": "Security alert requires immediate attention"
}
```
### Claude 的返回内容
```
{
"classification": "NOW",
"confidence": 0.95,
"reasoning": "Security alert requires immediate attention"
}
```
我们解析 JSON，验证 classification 是否为 NOW/LATER/NEVER 之一，并存储完整结果，包括模型名称、置信度分数以及是否为回退结果。
### 当 AI 不可用时 —— 逐步说明（当它失败或宕机时）
1. Claude API 调用失败
2. 等待 1 秒 → 重试（第 2 次尝试）
3. 等待 2 秒 → 重试（第 3 次尝试）
4. 所有 3 次尝试均失败 → 在熔断器中记录失败
5. 累计 5 次失败后 → 熔断器打开（停止调用 AI 60 秒）
6. 回退机制启动 —— 基于关键词的分类（类似于第一轮的逻辑）
7. 结果存储时标记 `is_fallback: true`，表明这不是 AI 的结果
8. 健康检查端点报告 `circuit_breaker: OPEN`
9. 60 秒后 → 熔断器尝试一次测试调用（半开状态）
10. 如果测试成功 → 回到关闭状态（恢复正常操作）
## 前置条件
- Node.js v18 或更高版本
- npm v9 或更高版本
- MongoDB Atlas 账户（免费层即可）
- Anthropic API 密钥（可在 console.anthropic.com 获取免费额度）
## 环境变量
在 `cyepro-mern` 文件夹中创建一个 `.env` 文件：
```
# MongoDB 连接字符串来自 Atlas → Connect → Drivers
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/cyepro-mern
# 用于签名 JWT tokens 的 Secret key — 设置得长且随机
JWT_SECRET=your_long_random_secret_at_least_32_characters
# Token 有效期
JWT_EXPIRES_IN=7d
# 来自 console.anthropic.com → API Keys
ANTHROPIC_API_KEY=sk-ant-api03-...
# Circuit breaker 打开前的 AI 失败次数
CIRCUIT_BREAKER_THRESHOLD=5
# Circuit breaker 保持打开的时长（毫秒） — 60000 = 1 分钟
CIRCUIT_BREAKER_TIMEOUT=60000
# 前端 URL（用于 CORS）
FRONTEND_URL=http://localhost:3000
```
## 本地运行
### 后端
```
# 1. 进入 backend 文件夹
cd cyepro-mern
# 2. 安装 packages
npm install
# 3. 创建 .env 文件并填入值（见上文）
# 4. 创建 admin/operator 账户和默认 rules
node scripts/seed.js
# 5. 启动服务器
node server.js
# 你应该看到：
# MongoDB 已连接
# 服务器运行在端口 5000
# LATER 队列任务已调度 — 每 5 分钟运行一次
```
### 前端
```
# 1. 进入 frontend 文件夹
cd cyepro-frontend
# 2. 安装 packages
npm install
# 3. 创建 .env.local 文件
echo NEXT_PUBLIC_API_URL=http://localhost:5000 > .env.local
# 4. 启动 frontend
npm run dev
# 打开 http://localhost:3000
```
## 已知局限性 —— 基于我的最佳实践
### 1. 登录会话在 7 天后过期
目前，如果你登录，会话将持续 7 天。之后你需要重新登录。一个完善的生产系统会在后台自动续期你的会话，让你永远不会意外登出。
### 2. 数据量极大时重复检测会变慢
我们的近重复检测使用文本相似度算法将每条新通知与最近的通知进行比较。这在数千条通知的情况下效果很好，但在数百万条时会变慢。一个真正的生产系统会使用一种称为 MinHash 的更快数学技术，可以瞬间比较数百万条通知。
### 3. AI 失败记录在重启后丢失
我们的熔断器（即当 AI 持续失败时停止调用它的系统）在内存中保存计数。如果服务器重启，它会忘记发生了多少次失败。生产系统会将此存储在像 Redis 这样的共享数据库中，以便失败计数在重启后依然保留。
### 4. 对单个用户的请求量没有限制
任何登录用户都可以发送任意数量的通知。生产系统会对此进行限制 —— 例如每个用户每分钟最多 100 个请求 —— 以防止滥用。
标签：AI 通知引擎, Claude AI, Express, GNU通用公共许可证, MERN 全栈, MITM代理, MongoDB, Mongoose, Node.js, OSV, Railway, REST API, SaaS 平台, Tailwind CSS, TCP/UDP协议, TypeScript, Vercel, 事件处理, 事件管理, 后台管理系统, 告警去重, 告警疲劳检测, 垃圾信息过滤, 安全插件, 安全运营, 实时分类, 扫描框架, 熔断器, 自动化规则, 自定义脚本, 自定义脚本, 通知优先级分类