mm_ip

Language: 中文 | English

一个功能强大的IP管理模块，支持白名单、黑名单管理、IP请求频率监控、违规记录和持久化存储。

功能特性

• ✅ 白名单管理 - 支持添加、删除、查询白名单IP
• ✅ 黑名单管理 - 支持添加、删除、查询黑名单IP，支持自动过期
• ✅ IP请求频率监控 - 实时监控IP请求频率，防止高频访问
• ✅ 自动拉黑机制 - 支持高频访问自动拉黑和违规次数超限自动拉黑
• ✅ 违规记录系统 - 记录IP违规行为，支持违规次数统计和重置
• ✅ 持久化存储 - 支持数据分文件存储（白名单、黑名单、违规记录独立存储）
• ✅ 自动保存机制 - 支持定时自动保存和操作触发保存
• ✅ 重启数据恢复 - 支持重启后自动加载持久化数据
• ✅ 灵活配置 - 支持自定义各种阈值和参数

安装

npm install mm_ip

快速开始

基本使用

const { Ip } = require('mm_ip');

// 创建IP管理实例
const ip_manager = new Ip();

// 设置日志器（可选）
ip_manager.setup(console);

// 添加白名单IP
ip_manager.addWhite('192.168.1.100');

// 添加黑名单IP
ip_manager.addBlack('10.0.0.100');

// 检查IP状态
console.log('192.168.1.100 在白名单:', ip_manager.isWhite('192.168.1.100'));
console.log('10.0.0.100 在黑名单:', ip_manager.isBlack('10.0.0.100'));

// 记录IP请求
console.log('192.168.1.100 请求结果:', ip_manager.record('192.168.1.100'));

持久化存储配置

// 创建带持久化配置的实例
const persistent_ip = new Ip({
    dir: './cache/ip', // 存储目录
    max_white: 1000,   // 最大白名单数量
    max_black: 1000    // 最大黑名单数量
});

// 添加数据后会自动保存到文件
persistent_ip.addWhite('192.168.1.101');
persistent_ip.addBlack('10.0.0.101');

// 重启后自动加载数据
const new_ip = new Ip({ dir: './cache/ip' });
console.log('重启后白名单数量:', new_ip.getAllWhite().length);

API文档

构造函数

new Ip(config)

配置参数 (config):

| 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | max_white | number | 1000 | 最大白名单数量 | | max_black | number | 1000 | 最大黑名单数量 | | check_interval | number | 60000 | 检查间隔（毫秒） | | max_req_per_min | number | 100 | 每分钟最大请求数 | | auto_black_enable | boolean | true | 启用自动高频拉黑 | | auto_black_threshold | number | 50 | 自动拉黑阈值 | | auto_black_duration | number | 3600000 | 自动拉黑持续时间（毫秒） | | violation_enable | boolean | true | 启用违规记录 | | violation_max_count | number | 10 | 最大违规次数 | | violation_reset_time | number | 86400000 | 违规记录重置时间（毫秒） | | violation_auto_black | boolean | true | 违规次数超限自动拉黑 | | dir | string | './cache/ip' | 持久化存储目录 |

主要方法

白名单操作

• addWhite(ip) - 添加白名单IP
• delWhite(ip) - 删除白名单IP
• isWhite(ip) - 检查是否在白名单
• getAllWhite() - 获取所有白名单IP
• clearWhite() - 清空白名单

黑名单操作

• addBlack(ip) - 添加黑名单IP
• delBlack(ip) - 删除黑名单IP
• isBlack(ip) - 检查是否在黑名单
• getAllBlack() - 获取所有黑名单IP
• clearBlack() - 清空黑名单
• getBlackExpireTime(ip) - 获取黑名单过期时间

IP请求记录

• record(ip) - 记录IP请求，返回是否允许访问
• getReqCount(ip) - 获取IP请求次数
• getReqFreq(ip) - 获取IP请求频率

违规记录

• recordViolation(ip, reason) - 记录IP违规
• getViolationCount(ip) - 获取违规次数
• resetViolation(ip) - 重置违规记录
• clearViolations() - 清空所有违规记录
• getAllViolations() - 获取所有违规记录

持久化存储

• save() - 手动保存数据
• load() - 手动加载数据
• autoSave(interval) - 开启自动保存
• stopAutoSave() - 停止自动保存

综合操作

• del(ip) - 删除IP的所有记录
• setup(logger) - 设置日志器

存储文件结构

当启用持久化存储时，数据会分三个文件存储：

cache/ip/
├── white.json      # 白名单数据
├── black.json      # 黑名单数据
└── violation.json  # 违规记录数据

每个文件包含对应的数据数组和时间戳信息。

测试

运行测试用例：

npm test

或直接运行：

node test.js

许可证

ISC License

作者

qww

仓库地址

• Gitee: https://gitee.com/qiuwenwu91/mm_ip.git
• npm: https://www.npmjs.com/package/mm_ip