VOS3000 电话黑名单过滤系统 —— 企业级智能呼叫拦截解决方案--按等级储存第三方数据

## 📌 项目简介

这是一套专为 VOS3000 软交换平台设计的**高性能黑名单过滤系统**，支持千万级号码实时查询，提供多维度智能拦截策略，有效拦截骚扰电话、诈骗号码，保障通信质量。

---

## 🎯 项目背景

在电话营销和客户服务场景中，企业常常面临以下问题：

- 被叫号码投诉导致线路封停
- 高频呼叫触发运营商风控
- 缺乏有效的号码过滤机制
- 无法对接多个第三方黑名单平台
- 各平台数据分散，无法统一管理

本系统正是为解决这些痛点而生，提供**一站式号码过滤解决方案**。

---

## ✨ 核心功能

### 一、实时监控仪表盘

系统提供可视化仪表盘，实时展示业务数据：

**今日统计卡片**
- 今日查询量、通过量、拦截量
- 通过率/拦截率实时计算
- 可视化进度条展示

**本地拦截分类饼图**
- 白名单放行数量及占比
- 靓号拦截数量及占比
- 地区拦截数量及占比
- 超频拦截数量及占比
- 黑名单拦截数量及占比
- 正常放行数量及占比
- 未匹配数量及占比

**第三方拦截分类饼图**
- 正常：第三方返回非黑名单
- 黑名单：第三方返回黑名单
- 超时：调用超时，只拦截本次
- 故障：连接失败/解析失败

**历史趋势图**
- 近10天通过/拦截数据走势
- 堆叠面积图直观展示

**性能指标**
- 实时 QPS（每秒查询数）
- 实时响应时间（毫秒级）

**服务器硬件监控**
- CPU 使用率及核心数
- 内存使用率（已用/总量）
- 磁盘使用率及可用空间
- 实时网络流量（发送/接收速率）

**Redis 实例监控**
- 多实例状态展示（在线/离线/降级）
- 每个实例的内存占用、键数量、连接数
- 主从复制状态
- Redis Cluster 集群节点详情（可展开查看）

**数据库监控**
- PostgreSQL：连接数、活跃查询、缓存命中率、存储大小
- ClickHouse：连接数、查询总数、表数量、存储大小

> 📸 *【此处插入仪表盘截图】*

---

### 二、智能拦截规则配置

支持灵活的多条件组合规则，每条规则可配置以下匹配条件：

**基础匹配**
| 维度 | 说明 |
|------|------|
| 规则名称 | 自定义名称，便于识别 |
| IP 匹配 | 限制特定 IP 来源的请求 |
| 主叫前缀 | 按主叫号码前缀匹配 |
| 被叫前缀 | 按被叫号码前缀匹配 |
| 优先级 | 1-9 级，数字越小优先级越高 |

**地区限制**
- 按省份限制（如：只允许广东、浙江）
- 按城市限制（如：只允许深圳、杭州）
- 按运营商限制（移动、联通、电信、虚拟运营商）

**靓号识别**
- 自动识别 AAAA（四连号）
- 自动识别 ABAB（交替号）
- 自动识别顺子号（1234、4321）
- 自动识别 AABB（双双号）
- 可配置识别后拦截或放行

**超频限制**
- 限制同一被叫号码的呼叫频率
- 可配置时间窗口（如：1分钟内）
- 可配置最大次数（如：不超过3次）

**本地黑名单拦截**
- 6个来源等级，可自定义名称
- 可选择启用哪些等级参与拦截
- 如：等级1=投诉库、等级5=质检库

**第三方黑名单拦截**
- 选择具体的主叫改写规则
- 调用外部平台进行号码检测

> 📸 *【此处插入拦截规则配置页面截图】*

---

### 三、黑名单/白名单管理

#### 私有黑名单

**分级管理**
- 支持 **6 个来源等级**
- 每个等级可自定义名称（如：投诉库、质检库、手动添加等）
- 不同规则可选择启用不同等级

**批量导入**
- 单次导入支持 **500万条** 数据
- 支持异步处理，后台执行不阻塞
- 实时进度查询

**导入记录管理**
- 记录每次导入的时间、数量、来源
- 支持按导入ID筛选
- 支持查看导入详情（成功/失败/重复）
- 支持**一键撤销**（删除该批次所有数据）

**其他功能**
- 按手机号搜索
- 按等级导出
- 按等级清空

#### 私有白名单
- VIP 客户号码免拦截
- 批量添加，支持备注原因
- 白名单优先级最高，直接放行

#### IP 白名单
- 限制 API 调用来源
- 只允许白名单内 IP 访问系统
- 防止未授权调用

> 📸 *【此处插入黑名单管理页面截图】*

---

### 四、第三方黑名单对接（重点功能）

这是系统的核心差异化功能，支持**多平台、多数据源、统一管理、智能缓存**。

#### 4.1 接口配置

每个第三方平台是一个"接口配置"：

| 字段 | 说明 |
|------|------|
| 接口名称 | 如：平台A、平台B、XX数据 |
| 请求URL | 第三方黑名单查询API地址 |
| 超时时间(毫秒) | 超时后只拦截本次，不缓存结果 |
| 启用/禁用 | 可随时关闭某个平台 |

#### 4.2 主叫改写规则

每个接口下可配置**多个主叫改写规则**，实现同一平台对接多套数据：

| 字段 | 说明 |
|------|------|
| 名称 | 如：严格库、宽松库、VIP数据 |
| 主叫改写值 | 调用API时的主叫号码标识（如 1A、TEST01） |
| 释放时间(小时) | 白名单缓存过期时间 |

**使用场景**：
```
平台A（https://api.xxx.com/check）
├── 改写规则1：名称="严格库", 主叫改写=A1, 释放时间=1小时
├── 改写规则2：名称="宽松库", 主叫改写=A2, 释放时间=24小时
└── 改写规则3：名称="VIP数据", 主叫改写=A3, 释放时间=48小时
```

在拦截规则中，可以选择具体使用哪个改写规则，实现精细化控制。

#### 4.3 三级缓存机制

```
查询请求
↓
1. 查白名单Redis ← 之前查过，非黑名单 → 直接放行
↓ 未命中
2. 查黑名单Redis ← 之前查过，是黑名单 → 直接拦截
↓ 未命中
3. 调用第三方API ← 首次查询
↓
┌────────────┬────────────┐
正常放行 黑名单 超时/故障
↓ ↓ ↓
写入白名单 写入黑名单 只拦截本次
(有TTL过期) (永不过期) (不写缓存)
```

**缓存策略**：
- **白名单缓存**：有释放时间（TTL），过期后重新查询
- **黑名单缓存**：永久缓存，需手动清空
- **超时/故障**：只拦截本次，不写入缓存，避免误伤正常号码

#### 4.4 Redis 数据管理

| 数据类型 | 过期策略 | 统计方式 |
|---------|---------|---------|
| 三方白名单 | 有TTL（释放时间后自动过期） | 需手动点击统计（SCAN全量扫描） |
| 三方黑名单 | 永不过期 | 实时计数器（毫秒级响应） |

**管理功能**：
- **按需统计**：白名单需手动点击统计按钮（避免影响性能）
- **精确搜索**：输入号码查询是否在缓存中
- **清空数据**：需密码验证 + 二次确认（输入配置名称）
- **计数器校准**：对比快速统计与精确统计的差异

> 📸 *【此处插入第三方接口配置页面截图】*

> 📸 *【此处插入三方黑名单库页面截图】*

---

### 五、请求日志与统计

#### 请求记录查询

支持多条件组合筛选：
- 主叫号码（模糊匹配）
- 被叫号码（模糊匹配）
- 来源IP
- 处理状态（正常/靓号/地区/超频/黑名单/白名单/第三方成功/第三方失败/第三方超时/第三方故障）
- 黑名单等级
- 时间范围

每条记录包含：
- 请求时间
- 主叫/被叫号码
- 来源IP
- 处理结果
- 响应时间
- 匹配的规则
- 归属地信息（省份、城市、运营商）

#### 历史统计报表

- 每日请求量、通过量、拦截量
- 各拦截类型分布
- 支持日期范围汇总查询
- 数据来源：ClickHouse（支持海量数据分析）

#### 手机归属地查询

- 内置全国号段数据
- 支持单个/批量查询
- 返回：省份、城市、运营商、区号

> 📸 *【此处插入请求记录页面截图】*

---

### 六、质检系统对接

提供专用 API 供外部质检系统调用：

**安全机制**
- **Token 认证**：需携带专用 API Token
- **IP 白名单**：限制调用来源 IP

**接口特点**
- 固定导入等级：level=5（质检系统库）
- 支持批量导入，返回详细处理结果
- 异步处理，支持大批量数据

**返回信息**
- 导入记录ID
- 总数量、有效数量、重复数量、无效数量

---

### 七、系统管理

**登录认证**
- JWT Token 认证
- 支持 Token 自动刷新
- 修改密码后旧 Token 立即失效

**导出密码保护**
- 敏感操作（导出数据、删除配置）需验证密码
- 防止误操作和未授权访问

**来源等级配置**
- 自定义 6 个黑名单等级的名称
- 如：投诉库、质检库、手动添加、合作方数据等

**数据清理**
- 清理历史请求日志
- 可配置保留天数
- 释放存储空间

**智能报警**
- Redis/数据库异常时自动弹窗通知
- 降级状态实时感知
- 支持声音提醒

> 📸 *【此处插入系统设置页面截图】*

---

## 💡 项目亮点

1. **高性能**：单机支持万级 QPS，响应时间毫秒级
2. **多维拦截**：IP、号码、地区、运营商、靓号、超频、黑名单全覆盖
3. **灵活配置**：规则优先级 + 多条件组合，满足复杂业务需求
4. **第三方联动**：支持对接多个外部黑名单平台，多套数据统一管理，智能缓存减少API调用
5. **可视化监控**：仪表盘实时展示业务数据、服务器状态、Redis/数据库健康度
6. **全链路追踪**：每次请求可追溯，支持多维度筛选，问题快速定位
7. **安全防护**：JWT认证、密码保护、IP白名单，多重安全机制

---

## 📈 总结

本系统是一套**完整的企业级呼叫过滤解决方案**，从号码管理、规则配置、实时查询到监控报表，形成闭环。

**适用场景**：
- 电话营销公司
- 客服呼叫中心
- VoIP 运营商
- 需要号码过滤的任何电话业务

**核心价值**：
- 有效降低投诉率
- 保障线路稳定
- 减少封停风险
- 提升业务合规性