alishasajjad/ModPulse-AI

# ModPulse AI **AI 驱动的 Reddit 审核操作系统** — 将实时威胁检测、智能审核流水线、审核员 Copilot 以及达到作品集级别的 SaaS 仪表板整合在一个平台中。        ## 引言 **ModPulse AI** 是一个为 Reddit 社区、毕业设计项目 (FYP)、招聘作品集和 SaaS 风格演示打造的全栈审核控制平面。它在一个玻璃拟物化的 UI 中，将 AI 辅助内容评分、实时运营仪表板和审核员工作流结合在一起。 该平台以运行在 **端口 5000** 的 **Node.js / Express API** 作为后端，前端采用 **React SPA** (Vite)，使用 **MongoDB** 进行持久化存储，并利用 **Socket.io** 实现实时警报、突袭 (raid) 模拟、分析刷新和锁定广播。 ## 核心功能 | 领域 | 功能 | |------|------------| | AI 审核 | Hugging Face Toxic-BERT 评分、解释说明、置信度、启发式兜底 | | 实时运营 | Socket.io 实时警报、指标、突袭动态、锁定横幅 | | 威胁检测 | 突袭、垃圾信息集群、调查、紧急锁定 | | 突袭模拟器 | 协调的有毒攻击模拟及实时威胁等级 | | Reddit 沙盒 | 虚假的 subreddits、用户、帖子、实时 AI 分析 | | 审核员 Copilot | 队列、建议、自然语言命令聊天 | | 申诉 | 提交、AI 重新审核、审核员批准/拒绝 | | 数据分析 | 热力图、趋势、准确度仪表板、导出 | | 认证与 RBAC | JWT + refresh token，角色从 viewer 到 super_admin | | 主题 | 深色/浅色切换，支持 `modpulse-theme` 持久化 | | 演示模式 | 演示用的种子数据 + 模拟流量 | | DevOps | Docker Compose、适配 CI 的测试、生产环境部署指南 | ### 功能清单 - [x] 带有 refresh token 轮换的 JWT 身份验证 - [x] 基于角色的访问控制 (RBAC) - [x] 带有解释面板的 AI 评论分析 - [x] 实时 Socket.io 仪表板 - [x] AI 突袭模拟器（启动 / 停止 / 重置） - [x] 虚假的 Reddit 沙盒环境 - [x] 审核员 Copilot + 自然语言命令聊天 (`/api/os/copilot/chat`) - [x] 带有重新分析功能的 AI 申诉系统 - [x] 紧急锁定模式 - [x] 用户信誉与高风险评分 - [x] 威胁时间轴重放 - [x] AI 审核准确度指标 - [x] 实时有毒活动热力图 - [x] 深色 / 浅色主题（加载时无闪烁） - [x] Reddit OAuth subreddit 连接 - [x] Devvit webhook 集成 - [x] Docker Compose 本地技术栈 - [x] 针对严重威胁的可选声音警报 ## 平台模块 ### SaaS 审核平台 采用多租户风格的布局，包含受保护的路由 (`/dashboard`, `/ai-moderation`, `/threat-detection` 等)、命令面板 (`Ctrl+K`)、通知中心、审计日志以及基于角色限制访问的导航。 ### AI 审核流水线 1. 内容通过 API、沙盒、Reddit 同步或 Devvit webhook 进入。 2. `aiModerationService` 调用 **Hugging Face**（默认使用 `unitary/toxic-bert`）。 3. 在失败或超时时，本地运行**启发式分析**（无需外部 LLM）。 4. 结果将连同风险评分、建议操作和解释字段持久化到 `ModerationLog` 中。 5. 高风险项目会触发 Socket.io 警报和 Copilot 队列更新。 ### 实时威胁检测 监控速度、协同垃圾邮件、滥用模式和突袭指标。审核员可以调查用户、解决突袭事件、调整严重程度，并触发具有完整审计追踪的锁定模拟。 ### AI 突袭模拟器 **威胁检测 → AI 突袭模拟器** 生成协同的有毒信息爆发，实时更新威胁等级，持久化 `RaidSimulation` / `RaidDetectionLog` 记录，并发出 `raid:*` socket 事件以供实时图表和提示通知使用。 ### Reddit 沙盒 **Reddit 沙盒** (`/reddit-sandbox`) 提供了一个演示环境：创建 subreddits、用户、帖子和评论；每条评论都会经过相同的 AI 流水线处理，并带有 `source: sandbox` 标记。 ### 审核员 Copilot **Copilot** 页面显示优先级队列、建议和工作负载。**自然语言聊天** 接受以下命令： - `show high risk users` - `start raid simulation` - `lock subreddit` - `show appeals` - `show recent raids` 通过 `POST /api/os/copilot/chat` 确定性地解析命令（无需付费 LLM）。 ### 申诉系统 用户/审核员提交申诉；流水线将重新运行 AI 分析。审核员批准或拒绝操作，并伴随审计日志和 `appeal:*` socket 事件。 ### 分析与热力图 **数据分析** 仪表板包含 KPI、有毒内容趋势、审核员表现、**实时热力图**、社区增长情况以及 **AI 审核准确度** 面板 (`/api/os/accuracy`)。 ### 实时 Socket.io 架构 单一的 Socket.io 服务器运行在 API 主机上 (`/socket.io`)。客户端使用 `auth.token` 中的 JWT 进行身份验证，加入仪表板房间，并通过限流处理程序进行订阅，以防止频繁重新渲染。 ### 认证与 RBAC | 角色 | 典型访问权限 | |------|----------------| | `viewer` | 仪表板、通知（以阅读为主） | | `analyst` | 威胁检测、社区情报、数据分析 | | `moderator` | AI 审核、Copilot、警报、沙盒、设置 | | `super_admin` | 完全平台访问权限 + 演示流量控制 | ## 技术栈 | 层级 | 技术 | |-------|----------------| | **前端** | React 19, Vite 8, React Router 7, Tailwind CSS 4, Framer Motion, Recharts, Lucide | | **后端** | Node.js 20+, Express 5, Mongoose 9, Socket.io 4 | | **AI** | Hugging Face Inference API (`unitary/toxic-bert`)，本地启发式算法 | | **数据库** | MongoDB 6+ / MongoDB Atlas | | **认证** | JWT access + refresh，bcrypt，cookie-parser | | **缓存 (可选)** | Redis（Docker Compose 包含 Redis；在配置后使用） | | **DevOps** | Docker，Nginx（前端镜像），GitHub Actions CI | ## 架构 ``` flowchart TB subgraph Client["Browser"] SPA["React SPA :5173"] SOC["Socket.io Client"] end subgraph API["Backend :5000"] EXP["Express 5 REST"] SIO["Socket.io Server"] AI["HF Toxic-BERT + Heuristics"] OS["ModPulse OS /api/os"] end subgraph Data["Data Layer"] MONGO[(MongoDB)] REDIS[(Redis optional)] end subgraph External["External"] HF["Hugging Face API"] REDDIT["Reddit OAuth"] end SPA --> EXP SOC --> SIO EXP --> MONGO EXP --> AI AI --> HF OS --> MONGO SIO --> MONGO EXP --> REDIS EXP --> REDDIT ``` 请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 了解请求流程、安全性和服务边界。 ## 项目结构 ``` ModPulse_AI/ ├── backend/ │ ├── src/ │ │ ├── config/ # env, database, socket │ │ ├── controllers/ │ │ ├── middleware/ # auth, RBAC, security, validation │ │ ├── models/ # Mongoose schemas │ │ ├── routes/ # REST routers (+ osRoutes.js) │ │ ├── services/ # business logic, AI providers, realtime │ │ └── utils/ │ ├── scripts/ # reddit-mock, utilities │ ├── Dockerfile │ └── .env.example ├── frontend/ │ ├── src/ │ │ ├── components/ # UI, dashboard, threat, os/ │ │ ├── context/ # Auth, Theme, ModPulseProvider │ │ ├── pages/ │ │ ├── routes/ │ │ └── services/ # api, socket, osApi │ ├── Dockerfile │ └── .env.example ├── docs/ # Detailed documentation ├── devvit/ # Reddit Devvit app ├── docker-compose.yml ├── docker-compose.prod.yml └── README.md ``` ## 快速开始 ### 前置条件 - **Node.js 20+** 和 npm - **MongoDB**（本地或 [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)） - 可选：用于实时 Toxic-BERT 评分的 **Hugging Face API key**（启发式算法可在离线状态下工作） ### 安装 ``` git clone https://github.com/your-username/ModPulse_AI.git cd ModPulse_AI cd backend && npm install cd ../frontend && npm install ``` ### 配置环境 ``` cp backend/.env.example backend/.env cp frontend/.env.example frontend/.env ``` 编辑 `backend/.env` —— 最少需要配置：`MONGODB_URI`, `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`, `CORS_ORIGIN=http://localhost:5173`。 请参阅 [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) 获取完整的变量参考。 ### 运行开发服务器 **终端 1 —— API (端口 5000):** ``` cd backend npm run dev ``` **终端 2 —— 前端 (端口 5173):** ``` cd frontend npm run dev ``` 打开 **http://localhost:5173** → 落地页。登录以访问位于 **/dashboard** 的应用外壳。 验证 API：`GET http://localhost:5000/health` ## 环境设置 | 文件 | 用途 | |------|---------| | `backend/.env` | API 密钥、MongoDB、JWT、Reddit OAuth、Hugging Face、演示标志 | | `frontend/.env` | `VITE_API_URL=http://localhost:5000` | **MongoDB Atlas（推荐用于演示）：** 1. 创建一个免费的集群和数据库用户。 2. 允许您的 IP 访问（或仅在开发时使用 `0.0.0.0/0`）。 3. 复制连接字符串 → `MONGODB_URI=mongodb+srv://...` **Reddit OAuth:** 在 [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps) 创建一个应用 (web app)，将重定向 URI 设置为 `http://localhost:5000/api/auth/reddit/callback`。详情请参阅 [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md)。 **Devvit:** 请参阅 [docs/DEVVIT.md](docs/DEVVIT.md)。 ## 演示凭证与演示模式 ### 默认管理员（首次启动时创建） | 字段 | 值 | |-------|--------| | Email | `admin@modpulse.ai` | | Password | `ModPulse2026!`（或您的 `DEFAULT_ADMIN_PASSWORD`） | ### 作品集演示模式 在 `backend/.env` 中： ``` DEMO_MODE=true SEED_ON_STARTUP=true ``` 然后（以 super_admin 身份）： ``` curl -X POST http://localhost:5000/api/demo/seed \ -H "Authorization: Bearer " ``` 可选的模拟流量： ``` curl -X POST http://localhost:5000/api/demo/traffic/start \ -H "Authorization: Bearer " ``` 停止流量：`POST /api/demo/traffic/stop` 有关生产演示实例，请参阅 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。 ### 演示工作流 (FYP / 作品集) 1. 启动后端 + 前端，以管理员身份登录。 2. 打开 **威胁检测** → **启动突袭模拟** → 观察实时威胁等级和警报。 3. 打开 **Reddit 沙盒** → 创建帖子 → 发表有毒评论 → 查看 AI 解释。 4. 打开 **审核员 Copilot** → 聊天输入：`show high risk users` 或 `start raid simulation`。 5. 打开 **AI 审核** → 分析评论 → 展开 **AI 推理过程**。 6. 从导航栏切换 **深色/浅色主题**（在重新加载后保持有效）。 ## API 概览 Base URL: `http://localhost:5000`（开发环境） 受保护的路由需要：`Authorization: Bearer ` | 命名空间 | 路径 | 描述 | |-----------|------|-------------| | Health | `GET /health`, `GET /metrics` | 存活状态与请求指标 | | Auth | `/api/auth/*` | 登录、注册、刷新、Reddit OAuth | | Moderation | `/api/moderation/*` | 分析、日志、AI 健康状态 | | Threats | `/api/threats/*` | 警报、突袭、锁定、调查 | | Copilot | `/api/copilot/*` | 队列、建议、操作 | | Analytics | `/api/analytics/*` | 仪表板、热力图、导出 | | Community | `/api/community/*` | 洞察、情绪、快照 | | Settings | `/api/settings` | 平台与 AI 自动化设置 | | Reddit | `/api/reddit/*` | 已连接的 subreddits | | Notifications | `/api/notifications/*` | 应用内通知 | | Automation | `/api/automation/*` | 定时自动化规则 | | **ModPulse OS** | `/api/os/*` | 突袭模拟、沙盒、申诉、锁定、Copilot 聊天 | | Demo | `/api/demo/*` | 种子数据与流量（当 `DEMO_MODE=true` 时 | | Devvit | `/api/devvit/*` | Webhook 与安装（公共路由有所不同） | 完整参考：[docs/API.md](docs/API.md) ## WebSocket 事件 连接方式：`io(VITE_API_URL, { path: '/socket.io', auth: { token: accessToken } })` | 类别 | 事件 | |----------|--------| | Connection | `modpulse:connected` | | Threat | `threat:alert`, `threat:emergency`, `threat:metrics`, `moderation:alert`, `threat:lockdown` | | Raid sim | `raid:started`, `raid:tick`, `raid:threat-level`, `raid:ended` | | Copilot | `copilot:queue`, `copilot:action`, `copilot:alert`, `copilot:recommendation` | | Analytics | `analytics:live-metrics`, `analytics:dashboard-refresh`, `analytics:update` | | Sandbox | `sandbox:post-created`, `sandbox:comment-created`, `sandbox:moderation-action` | | Appeals | `appeal:created`, `appeal:updated` | | Lockdown | `lockdown:updated` | | Reputation | `user:reputation-updated` | 详情请参阅：[docs/SOCKET.md](docs/SOCKET.md) ## 主题系统 - 通过导航栏中的**日/月**图标进行切换。 - 以 **`modpulse-theme`** (`dark` | `light`) 为 key 持久化存储在 `localStorage` 中。 - `frontend/index.html` 中的内联脚本会在 React 绘制之前应用主题（无闪烁）。 - 浅色模式使用 `frontend/src/index.css` 中的 CSS 变量覆盖。 ## Docker ``` # 从 repository root docker compose up --build ``` | 服务 | URL | |---------|-----| | Frontend | http://localhost:5173 (nginx) | | API | http://localhost:5000 | | MongoDB | localhost:27017 | | Redis | localhost:6379 | 生产环境配置： ``` docker compose -f docker-compose.prod.yml up --build -d ``` ## 测试 ``` # Backend — Jest + Supertest cd backend && npm test # Frontend — Vitest + Testing Library cd frontend && npm test ``` 配置后，CI 将通过 `.github/workflows/ci.yml` 运行这两个测试套件。 ## 部署 | 组件 | 建议目标平台 | |-----------|------------------| | 前端 | Vercel、Netlify 或 Nginx 静态主机 | | API + Socket.io | Railway、Render、Fly.io 或 VPS（端口 **5000**） | | 数据库 | MongoDB Atlas | | Redis | Redis Cloud（可选） | 指南：[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) ## 🚀 在线演示 / Devvit App ModPulse AI 已作为 Reddit Devvit 应用部署，直接集成了 Reddit 审核员工作流。 **体验 / App 链接:** https://www.reddit.com/r/modpulse_saas_dev ## 📌 关于本应用 ModPulse AI 是一个由 AI 驱动的 Reddit 审核系统，旨在帮助审核员更高效地管理社区。它能实时检测有毒内容，识别突袭模式，并提供 AI 辅助的审核决策。 该系统包含一个完整的审核仪表板，具备实时分析、审核队列、威胁检测、突袭模拟和智能审核员 Copilot，利用 Devvit 在 Reddit 内部自动化并协助决策。 ## 演示视频 - https://youtu.be/RcwOPWY-2e4 ## 文档 | 文档 | 描述 | |----------|-------------| | [架构](docs/ARCHITECTURE.md) | 架构层级、流程、安全性、实时通信 | | [本地设置](docs/SETUP.md) | 逐步搭建开发环境指南 | | [环境变量](docs/ENVIRONMENT.md) | 完整的环境变量参考 | | [API 参考](docs/API.md) | REST endpoints（包含 `/api/os`） | | [Socket.io 事件](docs/SOCKET.md) | 实时事件目录 | | [AI 工作流](docs/AI_WORKFLOWS.md) | 评分、Copilot、申诉、突袭模拟 | | [数据库 schema](docs/DATABASE.md) | 集合与索引 | | [部署](docs/DEPLOYMENT.md) | 生产环境与演示实例 | | [Devvit](docs/DEVVIT.md) | Reddit App 集成 | ## 故障排除 | 问题 | 解决方案 | |-------|----------| | API 调用时出现 `ECONNREFUSED` | 确保后端运行在端口 **5000** 上，并且 `VITE_API_URL` 匹配 | | Socket 显示离线 | 检查 JWT 是否有效；验证 CORS 以及 `CORS_ORIGIN` 是否包含前端 URL | | AI 总是使用启发式算法 | 设置 `HUGGINGFACE_API_KEY`；检查与 `api-inference.huggingface.co` 的网络连接 | | MongoDB 连接失败 | 验证 `MONGODB_URI`、Atlas IP 允许列表、凭据 | | 沙盒/申诉时出现验证错误 | 拉取最新代码 —— `ModerationLog.source` 和 `AuditLog.entityType` 枚举已扩展 | | 突袭模拟无法启动 | 更新 schema 后重启后端；检查 MongoDB 是否正在运行 | | 锁定同时显示错误和成功提示 | 确保在后端已更新 `AuditLog` 枚举的情况下重启 | | 重新加载时主题闪烁 | 清除缓存；确认 `index.html` 中存在内联主题脚本 | ## 未来改进 - 基于 Redis 的缓存，用于分析聚合数据 - Webhook 外发集成（Slack、Discord） - 多租户组织计费 - 增强的 LLM 解释（在 feature flag 之后使用可选的外部提供商） - 使用 Playwright 进行 E2E 测试 - Kubernetes Helm chart ## 贡献 1. Fork 本仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 使用清晰的信息提交更改 4. 在 `backend` 和 `frontend` 中运行 `npm test` 5. 提交 Pull request，UI 更改请附带截图 请勿提交密钥（`.env`、API 密钥）或在没有迁移说明的情况下修改生产环境的 schema。 ## 许可证 本项目基于 **MIT License** 授权 —— 请参阅仓库根目录中的 [LICENSE](LICENSE) 文件。 ## 贡献者 - Alisha Sajjad — 项目作者 & 全栈开发人员 - Zarmeen Rasool — 项目作者 & 全栈开发人员 未来的贡献者将出现在 GitHub 贡献者图表中。

为 FYP 演示、招聘作品集 以及 生产环境就绪的 SaaS 审核工作流而构建。

标签：GNU通用公共许可证, IaC 扫描, MITM代理, Node.js, React, SaaS平台, Syscalls, 人工智能, 内容审核, 后端开发, 实时通信, 搜索引擎查询, 用户模式Hook绕过, 社区管理, 请求拦截