# 超级美眉-IP管理

**Repository Path**: qiuwenwu91/mm_ip

## Basic Information

- **Project Name**: 超级美眉-IP管理
- **Description**: 用于管理IP名单，可设置白名单、黑名单和IP检查，查询IP请求次数、频率等。
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-09
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mm_ip

**Language:** [中文](./README.md) | [English](./README_EN.md)

---

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

## 功能特性

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

## 安装

```bash
npm install mm_ip
```

## 快速开始

### 基本使用

```javascript
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'));
```

### 持久化存储配置

```javascript
// 创建带持久化配置的实例
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文档

### 构造函数

```javascript
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  # 违规记录数据
```

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

## 测试

运行测试用例：

```bash
npm test
```

或直接运行：

```bash
node test.js
```

## 许可证

ISC License

## 作者

qww

## 仓库地址

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