# phpfirewall

**Repository Path**: qcod/phpfirewall

## Basic Information

- **Project Name**: phpfirewall
- **Description**: IP2Region Web 防火墙
基于 IP2Region 的地理位置访问控制防火墙，支持白名单和黑名单两种模式。
- **Primary Language**: PHP
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/qcod/phpfirewall
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IP2Region Web 防火墙 v2.3

基于 IP2Region 的地理位置访问控制防火墙，支持白名单和黑名单两种模式。
经过4个迭代的优化，已全面支持 IP 段匹配，并添加了 IP 段优先级功能。
功能就到这里了。有需要的可以参考代码自行添加。
效率是最关键的问题。此代码运行0.010秒左右，可以嵌入到任何PHP项目中。

## 🔥 介绍

    v3.1.0 2026-03-27
        手动优化逻辑
        基本bug修复，当前只是保存配置，但初始化时未能显示工作状态。
    v2.2.1 2026-03-26
        优化添加区域，优化黑白名单判断逻辑
        优化IP段匹配，添加IP段优先级功能
    v2.0 2026-03-25
        修改为标签控制模式，修复核心bug，城市名匹配问题
    v1.0 2026-03-24
    ai生成，就是下拉菜单直接保存模式，

## 📁 目录结构

```
ip2region/
├── Firewall.php          # 核心防火墙类
├── Middleware.php        # 中间件（用于拦截请求）
├── admin.php             # 管理面板
├── example.php           # 使用示例
├── config.json           # 防火墙模式配置
├── white.json            # 白名单配置
├── black.json            # 黑名单配置
├── ip2region.db          # IP2Region 数据库（需单独下载）
└── README.md             # 本说明文档
```

## ✨ 功能特性

### 两种防火墙模式

1. **黑名单模式（默认）**
   - 默认允许所有访问
   - 仅拒绝在 `black.json` 中的地区访问
   - 适合大多数场景

2. **白名单模式**
   - 默认拒绝所有访问
   - 仅允许在 `white.json` 中的地区访问
   - 适合高安全需求场景

### 多级地区控制

- **国家级别**：中国、美国、日本等
- **省份级别**：北京、上海、广东等（针对中国）
- **城市级别**：北京、上海、广州等

### 日志管理

自动记录每次访问的：

- IP 地址
- 国家/省份/城市信息
- 访问时间
- 访问方式（GET/POST）
- 访问路径
- 状态码（200/403）

## 🚀 快速开始

### 1. 安装 IP2Region 数据库

下载 IP2Region 数据库文件并放到 `ip2region/` 目录下：

```bash
# 下载地址：https://github.com/lionsoul2014/ip2region
# 需要 xdb 格式的数据库文件
mv ip2region.xdb ip2region/ip2region.db
```

### 2. 在你的网站入口启用防火墙

在你的网站入口文件（如 `index.php`）最开头添加：

```php
<?php
require_once __DIR__ . '/mod/ip2region/Middleware.php';

$middleware = new FirewallMiddleware();
if (!$middleware->handle()) {
    exit; // 访问被拒绝，中间件已输出页面
}

// 继续执行你的网站逻辑...
```

### 3. 访问管理面板

浏览器访问：`http://你的域名/mod/ip2region/admin.php`

默认密码：无需密码（建议添加认证）

## ⚙️ 配置文件说明

### config.json - 防火墙模式

```json
{
    "mode": "blacklist"  // 或 "whitelist"
}
```

### white.json - 白名单

```json
{
    "countries": ["中国", "美国", "日本"],
    "provinces": ["北京", "上海", "广东"],
    "cities": ["北京", "上海"]
}
```

### black.json - 黑名单

```json
{
    "countries": ["朝鲜", "伊朗"],
    "provinces": [],
    "cities": []
}
```

## 📋 管理面板功能

访问 `admin.php` 可以：

1. **切换防火墙模式**
   - 白名单模式：默认拒绝，仅允许名单内
   - 黑名单模式：默认允许，仅拒绝名单内

2. **管理 White.json**
   - 添加允许的国家
   - 添加允许的省份（国内）
   - 添加允许的城市
   - 提供快速添加按钮

3. **管理 Black.json**
   - 添加拒绝的国家
   - 添加拒绝的省份
   - 添加拒绝的城市
   - 提供快速添加按钮

4. **查看访问日志**
   - 最近 50 条访问记录
   - 显示 IP、地区、时间、状态
   - 绿色表示允许，红色表示拒绝

5. **访问统计**
   - 总访问数
   - 允许访问数
   - 拒绝访问数

## 🔍 常用地区名称

### 国家名称（部分）

```
中国、美国、日本、韩国、英国、德国、法国、意大利、西班牙、俄罗斯、
加拿大、澳大利亚、印度、巴西、墨西哥、新加坡、马来西亚、泰国、
越南、菲律宾、印度尼西亚、荷兰、瑞士、瑞典、挪威
```

### 中国省份（部分）

```
北京、上海、广东、浙江、江苏、山东、四川、湖北、湖南、河南、
河北、福建、安徽、辽宁、陕西、江西、重庆、云南、广西、山西、
吉林、黑龙江、内蒙古、新疆、西藏、宁夏、青海、甘肃、贵州、
海南、香港、澳门、台湾
```

## 📊 日志格式

日志文件位置：`log/security/firewall.log`

每条日志为 JSON 格式：

```json
{
    "time": "2024-03-23 15:30:00",
    "ip": "123.55.235.99",
    "country": "中国",
    "province": "河南",
    "city": "漯河",
    "allowed": true,
    "reason": "不在 black.json 中",
    "method": "GET",
    "uri": "/index.php",
    "status": 200
}
```

## 🛠️ 高级用法

### 1. 自定义 IP 获取逻辑

如果网站在 CDN 后面，需要修改 `Middleware.php` 中的 `getClientIP()` 方法：

```php
private function getClientIP() {
    // 从 CDN 头部获取真实 IP
    if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
        return $_SERVER['HTTP_X_FORWARDED_FOR'];
    }
    return $_SERVER['REMOTE_ADDR'];
}
```

### 2. 添加管理员认证

在 `admin.php` 开头添加：

```php
session_start();
if (!isset($_SESSION['admin_logged_in'])) {
    // 显示登录表单
    // ...
}
```

### 3. 定期清理日志

添加定时任务清理旧日志：

```bash
# 每天凌晨 2 点清理 7 天前的日志
0 2 * * * find /path/to/log/security -name "*.log" -mtime +7 -delete
```

## ⚠️ 注意事项

1. **数据库文件**：确保 `ip2region.db` 文件存在且可读
2. **目录权限**：确保 `log/security` 目录可写（755 权限）
3. **性能考虑**：高并发场景建议使用缓存（Redis/Memcached）
4. **内网 IP**：内网 IP（192.168.x.x、10.x.x.x 等）默认放行
5. **测试**：上线前充分测试，避免误伤正常用户

## 🔧 故障排查

### IP 解析失败

- 检查 `ip2region.db` 是否存在
- 检查数据库文件是否损坏
- 确认 PHP 版本兼容性

### 日志无法写入

- 检查 `log/security` 目录权限
- 确认磁盘空间充足
- 检查 SELinux/AppArmor 限制

### 配置不生效

- 检查 JSON 格式是否正确
- 清除 PHP OPcache 缓存
- 重启 PHP-FPM/Apache

## 📝 更新日志

### v2.0 - 重构版

- ✅ 简化代码结构，删除冗余文件
- ✅ 修复路径依赖问题
- ✅ 现代化管理界面
- ✅ 添加快速添加按钮
- ✅ 改进日志格式
- ✅ 优化性能

### v1.0 - 初始版

- 基本的黑白名单功能
- 简单的管理界面

## 📄 许可证

MIT License

## 🔗 相关链接

- [IP2Region 官方项目](https://github.com/lionsoul2014/ip2region)
- [GeoIP2 数据库](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data)

---

**作者**: AI Assistant  
**最后更新**: 2024-03-23