mm_ip 1.0.7 → 1.0.9

package/index.js

@@ -1,1333 +1,18 @@
-/**
- * IP管理模块
- * @file IP管理模块，支持白名单、黑名单管理，IP请求频率和次数记录
- */
-require('mm_expand');
+const IP = require('ip');
+const Admin = require('mm_corejs').Admin;
+const { Ip } = require('./lib/ip.js');
 
-/**
- * IP管理类
- * @class
- */
-class Ip {
-	static config = {
-		max_white: 1000,
-		max_black: 1000,
-		check_interval: 60000, // 1分钟
-		max_req_per_min: 100,
-		auto_black_enable: true, // 启用自动高频拉黑
-		auto_black_threshold: 50, // 自动拉黑阈值（每分钟请求数）
-		auto_black_duration: 3600000, // 自动拉黑持续时间（1小时）
-		auto_black_grace_count: 3, // 自动拉黑宽限次数，连续触限达到该次数后才拉黑
-		violation_enable: true, // 启用违规记录
-		violation_max_count: 10, // 最大违规次数
-		violation_reset_time: 86400000, // 违规记录重置时间（24小时）
-		violation_auto_black: true, // 违规次数超限自动拉黑
-		region_check_enable: true, // 启用国外IP检测
-		region_checker: null, // IP地区检测函数 (ip) => { country: 'CN' }，支持同步或异步
-		region_cache_time: 86400000, // 地区检测结果缓存时间（24小时）
-		os_black_enable: false, // 启用系统级拉黑联动（需管理员权限，默认关闭避免误拦截）
-		os_rule_prefix: 'mm_ip_black_', // 系统防火墙规则名前缀
-		dir: './cache/ip' // 持久化存储目录
-	}
-	/**
-	 * 创建IP管理实例
-	 * @param {Object} config - 配置选项
-	 */
-	constructor(config) {
-		this._config = Object.assign({}, Ip.config);
-
-		this._white = new Set();
-		this._black = new Set();
-		this._req_count = new Map();
-		this._req_time = new Map();
-		this._req_start = new Map(); // 请求窗口开始时间
-		this._black_time = new Map(); // 记录拉黑时间
-		this._violation_count = new Map(); // 违规次数记录
-		this._violation_time = new Map(); // 违规时间记录（首次违规时间）
-		this._violation_flagged = new Map(); // 同一请求窗口违规标记
-		this._region_cache = new Map(); // IP地区检测结果缓存
-		this._logger = $.log || console;
-
-		this.setConfig(config);
-		// 默认使用ip2region作为地区检测器
-		if (!this._config.region_checker && this._config.region_check_enable) {
-			this._initIp2Region();
-		}
-		// 自动加载持久化数据
-		if (this._config.dir) {
-			this.load();
-		}
-	}
-}
-
-/**
- * 设置配置选项
- * @param {Object} config - 配置选项
- */
-Ip.prototype.setConfig = function(config) {
-	if (config) {
-		Object.assign(this._config, config);
-	}
-}
-
-/**
- * 设置日志器
- * @param {Object} logger - 日志对象
- */
-Ip.prototype.init = function(logger) {
-	if (logger) {
-		this._logger = logger;
-	}
-};
-
-/**
- * 日志记录
- * @param {string} level - 日志级别（如：info, warn, error）
- * @param {string} message - 日志消息
- * @param {...*} args - 可选的日志参数
- */
-Ip.prototype.log = function(level, message, ...args) {
-	this._logger[level](`${this.constructor.name} ${message}`, ...args);
-};
-
-/**
- * 添加IP到白名单
- * @param {string} ip - IP地址
- * @returns {boolean} 是否添加成功
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.addWhite = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	if (this.getAllWhite().length >= this._config.max_white) {
-		this.log('warn', '白名单已满，无法添加IP:', ip);
-		return false;
-	}
-
-	this._white.add(ip);
-
-	// 自动保存到持久化存储
-	if (this._config.dir) {
-		this.save();
-	}
-
-	return true;
-};
-
-/**
- * 添加IP到黑名单
- * @param {string} ip - IP地址
- * @returns {boolean} 是否添加成功
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.addBlack = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	if (this.getAllBlack().length >= this._config.max_black) {
-		this.log('warn', '黑名单已满，无法添加IP:', ip);
-		return false;
-	}
-
-	this._black.add(ip);
-	this.log('info', '添加黑名单IP:', ip);
-
-	// 系统级联动拉黑
-	if (this._config.os_black_enable) {
-		this.osBlack(ip);
-	}
-
-	// 自动保存到持久化存储
-	if (this._config.dir) {
-		this.save();
-	}
-
-	return true;
-};
-
-/**
- * 从白名单删除IP
- * @param {string} ip - IP地址
- * @returns {boolean} 是否删除成功
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.delWhite = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const result = this._white.delete(ip);
-	if (result) {
-		this.log('info', '删除白名单IP:', ip);
-
-		// 自动保存到持久化存储
-		if (this._config.dir) {
-			this.save();
-		}
-	}
-	return result;
-};
-
-/**
- * 从黑名单删除IP
- * @param {string} ip - IP地址
- * @returns {boolean} 是否删除成功
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.delBlack = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const result = this._black.delete(ip);
-	if (result) {
-		this.log('info', '删除黑名单IP:', ip);
-
-		// 系统级联动释放
-		if (this._config.os_black_enable) {
-			this.osUnblack(ip);
-		}
-
-		// 自动保存到持久化存储
-		if (this._config.dir) {
-			this.save();
-		}
-	}
-	return result;
-};
-
-/**
- * 检查IP是否在白名单
- * @param {string} ip - IP地址
- * @returns {boolean} 是否在白名单
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.isWhite = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	return this._white.has(ip);
-};
-
-/**
- * 检查IP是否在黑名单
- * @param {string} ip - IP地址
- * @returns {boolean} 是否在黑名单
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.isBlack = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	return this._black.has(ip);
-};
-
-/**
- * 记录IP请求
- * @param {string} ip - IP地址
- * @returns {boolean} 是否允许请求
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.record = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	// 检查黑名单（包括过期检查）
-	if (this.isBlack(ip)) {
-		// 检查是否过期
-		if (this._isBlackExpired(ip)) {
-			this.delBlack(ip);
-		} else {
-			this.log('warn', '黑名单IP请求被拒绝:', ip);
-			// 记录违规：黑名单IP尝试访问
-			if (this._config.violation_enable) {
-				this.recordViolation(ip, '黑名单IP尝试访问');
-			}
-			return false;
-		}
-	}
-
-	// 内网IP豁免：不参与限流、违规与地区检测，避免误拉黑内网访问
-	if (this._isPrivate(ip)) {
-		this._updateReqCount(ip);
-		return true;
-	}
-
-	// 白名单直接通过
-	if (this.isWhite(ip)) {
-		this._updateReqCount(ip);
-		return true;
-	}
-
-	// 国外IP检测：检测到国外IP自动拉黑
-	if (this._config.region_check_enable && this._checkForeign(ip)) {
-		return false;
-	}
-
-	// 检查频率限制
-	if (!this._checkRateLimit(ip)) {
-		this.log('warn', 'IP请求频率超限:', ip);
-		const rate = this.getReqRate(ip);
-
-		// 同一请求窗口只记一次违规，避免连续请求导致违规次数暴涨
-		if (this._config.violation_enable) {
-			const flag_time = this._violation_flagged.get(ip);
-			const win_start = this._req_start.get(ip);
-			if (flag_time !== win_start) {
-				this.recordViolation(ip, '请求频率超限');
-				this._violation_flagged.set(ip, win_start);
-			}
-		}
-
-		// 达到宽限次数且频率超阈值才自动拉黑
-		if (this._config.auto_black_enable
-			&& rate >= this._config.auto_black_threshold
-			&& this.getViolationCount(ip) >= this._config.auto_black_grace_count) {
-			this._autoBlack(ip);
-			return false;
-		}
-
-		// 重置计数窗口（软限流），下一次请求重新计数
-		this._req_start.set(ip, Date.now());
-		this._req_count.set(ip, 0);
-
-		return false;
-	}
-
-	this._updateReqCount(ip);
-	return true;
-};
-
-/**
- * 获取IP请求次数
- * @param {string} ip - IP地址
- * @returns {number} 请求次数
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.getReqCount = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	return this._req_count.get(ip) || 0;
-};
-
-/**
- * 获取IP请求频率（每分钟请求数）
- * @param {string} ip - IP地址
- * @returns {number} 请求频率（每分钟请求数）
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.getReqRate = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const now = Date.now();
-	const start = this._req_start.get(ip) || now;
-	const count = this._req_count.get(ip) || 0;
-
-	// 当前窗口已过期，频率为0
-	if (now - start >= this._config.check_interval) {
-		return 0;
-	}
-
-	// 按窗口换算为每分钟请求数，不做时间外推
-	return Math.round((count / this._config.check_interval) * 60000);
-};
-
-/**
- * 获取所有IP的请求统计信息
- * @returns {Object} IP统计信息对象
- */
-Ip.prototype.getAllStats = function() {
-	const stats = {};
-	const now = Date.now();
-
-	// 收集所有有请求记录的IP
-	for (const ip of this.getAllReqIps()) {
-		const lastTime = this._req_time.get(ip) || now;
-		const isActive = now - lastTime < this._config.check_interval;
-
-		stats[ip] = {
-			count: this.getReqCount(ip),
-			rate: isActive ? this.getReqRate(ip) : 0,
-			last_time: lastTime,
-			is_white: this.isWhite(ip),
-			is_black: this.isBlack(ip),
-			black_time: this.getBlackExpireTime(ip)
-		};
-	}
-
-	return stats;
-};
-
-/**
- * 获取所有白名单IP
- * @returns {Array} 白名单IP数组
- */
-Ip.prototype.getAllWhite = function() {
-	return Array.from(this._white);
-};
-
-/**
- * 获取所有黑名单IP
- * @returns {Array} 黑名单IP数组
- */
-Ip.prototype.getAllBlack = function() {
-	return Array.from(this._black);
-};
-
-/**
- * 获取所有有请求记录的IP
- * @returns {Array} 有请求记录的IP数组
- */
-Ip.prototype.getAllReqIps = function() {
-	return Array.from(this._req_count.keys());
-};
-
-/**
- * 清空白名单
- */
-Ip.prototype.clearWhite = function() {
-	this._white.clear();
-	this.log('info', '清空白名单');
-
-	// 自动保存到持久化存储
-	if (this._config.dir) {
-		this.save();
-	}
-};
-
-/**
- * 清空黑名单
- */
-Ip.prototype.clearBlack = function() {
-	this._black.clear();
-	this.log('info', '清空黑名单');
-
-	// 自动保存到持久化存储
-	if (this._config.dir) {
-		this.save();
-	}
-};
-
-/**
- * 清空所有请求记录
- */
-Ip.prototype.clearReq = function() {
-	this._req_count.clear();
-	this._req_time.clear();
-	this._req_start.clear();
-	this.log('info', '清空请求记录');
-};
-
-/**
- * 检查IP请求频率限制（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @returns {boolean} 是否允许请求
- */
-Ip.prototype._checkRateLimit = function(ip) {
-	const now = Date.now();
-	let start = this._req_start.get(ip);
-
-	// 无窗口或窗口已过期，开启新窗口并重置计数
-	if (start === undefined || now - start >= this._config.check_interval) {
-		start = now;
-		this._req_start.set(ip, start);
-		this._req_count.set(ip, 0);
-	}
-
-	const count = this._req_count.get(ip) || 0;
-	return count < this._config.max_req_per_min;
-};
-
-/**
- * 更新IP请求计数（私有方法）
- * @private
- * @param {string} ip - IP地址
- */
-Ip.prototype._updateReqCount = function(ip) {
-	if (this._req_start.get(ip) === undefined) {
-		this._req_start.set(ip, Date.now());
-	}
-
-	const count = this.getReqCount(ip) + 1;
-	this._req_count.set(ip, count);
-	this._req_time.set(ip, Date.now());
-};
-
-/**
- * 验证IP格式（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @returns {boolean} 是否有效IP
- */
-Ip.prototype._validIp = function(ip) {
-	const ipRegex = /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/;
-	return ipRegex.test(ip);
-};
-
-/**
- * 判断IP是否为内网/回环地址（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @returns {boolean} 是否为内网IP
- */
-Ip.prototype._isPrivate = function(ip) {
-	const parts = ip.split('.');
-	if (parts.length !== 4) return false;
-
-	const first = parseInt(parts[0], 10);
-	const second = parseInt(parts[1], 10);
-
-	// 回环 127.0.0.0/8、A类 10.0.0.0/8、B类 172.16.0.0/12、C类 192.168.0.0/16
-	if (first === 127) return true;
-	if (first === 10) return true;
-	if (first === 172 && second >= 16 && second <= 31) return true;
-	if (first === 192 && second === 168) return true;
-
-	return false;
-};
-
-/**
- * 批量添加IP到白名单
- * @param {Array} ip_list - IP地址数组
- * @returns {number} 成功添加的数量
- */
-Ip.prototype.addWhiteBatch = function(ip_list) {
-	if (!Array.isArray(ip_list)) throw new TypeError('ip_list must be array');
-
-	let success = 0;
-	for (const ip of ip_list) {
-		if (typeof ip === 'string' && this._validIp(ip)) {
-			if (this.addWhite(ip)) {
-				success++;
-			}
-		}
-	}
-	return success;
-};
-
-/**
- * 批量添加IP到黑名单
- * @param {Array} ip_list - IP地址数组
- * @returns {number} 成功添加的数量
- */
-Ip.prototype.addBlackBatch = function(ip_list) {
-	if (!Array.isArray(ip_list)) throw new TypeError('ip_list must be array');
-
-	let success = 0;
-	for (const ip of ip_list) {
-		if (typeof ip === 'string' && this._validIp(ip)) {
-			if (this.addBlack(ip)) {
-				success++;
-			}
-		}
-	}
-	return success;
-};
-
-/**
- * 手动高频拉黑IP
- * @param {string} ip - IP地址
- * @param {number} duration - 拉黑持续时间（毫秒）
- * @returns {boolean} 是否拉黑成功
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.blackByHighFreq = function(ip, duration) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const black_duration = duration || this._config.auto_black_duration;
-
-	if (this.addBlack(ip)) {
-		this._black_time.set(ip, Date.now() + black_duration);
-		this.log('warn', '手动高频拉黑IP:', ip, '持续时间:', black_duration + 'ms');
-		return true;
-	}
-
-	return false;
-};
-
-/**
- * 检查并清理过期的黑名单IP（私有方法）
- * @private
- */
-Ip.prototype._cleanExpiredBlack = function() {
-	const now = Date.now();
-	const expired = [];
-
-	// 获取所有有过期时间的黑名单IP
-	for (const ip of this.getAllBlack()) {
-		const expireTime = this.getBlackExpireTime(ip);
-		if (expireTime && now > expireTime) {
-			expired.push(ip);
-		}
-	}
-
-	for (const ip of expired) {
-		this.delBlack(ip);
-		this._black_time.delete(ip);
-	}
-};
-
-/**
- * 检查黑名单是否过期（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @returns {boolean} 是否过期
- */
-Ip.prototype._isBlackExpired = function(ip) {
-	const expireTime = this.getBlackExpireTime(ip);
-	if (!expireTime) return false; // 没有设置过期时间，永不过期
-
-	return Date.now() > expireTime;
-};
-
-/**
- * 自动拉黑IP（私有方法）
- * @private
- * @param {string} ip - IP地址
- */
-Ip.prototype._autoBlack = function(ip) {
-	if (this.addBlack(ip)) {
-		this._black_time.set(ip, Date.now() + this._config.auto_black_duration);
-		this.log('warn', '自动高频拉黑IP:', ip,
-			'频率:', this.getReqRate(ip) + '/分钟',
-			'持续时间:', this._config.auto_black_duration + 'ms');
-	}
-};
-
-/**
- * 获取黑名单过期时间
- * @param {string} ip - IP地址
- * @returns {number|null} 过期时间戳（毫秒），null表示永不过期
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.getBlackExpireTime = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	if (!this.isBlack(ip)) return null;
-
-	const expireTime = this._black_time.get(ip);
-	return expireTime || null;
-};
-
-/**
- * 清理所有过期的黑名单IP
- * @returns {number} 清理的数量
- */
-Ip.prototype.cleanExpiredBlack = function() {
-	const beforeCount = this.getAllBlack().length;
-	this._cleanExpiredBlack();
-	return beforeCount - this.getAllBlack().length;
-};
-
-/**
- * 记录IP违规。
- * @param {string} ip - IP地址
- * @param {string} reason - 违规原因
- * @returns {number} 当前违规次数
- */
-Ip.prototype.recordViolation = function(ip, reason) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	if (!this._config.violation_enable) return 0;
-
-	this._cleanExpiredViolation();
-
-	const now = Date.now();
-	const count = this.getViolationCount(ip) + 1;
-
-	// 记录首次违规时间，用于违规窗口重置
-	if (!this._violation_time.has(ip)) {
-		this._violation_time.set(ip, now);
-	}
-	this._violation_count.set(ip, count);
-
-	// 检查是否达到自动拉黑条件
-	if (this._config.violation_auto_black && count >= this._config.violation_max_count) {
-		this.blackByHighFreq(ip, this._config.auto_black_duration);
-		this.log('warn', 'IP因违规次数超限自动拉黑:', {
-			ip,
-			count,
-			duration: this._config.auto_black_duration
-		});
-	}
-
-	return count;
-};
-
-/**
- * 获取IP违规次数。
- * @param {string} ip - IP地址
- * @returns {number} 违规次数
- */
-Ip.prototype.getViolationCount = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	this._cleanExpiredViolation();
-	return this._violation_count.get(ip) || 0;
-};
-
-/**
- * 重置IP违规记录。
- * @param {string} ip - IP地址
- * @returns {boolean} 是否成功重置
- */
-Ip.prototype.resetViolation = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const hadRecord = this._violation_count.has(ip);
-	this._violation_count.delete(ip);
-	this._violation_time.delete(ip);
-
-	return hadRecord;
-};
-
-/**
- * 获取所有有违规记录的IP
- * @returns {Array} 有违规记录的IP数组
- */
-Ip.prototype.getAllViolationIps = function() {
-	return Array.from(this._violation_count.keys());
-};
-
-/**
- * 获取IP违规详细信息
- * @param {string} ip - IP地址
- * @returns {Object|null} 违规信息
- */
-Ip.prototype.getViolationInfo = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const count = this.getViolationCount(ip);
-	if (count === 0) return null;
-
-	return {
-		count: count,
-		time: this._violation_time.get(ip) // 首次违规时间
-	};
-};
-
-/**
- * 获取所有IP违规统计信息。
- * @returns {Object} 违规统计信息
- */
-Ip.prototype.getAllViolations = function() {
-	this._cleanExpiredViolation();
-
-	const violations = {};
-	for (const ip of this.getAllViolationIps()) {
-		violations[ip] = this.getViolationInfo(ip);
-	}
-
-	return violations;
-};
-
-/**
- * 清理过期的违规记录（私有方法）
- * @private
- */
-Ip.prototype._cleanExpiredViolation = function() {
-	const now = Date.now();
-	const expired = [];
-
-	// 直接访问内部数据结构避免递归调用
-	for (const [ip, time] of this._violation_time) {
-		if (now - time > this._config.violation_reset_time) {
-			expired.push(ip);
-		}
-	}
-
-	for (const ip of expired) {
-		this._violation_count.delete(ip);
-		this._violation_time.delete(ip);
-	}
-};
-
-/**
- * 清空所有违规记录
- */
-Ip.prototype.clearViolations = function() {
-	this._violation_count.clear();
-	this._violation_time.clear();
-	this.log('info', '清空所有违规记录');
-
-	// 自动保存到持久化存储
-	if (this._config.dir) {
-		this.save();
-	}
-};
-
-/**
- * 保存IP数据到文件（持久化存储）
- * @returns {boolean} 是否保存成功
- */
-Ip.prototype.save = function() {
-	try {
-		const fs = require('fs');
-		const path = require('path');
-
-		// 确保存储目录存在
-		const dir = this._config.dir;
-		dir.addDir();
-
-		// 分别保存不同数据到不同文件
-		const timestamp = Date.now();
-
-		// 保存白名单数据
-		const whiteData = {
-			white: this.getAllWhite(),
-			timestamp: timestamp
-		};
-		const whitePath = path.join(dir, 'white.json');
-		fs.writeFileSync(whitePath, JSON.stringify(whiteData, null, 2), 'utf8');
-
-		// 保存黑名单数据
-		const blackData = {
-			black: this.getAllBlack(),
-			black_time: Array.from(this._black_time.entries()),
-			timestamp: timestamp
-		};
-		const blackPath = path.join(dir, 'black.json');
-		fs.writeFileSync(blackPath, JSON.stringify(blackData, null, 2), 'utf8');
-
-		// 保存违规记录数据
-		const violationData = {
-			violation_count: Array.from(this._violation_count.entries()),
-			violation_time: Array.from(this._violation_time.entries()),
-			timestamp: timestamp
-		};
-		const violationPath = path.join(dir, 'violation.json');
-		fs.writeFileSync(violationPath, JSON.stringify(violationData, null, 2), 'utf8');
-
-		this.log('info', 'IP数据已分文件保存:', {
-			white: whitePath,
-			black: blackPath,
-			violation: violationPath
-		});
-		return true;
-	} catch (err) {
-		this.log('error', '保存IP数据失败:', err.message);
-		return false;
-	}
-};
-
-/**
- * 从文件加载IP数据（持久化存储）
- * @returns {boolean} 是否加载成功
- */
-Ip.prototype.load = function() {
-	try {
-		const fs = require('fs');
-		const path = require('path');
-
-		const dir = this._config.dir;
-		let loadedCount = 0;
-
-		// 加载白名单数据
-		const whitePath = path.join(dir, 'white.json');
-		if (fs.existsSync(whitePath)) {
-			const content = fs.readFileSync(whitePath, 'utf8');
-			const data = JSON.parse(content);
-
-			if (Array.isArray(data.white)) {
-				for (const ip of data.white) {
-					if (typeof ip === 'string') {
-						this._white.add(ip);
-					}
-				}
-				loadedCount++;
-			}
-		}
-
-		// 加载黑名单数据
-		const blackPath = path.join(dir, 'black.json');
-		if (fs.existsSync(blackPath)) {
-			const content = fs.readFileSync(blackPath, 'utf8');
-			const data = JSON.parse(content);
-
-			// 加载黑名单
-			if (Array.isArray(data.black)) {
-				for (const ip of data.black) {
-					if (typeof ip === 'string') {
-						this._black.add(ip);
-					}
-				}
-			}
-
-			// 加载黑名单过期时间
-			if (Array.isArray(data.black_time)) {
-				for (const [ip, time] of data.black_time) {
-					if (typeof ip === 'string' && typeof time === 'number') {
-						this._black_time.set(ip, time);
-					}
-				}
-			}
-
-			loadedCount++;
-		}
-
-		// 加载违规记录数据
-		const violationPath = path.join(dir, 'violation.json');
-		if (fs.existsSync(violationPath)) {
-			const content = fs.readFileSync(violationPath, 'utf8');
-			const data = JSON.parse(content);
-
-			// 加载违规记录
-			if (Array.isArray(data.violation_count)) {
-				for (const [ip, count] of data.violation_count) {
-					if (typeof ip === 'string' && typeof count === 'number') {
-						this._violation_count.set(ip, count);
-					}
-				}
-			}
-
-			if (Array.isArray(data.violation_time)) {
-				for (const [ip, time] of data.violation_time) {
-					if (typeof ip === 'string' && typeof time === 'number') {
-						this._violation_time.set(ip, time);
-					}
-				}
-			}
-
-			loadedCount++;
-		}
-
-		return true;
-	} catch (err) {
-		this.log('error', '加载IP数据失败:', err.message);
-		return false;
-	}
-};
-
-/**
- * 自动保存数据（定时保存）
- * @param {number} interval - 保存间隔（毫秒），默认5分钟
- */
-Ip.prototype.autoSave = function(interval = 300000) {
-	if (this._autoSaveTimer) {
-		clearInterval(this._autoSaveTimer);
-	}
-
-	this._autoSaveTimer = setInterval(() => {
-		this.save();
-	}, interval);
-};
-
-/**
- * 停止自动保存
- */
-Ip.prototype.stopAutoSave = function() {
-	if (this._autoSaveTimer) {
-		clearInterval(this._autoSaveTimer);
-		this._autoSaveTimer = null;
-	}
-};
-
-/**
- * 设置IP地区检测函数
- * @param {Function} fn - 地区检测函数，入参为IP地址，返回地区信息对象或国家代码
- * @throws {TypeError} 当fn非函数时
- */
-Ip.prototype.setRegionChecker = function(fn) {
-	if (typeof fn !== 'function') throw new TypeError('fn must be function');
-
-	this._config.region_checker = fn;
-	this._config.region_check_enable = true;
-};
-
-/**
- * 初始化ip2region地区检测器（私有方法）
- * @private
- */
-Ip.prototype._initIp2Region = function() {
-	try {
-		const IP2Region = require('ip2region').default;
-		const searcher = new IP2Region();
-
-		this._ip2region = searcher;
-		this._config.region_checker = function(ip) {
-			const result = searcher.search(ip);
-			// 内网IP或查询失败时country为空，不返回地区信息
-			if (!result || !result.country) return null;
-			return { country: result.country };
-		};
-		this.log('info', '已加载ip2region地区检测器');
-	} catch (err) {
-		this.log('warn', 'ip2region加载失败，地区检测不可用:', err.message);
-		this._config.region_check_enable = false;
-	}
-};
-
-/**
- * 获取IP地区信息（带缓存）
- * @param {string} ip - IP地址
- * @returns {Object|null|Promise} 地区信息对象，无检测函数或检测失败返回null，异步检测返回Promise
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.getRegion = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	if (!this._config.region_checker) return null;
-
-	// 优先读取缓存
-	const cached = this._region_cache.get(ip);
-	if (cached && Date.now() - cached.time < this._config.region_cache_time) {
-		return cached.region;
-	}
-
-	try {
-		const result = this._config.region_checker(ip);
-
-		// 异步检测函数：缓存结果后返回
-		if (result && typeof result.then === 'function') {
-			return result.then(region => {
-				if (region) {
-					this._region_cache.set(ip, { region, time: Date.now() });
-				}
-				return region;
-			});
-		}
-
-		if (result) {
-			this._region_cache.set(ip, { region: result, time: Date.now() });
-		}
-		return result || null;
-	} catch (err) {
-		this.log('error', 'IP地区检测失败:', err.message);
-		return null;
-	}
-};
-
-/**
- * 判断IP是否为国外IP
- * @param {string} ip - IP地址
- * @returns {boolean} 是否为国外IP
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.isForeign = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const region = this.getRegion(ip);
-	if (!region || typeof region.then === 'function') return false;
-
-	return this._isForeign(region);
-};
-
-/**
- * 检测IP地区，国外IP自动加入黑名单（永久）
- * @param {string} ip - IP地址
- * @returns {Object|null|Promise} 检测结果对象，检测失败返回null，异步检测返回Promise
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.checkRegion = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const region = this.getRegion(ip);
-	if (region && typeof region.then === 'function') {
-		return region.then(region_info => this._handleRegionCheck(ip, region_info));
-	}
-
-	return this._handleRegionCheck(ip, region);
-};
-
-/**
- * 清空IP地区检测结果缓存
- */
-Ip.prototype.clearRegionCache = function() {
-	this._region_cache.clear();
-	this.log('info', '清空IP地区缓存');
-};
-
-/**
- * 判断地区信息是否为国外（私有方法）
- * @private
- * @param {Object|string} region - 地区信息对象或国家代码
- * @returns {boolean} 是否为国外
- */
-Ip.prototype._isForeign = function(region) {
-	if (!region) return false;
-
-	let country = '';
-	if (typeof region === 'string') {
-		country = region;
-	} else if (typeof region === 'object') {
-		// 支持直接指定国外标识
-		if (typeof region.is_foreign === 'boolean') {
-			return region.is_foreign;
-		}
-		country = region.country || region.country_code || '';
-	}
-
-	if (!country) return false;
-
-	const cn_list = ['cn', 'chn', '中国', '中国大陆', 'china'];
-	return !cn_list.includes(country.toLowerCase());
-};
-
-/**
- * 检测国外IP并自动拉黑（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @returns {boolean} 是否已拉黑国外IP
- */
-Ip.prototype._checkForeign = function(ip) {
-	if (!this._config.region_checker) return false;
-	if (this._isPrivate(ip)) return false;
-
-	const region = this.getRegion(ip);
-	// 异步检测函数无法同步拉黑，跳过自动处理
-	if (!region || typeof region.then === 'function') return false;
-
-	if (this._isForeign(region)) {
-		if (this.addBlack(ip)) {
-			// 国外IP拉黑带过期时间，避免永久封禁
-			this._black_time.set(ip, Date.now() + this._config.auto_black_duration);
-		}
-		this.log('warn', '检测到国外IP，自动拉黑:', ip);
-		return true;
-	}
-
-	return false;
-};
-
-/**
- * 处理地区检测结果并拉黑国外IP（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @param {Object} region - 地区信息
- * @returns {Object|null} 检测结果对象
- */
-Ip.prototype._handleRegionCheck = function(ip, region) {
-	if (!region) return null;
-	if (this._isPrivate(ip)) return null;
-
-	const is_foreign = this._isForeign(region);
-	let blacklisted = false;
-
-	if (is_foreign) {
-		blacklisted = this.addBlack(ip);
-		if (blacklisted) {
-			// 国外IP拉黑带过期时间，避免永久封禁
-			this._black_time.set(ip, Date.now() + this._config.auto_black_duration);
-		}
-		this.log('warn', '检测到国外IP，加入黑名单:', ip);
-	}
-
-	return {
-		ip: ip,
-		region: region,
-		is_foreign: is_foreign,
-		blacklisted: blacklisted
-	};
-};
-
-/**
- * 在操作系统层拉黑IP（入站拦截）
- * @param {string} ip - IP地址
- * @returns {boolean} 是否拉黑成功
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.osBlack = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	if (!this._validIp(ip)) return false;
-
-	const cmd = this._getOsCmd(ip, 'black');
-	if (!cmd) return false;
-
-	const result = this._execOsCmd(cmd);
-	if (result.success) {
-		this.log('info', '系统层拉黑IP:', ip);
-		return true;
-	}
-
-	this.log('error', '系统层拉黑IP失败:', ip, result.output);
-	return false;
-};
-
-/**
- * 在操作系统层释放IP（解除入站拦截）
- * @param {string} ip - IP地址
- * @returns {boolean} 是否释放成功
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.osUnblack = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	if (!this._validIp(ip)) return false;
-
-	const cmd = this._getOsCmd(ip, 'unblack');
-	if (!cmd) return false;
-
-	const result = this._execOsCmd(cmd);
-	if (result.success) {
-		this.log('info', '系统层释放IP:', ip);
-		return true;
-	}
-
-	this.log('error', '系统层释放IP失败:', ip, result.output);
-	return false;
-};
-
-/**
- * 检查IP是否已在操作系统层拉黑
- * @param {string} ip - IP地址
- * @returns {boolean} 是否已系统拉黑
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.isOsBlack = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-	if (!this._validIp(ip)) return false;
-
-	const cmd = this._getOsCmd(ip, 'check');
-	if (!cmd) return false;
-
-	const result = this._execOsCmd(cmd);
-	if (!result.success) return false;
-
-	return result.output.includes(this._config.os_rule_prefix + ip)
-		|| result.output.includes(ip);
-};
-
-/**
- * 生成系统拉黑命令（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @param {string} action - 操作类型（black, unblack, check）
- * @returns {string|null} 系统命令，不支持的平台返回null
- */
-Ip.prototype._getOsCmd = function(ip, action) {
-	if (process.platform === 'win32') {
-		return this._getWinCmd(ip, action);
-	}
-	if (process.platform === 'linux') {
-		return this._getLinuxCmd(ip, action);
-	}
-	return null;
-};
-
-/**
- * 生成Windows防火墙命令（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @param {string} action - 操作类型（black, unblack, check）
- * @returns {string|null} 系统命令
- */
-Ip.prototype._getWinCmd = function(ip, action) {
-	const rule = this._config.os_rule_prefix + ip;
-
-	if (action === 'black') {
-		return `netsh advfirewall firewall add rule name="${rule}" dir=in action=block remoteip=${ip}`;
-	}
-	if (action === 'unblack') {
-		return `netsh advfirewall firewall delete rule name="${rule}"`;
-	}
-	if (action === 'check') {
-		return `netsh advfirewall firewall show rule name="${rule}"`;
-	}
-	return null;
-};
-
-/**
- * 生成Linux iptables命令（私有方法）
- * @private
- * @param {string} ip - IP地址
- * @param {string} action - 操作类型（black, unblack, check）
- * @returns {string|null} 系统命令
- */
-Ip.prototype._getLinuxCmd = function(ip, action) {
-	if (action === 'black') {
-		return `iptables -I INPUT -s ${ip} -j DROP`;
-	}
-	if (action === 'unblack') {
-		return `iptables -D INPUT -s ${ip} -j DROP`;
-	}
-	if (action === 'check') {
-		return `iptables -L INPUT -n`;
-	}
-	return null;
-};
-
-/**
- * 执行系统命令（私有方法）
- * @private
- * @param {string} cmd - 系统命令
- * @returns {Object} 执行结果 { success, output }
- */
-Ip.prototype._execOsCmd = function(cmd) {
-	try {
-		const { execSync } = require('child_process');
-		const output = execSync(cmd, {
-			encoding: 'utf8',
-			timeout: 8000,
-			stdio: ['pipe', 'pipe', 'pipe']
-		});
-		return { success: true, output: output || '' };
-	} catch (err) {
-		const output = (err.stdout && err.stdout.toString()) || err.message || '';
-		return { success: false, output: output };
-	}
-};
-
-/**
- * 删除IP记录（从黑名单、白名单、临时记录中删除）
- * @param {string} ip - IP地址
- * @returns {Object} 删除结果
- * @throws {TypeError} 当IP非字符串时
- */
-Ip.prototype.del = function(ip) {
-	if (typeof ip !== 'string') throw new TypeError('ip must be string');
-
-	const result = {
-		black: false,
-		white: false,
-		violation: false,
-		black_time: false,
-		violation_count: false,
-		violation_time: false
-	};
-
-	// 从黑名单删除
-	if (this._black.has(ip)) {
-		this._black.delete(ip);
-		result.black = true;
-
-		// 系统级联动释放
-		if (this._config.os_black_enable) {
-			this.osUnblack(ip);
-		}
-	}
-
-	// 从白名单删除
-	if (this._white.has(ip)) {
-		this._white.delete(ip);
-		result.white = true;
-	}
-
-	// 从违规记录删除
-	if (this._violation_count.has(ip)) {
-		this._violation_count.delete(ip);
-		result.violation_count = true;
-	}
-
-	if (this._violation_time.has(ip)) {
-		this._violation_time.delete(ip);
-		result.violation_time = true;
-	}
-
-	// 清理请求窗口与违规标记
-	this._req_start.delete(ip);
-	this._violation_flagged.delete(ip);
-
-	// 从黑名单过期时间记录删除
-	if (this._black_time.has(ip)) {
-		this._black_time.delete(ip);
-		result.black_time = true;
-	}
-
-	// 从地区缓存删除
-	this._region_cache.delete(ip);
-
-	// 如果有任何删除操作，记录日志并自动保存
-	if (Object.values(result).some(Boolean)) {
-		// 自动保存到持久化存储
-		if (this._config.dir) {
-			this.save();
-		}
-	}
-
-	return result;
-};
-
-if (global.$ && !$.ip) {
-	$.ip = new Ip();
-}
+const admin = new Admin();
+admin.setClass(Ip);
 
 module.exports = {
-	Ip
+  IP,
+  Ip,
+  admin,
+  ipAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
 };