MuhammadZaidSaqib/SentinelX-Real-Time-Fraud-Intelligence
GitHub: MuhammadZaidSaqib/SentinelX-Real-Time-Fraud-Intelligence
一个端到端的实时AI欺诈检测系统，结合机器学习、图分析与可解释性，解决高并发场景下的风险识别与透明评分问题。
Stars: 16 | Forks: 0
# 任务4 — 实时AI欺诈检测平台
端到端演示：**FastAPI** API，**React** 仪表板，**Kafka** 流式处理，**PostgreSQL**，集成 **ensemble + Keras autoencoder** 堆栈，**NetworkX** 图风险分析，**SHAP** 解释，以及可选的 **OpenAI-compatible** 叙事端点。
**默认登录（生产环境请修改）：** `admin` / `admin123`（JWT）。
## 目录
- [功能](#功能)
- [仓库结构](#仓库结构)
- [前置条件](#前置条件)
- [快速启动（Docker）](#快速启动docker)
- [配置（环境变量）](#配置环境变量)
- [数据库迁移（Alembic）](#数据库迁移alembic)
- [本地开发（无 Docker）](#本地开发无-docker)
- [API 概览](#api-概览)
- [风险引擎](#风险引擎)
- [安全注意事项](#安全注意事项)
- [性能](#性能)
## 功能
- REST + WebSocket 实时更新；JWT 认证
- Kafka 生产者/消费者管道写入 Postgres
- 混合评分：ML 集成、重构误差、图风险
- 基于 SHAP 的解释；可选 LLM “分析师” 副本（通过兼容 API）
## 仓库结构
```
task4/
├── backend/ # FastAPI, ML, Kafka, Alembic, scripts
│ ├── app/
│ ├── migrations/ # Alembic (avoids shadowing pip `alembic`)
│ ├── scripts/
│ ├── alembic.ini
│ └── requirements.txt # pinned Python deps (included from repo root)
├── frontend/ # Vite + React + Tailwind + Recharts + D3
├── docker-compose.yml
├── requirements.txt # pip install -r requirements.txt → backend pins
└── README.md
```
## 前置条件
| 领域 | 要求 |
|------|------|
| **Docker 路径** | [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
| **本地后端** | Python **3.11+**，在仓库根目录执行 `pip install -r requirements.txt`（或进入 `backend/` 执行 `pip install -r requirements.txt`） |
| **本地前端** | Node.js **20+**，在 `frontend/` 目录执行 `npm install` |
| **完整本地流式处理** | PostgreSQL、Kafka（KRaft 或 ZooKeeper），如使用经典 Kafka 脚本需 Java 17+ |
## 快速启动（Docker）
1. 安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。
2. 进入 `task4` 目录：
```
docker-compose up --build
```
3. 启动后，后端会运行 **`alembic upgrade head`**（详见 `scripts/entrypoint.py`），如果缺少模型工件则首次运行时会训练模型。首次启动可能需要几分钟，**模型训练**（若 `creditcard.csv` 不存在则使用合成数据）并将工件写入共享的 `modelshare` 卷。
4. 打开 **http://localhost:3000**（仪表板）和 **http://localhost:8000/docs**（OpenAPI）。
5. 使用 **`admin` / `admin123`** 登录。部署前请设置强 **`JWT_SECRET`** 并轮换演示凭据。
### 服务
| 服务 | 主机端口 | 角色 |
|------|----------|------|
| backend | 8000 | REST + WebSocket + ML 推理 |
| frontend | 3000 | 静态 UI（Nginx） |
| postgres | 5432 | `transactions`、`predictions`、`graph_edges` |
| kafka | 9092 | 外部 PLAINTEXT_HOST 监听器 |
| zookeeper | 2181 | Kafka 依赖 |
| consumer | — | Kafka → 数据库管道 |
| producer | — | 模拟交易流 |
容器内部 Kafka 监听地址：**`kafka:29092`**（在 Compose 中自动设置）。
### 可选：使用真实信用卡 CSV
将 [Kaggle creditcard.csv](https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud) 放置到 `backend/data/creditcard.csv` 并重建，或挂载卷到 `/app/data/creditcard.csv` 后运行训练：
```
docker-compose exec backend python scripts/train_models.py --csv /app/data/creditcard.csv
```
### 可选：AI 叙事（OpenAI-compatible）
在 `.env` 或当前 Shell 中设置（参见[配置](#配置环境变量)）。`POST /ai/insight` 返回简短的分析师风格摘要；无密钥时则使用 SHAP + 评分的**模板**摘要。
## 配置（环境变量）
变量从环境或可选 `.env` 读取（详见 `backend/app/config.py`）。Docker Compose 为 `backend` 设置主要变量；可通过根目录 `.env` 覆盖敏感信息。
| 变量 | 用途 | 示例 / 默认值 |
|------|------|----------------|
| `DATABASE_URL` | Postgres 连接 | `postgresql://fraud:fraud@localhost:5432/fraud_db` |
| `KAFKA_BOOTSTRAP_SERVERS` | 代理列表 | `localhost:9092`（本地）；Compose 中为 `kafka:29092` |
| `JWT_SECRET` | HS256 签名密钥 | **生产环境必须设置** |
| `JWT_ALGORITHM` | 算法 | `HS256` |
| `JWT_EXPIRE_MINUTES` | 令牌有效期 | `60` |
| `MODELS_DIR` | 保存的模型工件 | `models` 或 Docker 中的 `/app/models` |
| `DATA_DIR` | CSV / 数据文件 | `data` |
| `OPENAI_API_KEY` | 可选 LLM 洞察 | 空值 → 仅模板 |
| `OPENAI_BASE_URL` | 兼容 API 基础地址 | `https://api.openai.com/v1` |
| `OPENAI_MODEL` | 模型 ID | `gpt-4o-mini` |
**前端：** `VITE_API_URL` 指向 API（例如 `http://127.0.0.1:8000` 用于 `npm run dev`）。
## 数据库迁移（Alembic）
架构**不会**在运行时通过 `Base.metadata.create_all()` 创建。迁移文件位于 `backend/migrations/`，在 API 启动前于 Docker 中应用。
**常用命令**（在 `backend/` 中，设置 `DATABASE_URL`）：
```
# 应用所有挂起的迁移
python -m alembic upgrade head
# 从模型更改创建新修订（提交前审查差异）
python -m alembic revision --autogenerate -m "describe change"
# 一步降级
python -m alembic downgrade -1
```
**已存在的数据库**（若之前使用 `create_all` 构建且表结构一致）：可先在全新卷上应用迁移，或告知 Alembic 数据库已是最新版本而跳过 DDL：
```
python -m alembic stamp head
```
`migrations/env.py` 优先读取 `DATABASE_URL`，否则回退到 `app.config.Settings.database_url`。
## 本地开发（无 Docker）
### 完整栈：本地运行 PostgreSQL + Kafka
依次运行 **PostgreSQL**、**Kafka**（以下记录使用 KRaft，无需 ZooKeeper；经典 ZooKeeper + Kafka 也适用）、后端、**consumer**、**producer** 和 Vite 开发服务器。
**Kafka（Windows / KRaft）** — 前提条件：**Java 17+**、**Python 3.11+**、**Node.js 20+**、[Apache Kafka](https://kafka.apache.org/downloads) 解压到**无空格路径**（例如 `C:\kafka\kafka_2.13-3.7.0`），并设置 `KAFKA_HOME`。
**一次性 KRaft 初始化**
1. 编辑 `%KAFKA_HOME%\config\kraft\server.properties`：
- `listeners=PLAINTEXT://localhost:9092`
- `advertised.listeners=PLAINTEXT://localhost:9092`
- `log.dirs` 指向已存在的文件夹（例如 `C:/kafka-data/kraft-combined-logs`）
2. 格式化存储（每个新的 `log.dirs` 仅需一次）：
```
cd $env:KAFKA_HOME
.\bin\windows\kafka-storage.bat random-uuid
.\bin\windows\kafka-storage.bat format -t PASTE_UUID_HERE -c .\config\kraft\server.properties
```
3. 启动 Broker（保持运行）：`.\bin\windows\kafka-server-start.bat .\config\kraft\server.properties`
4. 创建主题 `transactions`：
```
& "$env:KAFKA_HOME\bin\windows\kafka-topics.bat" --create --if-not-exists --topic transactions --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
```
**启动顺序：** PostgreSQL → Kafka → topic → 后端 → consumer → producer → 前端。
**后端**（在 `backend/` 中，建议使用新虚拟环境）：
```bash
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
```
**Consumer**（第二个终端，使用相同虚拟环境和 `DATABASE_URL` / `KAFKA_BOOTSTRAP_SERVERS`）：
```bash
python -m app.kafka_appconsumer
```
**Producer**（第三个终端，设置 `KAFKA_BOOTSTRAP_SERVERS`）：
```bash
python -m app.kafka_app.producer
```
**前端：**
```
cd ..\frontend
npm install
$env:VITE_API_URL = "http://127.0.0.1:8000"
npm run dev
```
打开 Vite 打印的地址（例如 **http://localhost:5173**）。登录：**`admin` / `admin123`**。
**常见问题**
- `NoBrokersAvailable` → Kafka 未运行或 `KAFKA_BOOTSTRAP_SERVERS` 与 Broker 的 `listeners` 不匹配。
- Consumer “models not loaded” → 运行 `python scripts\train_models.py`。
- 旧版 Kafka + ZooKeeper 同样适用：先启动 ZooKeeper 再启动 Broker，并创建相同主题。
- **`Activate.ps1` 未找到** → 在 `backend/` 中创建虚拟环境：`python -m venv .venv`。若 PowerShell 限制脚本，执行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`，或直接调用 `.\.venv\Scripts\python.exe -m app.kafka_app.consumer`。
- **`No module named 'kafka'`** → 确保在虚拟环境中执行 `pip install -r requirements.txt`（根目录）或 `pip install -r backend/requirements.txt`。
### 仅后端（无 Kafka）
适用于 UI 与 API 调试；可省略 producer/consumer。仪表板模拟器仍可在无 Broker 情况下驱动流程。
```
cd backend
python -m venv .venv
.venv\Scripts\activate # Windows
# macOS/Linux：source .venv/bin/activate
pip install -r requirements.txt
set DATABASE_URL=postgresql://fraud:fraud@localhost:5432/fraud_db
python -m alembic upgrade head
python scripts/train_models.py
uvicorn app.main:app --reload --port 8000
```
### Kafka 消费者 / 生产者（Broker 已运行）
```
# 来自 backend/，venv 已激活，KAFKA_BOOTSTRAP_SERVERS 已设置
python -m app.kafka_app.producer
python -m app.kafka_app.consumer
```
### 前端（自定义 API 地址）
```
cd frontend
npm install
set VITE_API_URL=http://localhost:8000
npm run dev
```
## API 概览（JWT 认证，除 `/health`、`/auth/login` 外均需）
| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/auth/login` | JSON `{ "username", "password" }` → JWT |
| POST | `/predict` | 评分并持久化交易 |
| GET | `/transactions` | 带预测结果的最近记录 |
| GET | `/fraud-graph` | D3 所需的节点/边与指标 |
| GET | `/explain/{transaction_id}` | 随机森林的 SHAP 关键特征 |
| POST | `/ai/insight` | SHAP + 评分 → 模板或 LLM 叙事 |
| POST | `/ai/score-preview` | 评分特征（不包含图上下文） |
| WS | `/ws/stream?token=...` | 新交易（轮询 DB 并推送） |
| GET | `/health` | 活跃状态 + `models_loaded` |
## 风险引擎
最终评分（0–1）：
`0.5 × ML_ensemble_prob + 0.35 × autoencoder_norm + 0.15 × graph_risk`
等级：**LOW** / **MEDIUM** / **HIGH**，基于最终评分的阈值划分。
## 安全注意事项
- 部署前请替换 `JWT_SECRET` 和演示凭据。
- 开发环境 CORS 设置为 `*`，生产环境应限制来源。
- 使用网络策略保护 Kafka 与 Postgres，并设置强密码。
## 性能
推理针对 **单条交易** 在 CPU 上优化至 **低于 200 毫秒**；SHAP 与可选 LLM 调用为**按需执行**，不计入流式 SLA。
标签：AI欺诈检测, Apex, AV绕过, DNS解析, FastAPI, JWT认证, Kafka流处理, PostgreSQL, React, SHAP可解释性, Syscalls, Web仪表盘, 图分析, 图神经网络, 实时欺诈检测, 开源项目, 异常检测, 数据监控, 机器学习, 流式处理, 测试用例, 深度学习, 特权检测, 网络安全, 自编码器, 请求拦截, 逆向工具, 隐私保护, 风险评分