黑名单系统（智能拦截）是一款专为VOS3000通信平台设计的企业级呼叫管理系统。
系统通过8大核心拦截模块（本地黑名单、第三方黑名单、质检/外部推送、超频限制、靓号拦截、地区限制、私有白名单、IP白名单），
帮助企业有效防范骚扰电话、恶意呼叫和异常通信行为，显著提升通信质量和运营效率。
🏢 支持私有化部署，数据完全由企业自主掌控，确保通信数据安全和业务自主性。
系统支持超大规模数据管理（亿级黑名单记录），采用Go语言 + Redis集群分布式架构，
可承载20000+ QPS高并发查询，响应时间低至亚毫秒级。
💰 通过第三方API"抄库省钱"机制，可节省超过80%的API调用费用。
查一次付一次钱，用一辈子——查询结果永久缓存，重复查询零成本。
📊 提供专业级Dashboard监控仪表盘，实时展示QPS、响应时间、Redis状态、系统资源；
完整的查询日志和历史统计功能，支持全链路追踪和数据分析，是现代企业通信安全防护的理想选择。
📱
核心功能
私有黑名单
企业自主维护的核心黑白名单库。系统自动建立6个独立的等级库，
客户可以根据业务需求自定义每个等级的名称和用途（如"高危号码"、"疑似诈骗"、"营销骚扰"等），
实现灵活的号码分类管理。通过分布式缓存架构，确保查询速度达到亚毫秒级。
- 6个独立等级库：系统自动创建，客户可自定义每个等级的名称和描述
- 灵活分类管理：根据业务需求对号码进行精细化分类
- 亿级号码容量：支持海量数据存储，毫秒级查询响应
- 批量导入导出：支持Excel和CSV格式，含完整历史记录和批次撤销
🔗
省钱利器
第三方黑名单（智能缓存）
对接多个第三方黑名单API服务商，支持多三方顺序拦截，通过智能缓存机制将查询结果永久保存，
实现"查一次API，终身复用"，大幅降低API调用费用。
- 💰 多商家对接：同时配置多个第三方API服务商，灵活切换
- 🔄 多三方顺序拦截：一条规则可选择多个第三方接口，按①②③顺序依次调用，任一命中黑名单即拦截
- 🎯 分级缓存：白名单（安全号码）和黑名单（风险号码）分别缓存
- ♾️ 永久存储：一次查询后永久缓存（亿级数据容量），重复查询零成本
- ⚡ 只查缓存模式：可按接口开启"只查缓存"，缓存未命中时跳过API调用，零额外费用
- 💡 智能省钱：渐进式缓存，可节省80%以上的API费用
- 🔧 灵活管理：支持按商家查看、清除、统计缓存数据
📤
外部对接
质检/外部推送
支持质检系统、ASR转写、投诉系统等外部平台通过专用API将违规号码批量写入黑名单指定等级，实现与现有业务系统的无缝对接。
- 质检、ASR、投诉等系统通过专用API批量写入
- 可写入指定等级（如质检系统专用库）
- 支持单次大批量号码导入
- Token + IP白名单双重认证，保障安全
⚡
智能防护
超频限制
智能识别和拦截高频呼叫行为，有效防止恶意骚扰和资源滥用。
- 可配置时间窗口和次数阈值
- 支持主叫和被叫双向限制
- 实时计数和自动过期
- 分布式并发安全控制
💎
智能识别
靓号拦截
智能识别各类靓号模式，防止虚假号码和异常呼叫。
- 支持AAA、AABB、ABCD等模式
- 特殊靓号模式识别
- 可配置拦截模式组合
- 高性能模式匹配算法
🌍
精准控制
地区限制
基于手机号归属地的智能拦截，精准控制呼叫来源区域。
- 全国省市归属地数据
- 支持多地区组合限制
- 运营商信息识别
- 实时归属地查询
✅
优先放行
私有白名单
企业自主维护的VIP号码库，白名单号码优先放行，不受任何拦截规则限制。
- 优先级高于所有黑名单
- 内存缓存，O(1)查找
- 支持批量导入导出
- 适用于VIP客户保护
🔐
安全控制
IP白名单
限制哪些IP地址可以调用API接口，保障系统访问安全。
- 只有白名单IP可调用API
- 内存缓存，O(1)验证
- 支持多IP配置
- 拦截规则按IP匹配
💡 抄库省钱的核心逻辑（一句话版）
调用第三方API花钱查到的结果，存到自己的库里，下次查同一个号码就不用再花钱了
📱 同一个号码的查询过程
1️⃣
第一次查询
调用第三方API
💰 花钱
结果存入自己的库
2️⃣
第二次查询
直接查自己的库
🎉 免费
不调用第三方API
🔄
第N次查询
永远查自己的库
🎉 永远免费
查一次，用一辈子
结论：同一个号码无论被查多少次，只有第一次花钱，后面全部免费
✅
白名单缓存（安全号码）
触发条件：第三方API返回"不在黑名单"
缓存时间：可配置TTL（如72小时）
设计原因：安全号码可能变成危险号码，需要定期重新验证
❌
黑名单缓存（风险号码）
触发条件：第三方API返回"在黑名单"
缓存时间：永久存储，永不过期
设计原因：危险号码不会变安全，永久拦截最省钱
🎯 配置管理
1. 多商家对接：系统支持同时配置多个第三方黑名单API服务商，
每个商家可独立配置API地址、超时时间、主叫号码等参数。不同规则可以使用不同的商家，实现灵活的策略组合。
2. 主叫改写：每个第三方商家可配置多个"主叫改写规则"，使用不同的主叫号码查询不同号段，
实现精细化的查询策略。系统会自动匹配最合适的改写规则进行查询。
📊 分级查询与存储流程
📱 同一号码在不同等级的查询结果示例
传统方案中，要实现多个第三方黑名单的顺序检查，往往需要部署多套VOS或在多个节点配置规则，运维复杂且难以追踪。
本系统的多层三方拦截功能，一条规则即可选择多个第三方接口，按 ①②③ 的顺序依次调用，
并且每一步的调用结果都完整记录在请求日志中，实现全链路可追踪。
⚙️ 核心调用机制
①
规则配置
在拦截规则中勾选多个第三方接口，点击顺序即为调用优先级。
系统自动标记 ①②③ 序号，一眼看清调用先后。
②
顺序执行
呼叫进入时，按 ①→②→③ 顺序依次检查。
每个第三方先查缓存，未命中再调API。任一命中黑名单即立即拦截，不再继续后续调用。
③
全链路记录
每次请求的完整调用链路记录在日志中：经过了哪些第三方、每个是缓存命中还是调了API、
最终结果是放行还是拦截，全部一目了然。
📋 多层调用顺序示意
📝 规则配置示例：规则 "深圳线路" 选择了4个第三方
①天盾风控
→
②云衡检测
→
③星盾数据
→
④锐信号码
1
①天盾风控 → 查白名单缓存 → 命中 ✅
缓存中已有安全记录，直接标记为通过，不花钱
2
②云衡检测 → 查黑名单缓存 → 命中 ❌ → 拦截
缓存中发现黑名单记录，立即拦截，不再继续后续调用
3
③星盾数据 → 已被拦截，跳过
第②步已命中黑名单，后续接口不再调用
4
④锐信号码 → 已被拦截，跳过
第②步已命中黑名单，后续接口不再调用
❌ 最终结果：拦截（第②步命中黑名单，③④不再调用）
⏭️ "只查缓存"模式
⏭️ 什么是"只查缓存"？
在三方接口管理 → 主叫改写管理中，每个调用方改写都有一个"只查缓存"开关。
开启后，该接口在检查时只查本地缓存：
• 缓存命中 → 正常判断（黑名单拦截/白名单放行）
• 缓存未命中 → 跳过，不调API（零费用）
💡 适用场景
1. 已积累大量缓存：某个第三方已运行数月，缓存覆盖率很高，
不想再花钱调API，只复用已有缓存数据。
2. 备用接口：作为后备第三方，仅在缓存命中时生效，
避免产生额外费用。
3. 成本精细控制：对不同接口采取不同策略，
核心接口正常调API，辅助接口只查缓存。
📋 请求记录 - 三方拦截列
每条请求记录都完整展示了三方拦截的调用链路和数据来源，用彩色标签一眼区分
📌 实际展示示例：
全部API：
①天盾风控 API
→
②云衡检测 API
→
③星盾数据 API
缓存命中：
①天盾风控 缓存
→
②云衡检测 缓存
→
③星盾数据 API
只查缓存：
①天盾风控 缓存
→
②云衡检测 缓存
→
③星盾数据 noAPI
命中拦截：
①天盾风控 缓存
→
②云衡检测 缓存
→
③星盾数据 API
绿色标签=正常通过 · 红色标签=命中拦截 | 蓝色=调了API · 橙色=缓存命中 · 青色=只查缓存跳过
📊 API调用统计
📈 功能说明
在三方接口管理页面的"调用统计"Tab中，可以查看每个第三方接口每天实际调用了多少次API。
这里统计的是真正花钱的API调用次数，不包含缓存命中的次数。
🔍 查询维度
• 按日期范围：选择起止日期查看期间的调用统计
• 按接口筛选：选择特定第三方接口查看单独统计
• 分页浏览：支持分页查看大量数据
💡 实用价值：通过调用统计可以精确计算每月的API费用，
对比缓存命中率变化趋势，评估省钱效果
🤝 黑名单联盟 — 多层拦截的进阶玩法
💡 核心思路
多层三方拦截不仅能串联收费API，还能组建"黑名单联盟"。
如果你的朋友也部署了这套系统，各自都积累了大量的缓存数据（黑名单库），
那么可以把朋友的系统作为"第三方接口"配置进来，放在收费API前面。
查询时先在联盟伙伴的库里查（免费），都查不到再调收费API——进一步降低费用。
📋 黑名单联盟配置示例
①联盟·张总 🆓
→
②联盟·李总 🆓
→
③联盟·王总 🆓
→
④收费三方API 💰
1
①联盟·张总
— 查联盟伙伴张总积累的数据，免费
2
②联盟·李总
— 张总那没查到，继续查联盟伙伴李总的数据，免费
3
③联盟·王总
— 李总那也没查到，继续查联盟伙伴王总的数据，免费
4
④收费三方API
— 联盟伙伴都没查到，才调收费API，花钱
效果：联盟伙伴越多 → 前置免费库越全 → 需要调收费API的次数越少 → 省得越多
🔄
数据互补
不同伙伴的业务场景不同，积累的号码库各有侧重，联盟后覆盖率远高于单个库
💰
成本分摊
每个伙伴各自积累数据、各自付费，通过联盟实现数据共享，大家一起省钱
📈
滚雪球效应
加入联盟的伙伴越多，免费前置库越大，收费API调用越少，整个联盟一起受益
🎯 多层三方拦截的核心价值
1. 运维简化：一条规则实现多层第三方过滤，无需部署多套VOS或配置多个节点。
2. 精细管控：每个第三方接口可独立配置"只查缓存"，核心接口调API、辅助接口只用缓存，费用精准控制。
3. 黑名单联盟：把联盟伙伴的系统作为免费前置库，收费API放最后，伙伴越多省得越多。
4. 全链路追踪：请求记录中完整展示每一步的调用结果和数据来源（API/缓存/跳过），排查问题一目了然。
5. 费用透明：调用统计按天、按接口精确统计API调用次数，费用账单清清楚楚。
6. 灵活组合：不同规则可使用不同的第三方组合和顺序，满足多种业务场景需求。
传统方案中，每次查询都要调用第三方API付费，同一个号码被查100次就付100次钱。
本系统通过智能缓存机制，将每次查询结果永久存储在本地，
同一个号码只有第一次花钱，后续查询全部免费，随着时间推移，缓存覆盖率逐步提升，API费用逐月下降。
📈 缓存命中率随使用量递增
缓存命中率取决于查询量，查得越多，缓存积累越快，命中率越高
📊 传统方案（无缓存）
每次查询都调用第三方API
同一个号码查N次 = 付N次钱
费用 = 查询总量 × 单价
🚀 智能缓存方案（本系统）
首次查询调API，结果永久缓存
同一个号码只花1次钱
费用 = 不重复号码数 × 单价
缓存稳定后
节省 80% 以上
的第三方API调用费用
用得越久，缓存越全，省得越多 · 这些缓存数据就是企业的数据资产
💡 省钱原理
• 核心逻辑：通信行业中，号码的重复查询率极高，大量呼叫会反复查询同一批号码
• 渐进积累：系统运行时间越长，缓存覆盖的号码越多，需要调API的次数就越少
• 永久存储：黑名单结果永久缓存不过期，白名单结果可配置过期时间定期重新验证
• 数据资产：积累的缓存数据就是企业的核心资产，形成正向循环——用得越久，省得越多
🖥️
单机部署
适合中小规模应用
快速部署，资源占用低
支持20000+ QPS
适合测试和小型业务
🌐
集群部署
高可用架构
自动故障转移，负载均衡
支持20000+ QPS
适合大规模生产环境
🖥️ 服务器硬件要求
⚙️ 最低配置
CPU 核心
16核
CPU 型号
E5-2680 v3
硬盘
300G SSD
适合小型和中型业务
⭐ 推荐
🚀 推荐配置
CPU 核心
32核
CPU 型号
Gold 6133
硬盘
500G SSD
适合生产环境和大规模业务
🐧 系统版本要求
Rocky Linux 9.7 (X86 minimal)
建议使用最小化安装，后续根据需要安装必要组件
📌 配置说明
• 根据业务规模选择：日均查询量小于2000万次可使用最低配置，超过2000万次建议使用推荐配置
• 存储空间：SSD硬盘保证高速读写性能，建议预留足够空间存储日志和缓存数据
• CPU性能：高频率多核心CPU能显著提升并发处理能力和查询响应速度
• 内存容量：足够的内存可缓存更多热点数据，提升查询命中率和响应速度
• 网络带宽：建议千兆网卡，确保高并发场景下的网络IO性能
📊 Dashboard仪表盘
系统提供专业级的实时监控仪表盘，帮助运维人员全面掌握系统运行状态：
⚡
QPS监控
当前QPS
峰值QPS
平均QPS
⏱️
响应时间
平均响应时间
P95/P99延迟
最大响应时间
🗄️
Redis监控
多实例状态
内存使用率
主从同步状态
💻
系统资源
CPU/内存使用
磁盘IO
网络流量
📁 数据管理功能
完善的数据管理能力，支持全链路追踪和历史数据分析：
📋
查询日志
- ✓ 每次请求完整记录
- ✓ 拦截原因追踪
- ✓ 响应时间统计
- ✓ 支持多条件筛选
- ✓ 可配置保留天数
📈
历史统计
- ✓ 每日查询/拦截统计
- ✓ 多维度数据分析
- ✓ 趋势图表展示
- ✓ 拦截类型分布
- ✓ 第三方调用统计
🔍
批量查询
- ✓ 批量检查号码状态
- ✓ 返回命中等级信息
- ✓ 支持API调用
- ✓ 高效并发处理
- ✓ Web界面可视化
📊 三方缓存统计
实时查看每个第三方商家的缓存数据：白名单数量、黑名单数量、缓存命中率。
支持按商家查看、清除、导出缓存数据，方便运维管理和成本核算。
🔌 质检系统API接口
系统提供专用的外部API接口，允许质检系统、ASR转写系统等外部平台将违规号码实时推送到黑名单库：
📡 能力说明
提供专用 API，供质检、ASR、投诉等系统将违规号码批量写入黑名单；支持写入指定等级（如质检系统专用库），单次支持大批量导入。具体接口以实际系统文档为准。
写入等级：
可写入指定等级（如 质检系统库）
批量能力：
支持单次大批量号码导入
🔐 双重安全认证
1
Token认证
URL参数携带系统分配的API Token
🎯 典型应用场景
质检系统 → 发现违规录音 → 自动推送号码到黑名单
ASR转写系统 → 识别敏感词 → 自动推送号码到黑名单
投诉系统 → 收到投诉 → 自动推送号码到黑名单
⚡
超高性能
采用Go语言 + FastHTTP + Redis集群，支持20000+ QPS，
响应时间低至亚毫秒级，内存缓存O(1)查找，轻松应对高并发场景。
🔒
高可靠性
分布式架构，Redis主从复制，自动故障转移，
数据多副本保护，系统可用性达99.99%，保障业务连续性。
💰
抄库省钱
第三方API智能缓存，可节省80%以上的调用费用！
查一次付一次钱，用一辈子。缓存稳定后命中率可达95%以上。
📊
全链路监控
Dashboard仪表盘实时展示QPS、响应时间、Redis状态、系统资源。
查询日志全链路追踪，历史统计数据可视化分析。
🎯
灵活规则
8大拦截模块自由组合：本地黑名单、第三方黑名单、质检/外部推送、超频限制、
靓号拦截、地区限制、私有白名单、IP白名单。按IP和前缀精准匹配。
支持多三方顺序拦截和只查缓存模式，一条规则实现多层过滤。
📈
可扩展性
水平扩展能力，支持单机和集群部署，亿级黑名单数据容量。
可根据业务增长动态调整资源，平滑升级无需停机。
🖥️
易于使用
现代化Web管理界面（React + Ant Design），无需专业培训即可上手。
批量导入导出，API接口完善，响应式设计支持移动端访问。
🏢
私有化部署
数据完全由企业自主掌控，确保通信数据安全和业务自主性。
开源技术栈无授权费用，RPM一键部署，降低运维成本。
