mm_ip 1.0.5 → 1.0.7

package/README.md

@@ -13,6 +13,8 @@
 - ✅ **IP请求频率监控** - 实时监控IP请求频率，防止高频访问
 - ✅ **自动拉黑机制** - 支持高频访问自动拉黑和违规次数超限自动拉黑
 - ✅ **违规记录系统** - 记录IP违规行为，支持违规次数统计和重置
+- ✅ **IP地区检测** - 内置ip2region离线IP库，检测到国外IP自动加入黑名单
+- ✅ **操作系统级拉黑** - 支持直接调用系统防火墙拉黑/释放IP（Windows netsh / Linux iptables）
 - ✅ **持久化存储** - 支持数据分文件存储（白名单、黑名单、违规记录独立存储）
 - ✅ **自动保存机制** - 支持定时自动保存和操作触发保存
 - ✅ **重启数据恢复** - 支持重启后自动加载持久化数据
@@ -89,10 +91,16 @@ new Ip(config)
 | `auto_black_enable` | boolean | true | 启用自动高频拉黑 |
 | `auto_black_threshold` | number | 50 | 自动拉黑阈值 |
 | `auto_black_duration` | number | 3600000 | 自动拉黑持续时间（毫秒） |
+| `auto_black_grace_count` | number | 3 | 自动拉黑宽限次数，连续触限达到该次数后才拉黑 |
 | `violation_enable` | boolean | true | 启用违规记录 |
 | `violation_max_count` | number | 10 | 最大违规次数 |
 | `violation_reset_time` | number | 86400000 | 违规记录重置时间（毫秒） |
 | `violation_auto_black` | boolean | true | 违规次数超限自动拉黑 |
+| `region_check_enable` | boolean | true | 启用国外IP检测 |
+| `region_checker` | function | 自动加载ip2region | IP地区检测函数 (ip) => 地区信息 |
+| `region_cache_time` | number | 86400000 | 地区检测结果缓存时间（毫秒） |
+| `os_black_enable` | boolean | false | 启用系统级拉黑联动（需管理员权限，默认关闭避免误拦截） |
+| `os_rule_prefix` | string | 'mm_ip_black_' | 系统防火墙规则名前缀 |
 | `dir` | string | './cache/ip' | 持久化存储目录 |
 
 ### 主要方法
@@ -124,6 +132,20 @@ new Ip(config)
 - `clearViolations()` - 清空所有违规记录
 - `getAllViolations()` - 获取所有违规记录
 
+#### IP地区检测
+- `setRegionChecker(fn)` - 设置自定义地区检测函数
+- `getRegion(ip)` - 获取IP地区信息（带缓存）
+- `isForeign(ip)` - 判断IP是否为国外IP
+- `checkRegion(ip)` - 检测IP地区，国外IP自动加入黑名单
+- `clearRegionCache()` - 清空地区检测结果缓存
+
+#### 操作系统级拉黑
+- `osBlack(ip)` - 在操作系统层拉黑IP（入站拦截，需管理员权限）
+- `osUnblack(ip)` - 在操作系统层释放IP
+- `isOsBlack(ip)` - 检查IP是否已在操作系统层拉黑
+
+> 启用 `os_black_enable` 后，`addBlack()` 会自动同步系统防火墙拉黑，`delBlack()`/`del()` 会自动释放。运行环境需具备管理员权限，否则系统命令执行失败仅记录日志，不影响应用层黑名单功能。
+
 #### 持久化存储
 - `save()` - 手动保存数据
 - `load()` - 手动加载数据

package/README_EN.md

@@ -13,6 +13,8 @@ A powerful IP management module that supports whitelist, blacklist management, I
 - ✅ **IP Request Frequency Monitoring** - Real-time IP request frequency monitoring to prevent high-frequency access
 - ✅ **Auto-Blacklist Mechanism** - Automatic blacklisting for high-frequency access and violation limit exceeding
 - ✅ **Violation Record System** - Record IP violation behaviors with violation count statistics and reset
+- ✅ **IP Region Detection** - Built-in ip2region offline IP database, auto-blacklist foreign IPs
+- ✅ **OS-Level Blacklisting** - Directly blacklist/release IPs via system firewall (Windows netsh / Linux iptables)
 - ✅ **Persistent Storage** - Support for separate file storage (whitelist, blacklist, violation records stored independently)
 - ✅ **Auto-Save Mechanism** - Support for timed auto-save and operation-triggered save
 - ✅ **Data Recovery on Restart** - Automatic loading of persistent data after restart
@@ -89,10 +91,16 @@ new Ip(config)
 | `auto_black_enable` | boolean | true | Enable auto-blacklist for high frequency |
 | `auto_black_threshold` | number | 50 | Auto-blacklist threshold |
 | `auto_black_duration` | number | 3600000 | Auto-blacklist duration (milliseconds) |
+| `auto_black_grace_count` | number | 3 | Grace count before auto-blacklist |
 | `violation_enable` | boolean | true | Enable violation records |
 | `violation_max_count` | number | 10 | Maximum violation count |
 | `violation_reset_time` | number | 86400000 | Violation record reset time (milliseconds) |
 | `violation_auto_black` | boolean | true | Auto-blacklist when violation count exceeds limit |
+| `region_check_enable` | boolean | true | Enable foreign IP detection |
+| `region_checker` | function | auto load ip2region | IP region check function (ip) => region info |
+| `region_cache_time` | number | 86400000 | Region check result cache time (ms) |
+| `os_black_enable` | boolean | false | Enable OS-level blacklist sync (requires admin, off by default) |
+| `os_rule_prefix` | string | 'mm_ip_black_' | System firewall rule name prefix |
 | `dir` | string | './cache/ip' | Persistent storage directory |
 
 ### Main Methods
@@ -124,6 +132,20 @@ new Ip(config)
 - `clearViolations()` - Clear all violation records
 - `getAllViolations()` - Get all violation records
 
+#### IP Region Detection
+- `setRegionChecker(fn)` - Set custom region check function
+- `getRegion(ip)` - Get IP region info (with cache)
+- `isForeign(ip)` - Check if IP is foreign
+- `checkRegion(ip)` - Check IP region, auto-blacklist foreign IPs
+- `clearRegionCache()` - Clear region check result cache
+
+#### OS-Level Blacklisting
+- `osBlack(ip)` - Blacklist IP at OS level (inbound block, requires admin)
+- `osUnblack(ip)` - Release IP at OS level
+- `isOsBlack(ip)` - Check if IP is blacklisted at OS level
+
+> When `os_black_enable` is enabled, `addBlack()` automatically syncs the system firewall, and `delBlack()`/`del()` automatically release it. The running environment needs administrator privileges; otherwise, failed system commands only log errors and do not affect the application-level blacklist.
+
 #### Persistent Storage
 - `save()` - Manually save data
 - `load()` - Manually load data

package/cache/ip/black.json

@@ -2,26 +2,25 @@
   "black": [
     "192.168.100.2",
     "192.168.200.1",
-    "192.168.200.2",
     "192.168.200.3"
   ],
   "black_time": [
     [
       "172.16.0.2",
-      1765868172389
+      1787927071109
     ],
     [
       "192.168.100.2",
-      1765868205392
+      1787928865115
     ],
     [
       "192.168.200.2",
-      1765868206419
+      1787928361999
     ],
     [
       "192.168.200.3",
-      1765868206425
+      1787928866136
     ]
   ],
-  "timestamp": 1765868213494
+  "timestamp": 1787928873206
 }

package/cache/ip/violation.json

@@ -1,5 +1,5 @@
 {
   "violation_count": [],
   "violation_time": [],
-  "timestamp": 1765868213494
+  "timestamp": 1787928873206
 }

package/cache/ip/white.json

@@ -1,4 +1,4 @@
 {
   "white": [],
-  "timestamp": 1765868213494
+  "timestamp": 1787928873206
 }

package/index.js

@@ -17,10 +17,16 @@ class Ip {
 		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' // 持久化存储目录
 	}
 	/**
@@ -34,12 +40,19 @@ class Ip {
 		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_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();
@@ -118,6 +131,11 @@ Ip.prototype.addBlack = function(ip) {
 	this._black.add(ip);
 	this.log('info', '添加黑名单IP:', ip);
 
+	// 系统级联动拉黑
+	if (this._config.os_black_enable) {
+		this.osBlack(ip);
+	}
+
 	// 自动保存到持久化存储
 	if (this._config.dir) {
 		this.save();
@@ -160,6 +178,11 @@ Ip.prototype.delBlack = function(ip) {
 	if (result) {
 		this.log('info', '删除黑名单IP:', ip);
 
+		// 系统级联动释放
+		if (this._config.os_black_enable) {
+			this.osUnblack(ip);
+		}
+
 		// 自动保存到持久化存储
 		if (this._config.dir) {
 			this.save();
@@ -214,30 +237,50 @@ Ip.prototype.record = function(ip) {
 		}
 	}
 
+	// 内网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) {
-			this.recordViolation(ip, '请求频率超限');
+			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) {
-			const rate = this.getReqRate(ip);
-			if (rate >= this._config.auto_black_threshold) {
-				this._autoBlack(ip);
-				return false;
-			}
+		// 达到宽限次数且频率超阈值才自动拉黑
+		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;
 	}
 
@@ -266,17 +309,16 @@ Ip.prototype.getReqRate = function(ip) {
 	if (typeof ip !== 'string') throw new TypeError('ip must be string');
 
 	const now = Date.now();
-	const lastTime = this._req_time.get(ip) || now;
+	const start = this._req_start.get(ip) || now;
 	const count = this._req_count.get(ip) || 0;
 
-	if (now - lastTime < this._config.check_interval) {
-		// 在检查间隔内，计算实际频率
-		const elapsed = Math.max(1, now - lastTime); // 避免除零
-		return Math.round((count / elapsed) * this._config.check_interval);
-	} else {
-		// 超过检查间隔，频率为0
+	// 当前窗口已过期，频率为0
+	if (now - start >= this._config.check_interval) {
 		return 0;
 	}
+
+	// 按窗口换算为每分钟请求数，不做时间外推
+	return Math.round((count / this._config.check_interval) * 60000);
 };
 
 /**
@@ -361,6 +403,7 @@ Ip.prototype.clearBlack = function() {
 Ip.prototype.clearReq = function() {
 	this._req_count.clear();
 	this._req_time.clear();
+	this._req_start.clear();
 	this.log('info', '清空请求记录');
 };
 
@@ -372,20 +415,17 @@ Ip.prototype.clearReq = function() {
  */
 Ip.prototype._checkRateLimit = function(ip) {
 	const now = Date.now();
-	const lastTime = this._req_time.get(ip) || 0;
+	let start = this._req_start.get(ip);
 
-	// 检查时间间隔
-	if (now - lastTime < this._config.check_interval) {
-		const count = this.getReqCount(ip);
-		if (count >= this._config.max_req_per_min) {
-			return false;
-		}
-	} else {
-		// 重置计数
+	// 无窗口或窗口已过期，开启新窗口并重置计数
+	if (start === undefined || now - start >= this._config.check_interval) {
+		start = now;
+		this._req_start.set(ip, start);
 		this._req_count.set(ip, 0);
 	}
 
-	return true;
+	const count = this._req_count.get(ip) || 0;
+	return count < this._config.max_req_per_min;
 };
 
 /**
@@ -394,6 +434,10 @@ Ip.prototype._checkRateLimit = function(ip) {
  * @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());
@@ -410,6 +454,28 @@ Ip.prototype._validIp = function(ip) {
 	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地址数组
@@ -558,8 +624,11 @@ Ip.prototype.recordViolation = function(ip, reason) {
 	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);
-	this._violation_time.set(ip, now);
 
 	// 检查是否达到自动拉黑条件
 	if (this._config.violation_auto_black && count >= this._config.violation_max_count) {
@@ -622,7 +691,7 @@ Ip.prototype.getViolationInfo = function(ip) {
 
 	return {
 		count: count,
-		time: this._violation_time.get(ip)
+		time: this._violation_time.get(ip) // 首次违规时间
 	};
 };
 
@@ -842,6 +911,349 @@ Ip.prototype.stopAutoSave = function() {
 	}
 };
 
+/**
+ * 设置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地址
@@ -864,6 +1276,11 @@ Ip.prototype.del = function(ip) {
 	if (this._black.has(ip)) {
 		this._black.delete(ip);
 		result.black = true;
+
+		// 系统级联动释放
+		if (this._config.os_black_enable) {
+			this.osUnblack(ip);
+		}
 	}
 
 	// 从白名单删除
@@ -883,12 +1300,19 @@ Ip.prototype.del = function(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)) {
 		// 自动保存到持久化存储

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mm_ip",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "用于管理IP名单，可设置白名单、黑名单和IP检查，查询IP请求次数、频率等。",
   "main": "index.js",
   "scripts": {
@@ -21,6 +21,7 @@
   "author": "qww",
   "license": "ISC",
   "dependencies": {
-    "mm_expand": "^2.5.1"
+    "ip2region": "^2.3.0",
+    "mm_expand": "^2.5.4"
   }
 }

package/test.js

@@ -16,7 +16,8 @@ const ip_manager = new Ip({
     violation_enable: true, // 启用违规记录
     violation_max_count: 3, // 降低阈值便于测试
     violation_reset_time: 10000, // 10秒便于测试
-    violation_auto_black: true // 违规次数超限自动拉黑
+    violation_auto_black: true, // 违规次数超限自动拉黑
+    os_black_enable: false // 测试环境禁用系统级联动
 });
 
 
@@ -35,6 +36,91 @@ console.log('添加 10.0.0.1:', ip_manager.addBlack('10.0.0.1'));
 console.log('添加 10.0.0.2:', ip_manager.addBlack('10.0.0.2'));
 console.log('黑名单列表:', ip_manager.getAllBlack());
 
+// 测试2.5: 国外IP检测功能
+console.log('\n2.5 测试国外IP检测功能:');
+
+// 创建独立实例，避免影响其他测试
+const region_ip = new Ip({ dir: null, os_black_enable: false });
+
+// 模拟地区检测函数
+region_ip.setRegionChecker(function(ip) {
+    const region_map = {
+        '8.8.8.8': { country: 'US' },          // 国外
+        '1.1.1.1': 'US',                       // 国外（字符串国家代码）
+        '114.114.114.114': { country: 'CN' }   // 国内
+    };
+    return region_map[ip] || null;
+});
+
+// 获取地区信息
+console.log('获取 8.8.8.8 地区:', region_ip.getRegion('8.8.8.8'));
+console.log('获取 114.114.114.114 地区:', region_ip.getRegion('114.114.114.114'));
+
+// 判断国外
+console.log('8.8.8.8 是否国外:', region_ip.isForeign('8.8.8.8'));
+console.log('114.114.114.114 是否国外:', region_ip.isForeign('114.114.114.114'));
+
+// checkRegion 检测并拉黑国外IP
+console.log('检测 8.8.8.8 地区:', region_ip.checkRegion('8.8.8.8'));
+console.log('8.8.8.8 是否在黑名单:', region_ip.isBlack('8.8.8.8'));
+console.log('检测 114.114.114.114 地区:', region_ip.checkRegion('114.114.114.114'));
+console.log('114.114.114.114 是否在黑名单:', region_ip.isBlack('114.114.114.114'));
+
+// record 自动检测国外IP并拉黑
+console.log('记录 1.1.1.1 请求:', region_ip.record('1.1.1.1'));
+console.log('1.1.1.1 是否在黑名单:', region_ip.isBlack('1.1.1.1'));
+
+// 未知地区IP不会被拉黑
+console.log('记录未知IP 172.16.9.9 请求:', region_ip.record('172.16.9.9'));
+console.log('172.16.9.9 是否在黑名单:', region_ip.isBlack('172.16.9.9'));
+
+// 清空地区缓存
+region_ip.clearRegionCache();
+console.log('地区缓存已清空');
+
+// 测试2.6: ip2region 接入测试
+console.log('\n2.6 测试ip2region接入:');
+
+// 使用默认配置创建实例，自动加载ip2region检测器
+const ipr = new Ip({ dir: null, os_black_enable: false });
+console.log('ip2region 检测器已加载:', typeof ipr.getRegion('8.8.8.8') === 'object');
+
+// 国外IP自动拉黑
+console.log('8.8.8.8 地区:', ipr.getRegion('8.8.8.8'));
+console.log('8.8.8.8 是否国外:', ipr.isForeign('8.8.8.8'));
+console.log('记录 8.8.8.8 请求:', ipr.record('8.8.8.8'));
+console.log('8.8.8.8 是否在黑名单:', ipr.isBlack('8.8.8.8'));
+
+// 国内IP正常放行
+console.log('记录 114.114.114.114 请求:', ipr.record('114.114.114.114'));
+console.log('114.114.114.114 是否在黑名单:', ipr.isBlack('114.114.114.114'));
+
+// 内网IP不会被拉黑
+console.log('记录 192.168.1.1 请求:', ipr.record('192.168.1.1'));
+console.log('192.168.1.1 是否在黑名单:', ipr.isBlack('192.168.1.1'));
+
+// 测试2.7: 系统级拉黑功能
+console.log('\n2.7 测试系统级拉黑功能:');
+const os_ip = new Ip({ dir: null });
+
+// 无效IP不执行系统命令
+console.log('无效IP osBlack:', os_ip.osBlack('not_a_ip'));
+console.log('无效IP isOsBlack:', os_ip.isOsBlack('not_a_ip'));
+
+// 系统级拉黑（需管理员权限，无权限时返回false且不崩溃）
+console.log('系统拉黑 1.2.3.4:', os_ip.osBlack('1.2.3.4'));
+console.log('1.2.3.4 是否系统拉黑:', os_ip.isOsBlack('1.2.3.4'));
+
+// 系统级释放
+console.log('系统释放 1.2.3.4:', os_ip.osUnblack('1.2.3.4'));
+console.log('释放后是否系统拉黑:', os_ip.isOsBlack('1.2.3.4'));
+
+// addBlack 联动系统拉黑
+os_ip.setConfig({ os_black_enable: true });
+console.log('联动addBlack系统拉黑 1.2.3.5:', os_ip.addBlack('1.2.3.5'));
+console.log('1.2.3.5 在应用层黑名单:', os_ip.isBlack('1.2.3.5'));
+console.log('delBlack 联动系统释放:', os_ip.delBlack('1.2.3.5'));
+
 // 测试3: 检查IP状态
 console.log('\n3. 测试检查IP状态:');
 console.log('192.168.1.1 在白名单:', ip_manager.isWhite('192.168.1.1'));
@@ -196,7 +282,8 @@ setTimeout(() => {
     const persistent_ip = new Ip({
         dir: './cache/ip',
         max_white: 3,
-        max_black: 3
+        max_black: 3,
+        os_black_enable: false
     });
     
     // 添加测试数据
@@ -246,7 +333,8 @@ setTimeout(() => {
     // 创建新实例并加载数据
     console.log('创建新实例并加载数据:');
     const loaded_ip = new Ip({
-        dir: './cache/ip'
+        dir: './cache/ip',
+        os_black_enable: false
     });
     
     console.log('加载后数据统计:');