IP 访问记录工具(PHP + SQLite + ip2region)
平时都是用AI都是问答式获取信息和代码,也用过几次TRAE搞代码提供打包下载,但理解能力有限需要不断的修正。今天第一次使用网页版豆包项目工具在线编写程序,感受了AI的功能强大,它能完全理解我的意图,实现了简单的IP防火墙和日志管理。编写的项目非常的完善,并提供了详细说明和打包下载。
包括ip2region_v4和ip2region_v6本地数据库,压缩包达到了11M,下载地址如下:
移动云(登录后不限速):https://yun.139.com/shareweb/#/w/i/2yA8Jyz9KGYqb
蓝奏云:https://wlgn.lanzoul.com/iE9tM4gp71la 密码:4a60
现将README.md和CHANGELOG.md帖上来。

IP 访问记录工具(PHP + SQLite + ip2region)
一个开箱即用的访客 IP 记录与拦截工具:记录 IP / 归属地 / 时间 / 页面 / 来源,后台分页查看、按时间段清空,支持 IP 黑名单,命中黑名单的访客在页面加载前直接被拦截。
- 单文件 SQLite,无需 MySQL,无需 Redis,无需 Composer
- 归属地查询使用内置的 ip2region 纯 PHP SDK + 官方离线库(本地文件,不联网)
- 两种接入方式:服务端一行 require(推荐,记录 + 拦截)或 一段 JS 脚本(任意网站,仅记录)
- 后台含登录、CSRF 防护、登录失败限流、CSV 导出、单条删除、按天趋势图
环境要求
| 项目 | 要求 |
|---|---|
| PHP | 7.4 及以上(推荐 8.1+) |
| 扩展 | pdo_sqlite(必需)、sqlite3(可选)、mbstring(推荐) |
| Web 服务器 | Apache / Nginx / IIS / 宝塔 / 虚拟主机均可 |
| 目录权限 | data/ 可写(用于数据库与缓存) |
查看环境是否满足:
php check.php会输出 PHP 版本、SQLite 状态、数据库记录数、归属地库状态,并用几个样例 IP 实测归属地查询。
快速开始
- 把整个
ip-record/目录上传到网站目录,例如:
/www/wwwroot/your-site/ip-record/访问
https://your-site.com/ip-record/admin/login.php- 默认账号:
admin - 默认密码:
admin123 - 首次登录后请立刻在「修改密码」中修改(账号密码只在第一次初始化数据库时从
config.php读取,之后改配置不会生效)
- 默认账号:
- 在网站页面接入记录(三选一,见下一节)。
- 打开后台「访客记录」即可看到数据。
首次访问任意入口会自动创建 data/ip_records.db 并建表,不需要手动导入 SQL。接入方式(按推荐程度排序)
方式一:服务端一行引入(推荐,记录 + 拦截)
在你每个需要记录的页面最顶部加入(一定要在任何输出之前):
<?php
require_once '/www/wwwroot/your-site/ip-record/embed/ip-record.php';⚠️ 必须是服务器上的文件路径,不能写成http://...网址。require/include引入的是本地 PHP 文件;用网址引入需要allow_url_include=On(默认关闭且不安全),会直接触发致命错误,表现为页面白屏 / 500。
路径的几种写法(按实际情况选一种):
// 1. 绝对路径(最稳妥,推荐)
require_once '/www/wwwroot/your-site/ip-record/embed/ip-record.php';
// 2. 与当前 PHP 文件同目录时(__DIR__ 是当前文件的目录)
require_once __DIR__ . '/ip-record/embed/ip-record.php';
// 3. 用站点根目录拼接
require_once $_SERVER['DOCUMENT_ROOT'] . '/ip-record/embed/ip-record.php';
// 4. Windows(PHPStudy / 宝塔 Windows 版),正斜杠或双反斜杠均可
require_once 'C:/phpstudy_pro/WWW/your-site/ip-record/embed/ip-record.php';- 优点:不依赖浏览器 JS,爬虫、接口请求、禁用 JS 的访客都能记录;IP 取的是真实
REMOTE_ADDR;黑名单可以在页面渲染前直接 403。 - 适合:PHP 网站、WordPress(放到主题
header.php最前面)、ThinkPHP/Laravel 的公共入口、Discuz 等。
WordPress 示例:编辑当前主题的 header.php,把上面一行放在文件第一行 <?php 之后。
方式二:全站无感接入(auto_prepend_file,整站部署最省事)
不用改任何页面,PHP 会在执行每个脚本前自动加载:
php.ini(独立服务器 / 宝塔「配置修改」):
auto_prepend_file = "/www/wwwroot/your-site/ip-record/embed/auto_prepend.php"Apache .htaccess(虚拟主机):
php_value auto_prepend_file "/www/wwwroot/your-site/ip-record/embed/auto_prepend.php"Nginx + PHP-FPM(在 php-fpm 池配置 www.conf 或 php.ini 中):
php_value[auto_prepend_file] = /www/wwwroot/your-site/ip-record/embed/auto_prepend.php- 工具会自动跳过自己的
admin/、api/目录,不会重复记录,也不会把管理员锁在黑名单外面。 - 改完 php.ini 必须重载 / 重启对应版本的 PHP-FPM 才生效(宝塔:软件商店 → PHP → 设置 → 重载配置,或
systemctl reload php-fpm-81)。 - 本工具只定义
ipr_前缀的辅助函数,不定义e()等通用函数,也不会修改宿主站点的默认时区,避免和现有框架冲突。 - 注意:部分虚拟主机禁用了
auto_prepend_file,此时改用方式一。
方式三:JS 脚本(任意网站,包括静态站 / 非 PHP 站)
在页面 </body> 前加:
<script src="https://your-site.com/ip-record/embed/ip-record.js" defer></script>- 脚本会自动把
/embed/ip-record.js推导成/api/track.php作为上报地址;如果脚本被 CDN 镜像或改了路径,用data-endpoint显式指定:
<script src="https://cdn.example.com/ip-record.js"
data-endpoint="https://your-site.com/ip-record/api/track.php" defer></script>- 支持跨域上报(默认允许任意来源,可在
config.php的cors.allow_origin收紧)。 - 会额外记录页面标题和来源页;使用
sendBeacon/fetch keepalive,不阻塞页面。 - SPA 切换路由后可手动再报一次:
window.IpRecord && window.IpRecord.track();重要限制:JS 只能“记录”,无法真正阻止页面加载。需要拦截黑名单时必须使用方式一或方式二。两者可以同时使用(服务端记录 + JS 补标题),不会重复计数。
三种方式对比
| 方式一 require | 方式二 auto_prepend | 方式三 JS | |
|---|---|---|---|
| 适用站点 | PHP 站 | PHP 站(整站) | 任意站点(含静态页) |
| 记录 IP / 归属地 / 时间 / URL | ✅ | ✅ | ✅ |
| 记录页面标题 | ❌(服务端拿不到) | ❌ | ✅ |
| 拦截黑名单(阻断访问) | ✅ | ✅ | ❌ |
| 需要改代码 | 每页一行 | 不需要 | 每页一行 |
后台功能
入口:/ip-record/admin/login.php
访客记录
- 概览:总访问、今日、近 7 天、独立 IP、已拦截、数据库体积
- 近 14 天访问量柱状图
- 筛选:关键词(IP / URL / 标题 / 归属地)、访问状态(正常 / 已拦截)、起止时间、每页条数
- 快捷范围:今天 / 近 7 天 / 近 30 天 / 全部
- 分页:首页 / 上一页 / 页码窗口 / 下一页 / 末页,筛选条件自动保留
- 每行可「拉黑」该 IP,或删除单条记录
- 右上角「导出 CSV」按当前筛选条件导出(UTF-8 带 BOM,Excel 直接打开)
IP 黑名单
- 支持单个 IPv4 / IPv6,也支持 CIDR 网段:
1.2.3.4、1.2.3.0/24、2001:db8::/32 - 可填写备注,记录添加时间
- 「命中检测」:输入 IP 即时判断会被哪条规则拦截,不写库
- 黑名单改动后缓存会在
guard.cache_ttl(默认 10 秒)内生效;想立即生效可把该值设为0
数据清理
- 按时间段清空:填开始 / 结束时间(可只填一端),删除该区间内的记录
- 清理历史:一键删除 7 / 30 / 90 / 180 / 365 天前的记录
- 清空全部:需勾选确认,删除后自动
VACUUM收缩数据库文件 - 删除前会二次确认,所有写操作都校验 CSRF Token
配置说明(config.php)
| 配置项 | 默认 | 说明 |
|---|---|---|
timezone | Asia/Shanghai | 时间显示与按天统计的时区 |
db_path | data/ip_records.db | SQLite 文件路径,可改到 Web 根目录之外 |
ip_source | remote_addr | 取 IP 的方式。只有接了 CDN / 反向代理才改成 auto |
trust_proxy_headers | CF / X-Real-IP / XFF | auto 模式下依次尝试的请求头 |
ip2region.cache_policy | file | file 省内存;vector 更快;content 整库进内存(约 11MB/请求,FPM 下慎用) |
guard.enabled | true | 是否启用黑名单拦截 |
guard.block_mode | 403 | 403 返回拦截页;redirect 跳转到 redirect_url |
guard.cache_ttl | 10 | 黑名单缓存秒数,0 = 每次查库、立即生效 |
log.dedupe_seconds | 0 | 同 IP + 同页面在该秒数内只记一条,0 不去重 |
log.skip_extensions | 常见静态后缀 | 这些请求不记录 |
log.ignore_ips | [] | 不记录也不拦截的 IP(本机调试用) |
cors.allow_origin | * | JS 上报允许的来源,可改成数组收紧 |
cors.max_per_minute | 120 | 单 IP 每分钟上报上限,0 关闭 |
admin.default_username/password | admin / admin123 | 仅首次初始化生效 |
admin.login_max_attempts | 5 | 窗口内登录失败次数上限 |
admin.login_lock_seconds | 300 | 失败计数窗口 = 锁定时长 |
真实 IP:接了 CDN / 反向代理怎么办
默认只信任 REMOTE_ADDR(最安全,无法伪造)。如果站点前面有 Cloudflare、Nginx 反代、宝塔 CDN,所有访客都会显示为代理的 IP,需要:
'ip_source' => 'auto',
'trust_proxy_headers' => [
'HTTP_CF_CONNECTING_IP', // Cloudflare
'HTTP_X_REAL_IP', // Nginx
'HTTP_X_FORWARDED_FOR', // 通用,取最左侧
],⚠️ 安全提示:一旦信任这些头,访客可以自己伪造 X-Forwarded-For 来绕过黑名单。只有在无法绕过代理直连你的服务器(源站只允许 CDN 回源、或代理会覆盖该头)时才开启。Nginx 推荐在反代处这样设置:
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;安全加固清单
- 改掉默认密码(后台「修改密码」)。
- 不要暴露数据库目录。已内置
data/.htaccess和lib/.htaccess供 Apache 使用;Nginx 需手动加:
location ^~ /ip-record/data/ { deny all; return 403; }
location ^~ /ip-record/lib/ { deny all; return 403; }
# 或干脆把 db_path 指到网站根目录之外:
# 'db_path' => '/var/lib/ip-record/records.db',- 生产环境删除
check.php、demo.php、demo-js.html,或至少限制访问。 - 后台建议走 HTTPS(Session Cookie 会自动加
secure)。 - 定期备份
data/ip_records.db(连同-wal、-shm文件一起,或先PRAGMA wal_checkpoint(TRUNCATE))。 - 如担心被恶意刷量,调低
cors.max_per_minute,并设置log.dedupe_seconds。
ip2region 说明
- SDK 位于
lib/ip2region/Searcher.class.php(官方 PHP 绑定,纯 PHP 实现,无需 Composer、无需扩展)。 - IPv4 离线库:
lib/ip2region/data/ip2region_v4.xdb(约 11MB,已内置)。 - 数据来源:lionsoul2014/ip2region,Apache-2.0 License。
- 更新数据:从官方仓库
data/目录下载最新的ip2region_v4.xdb覆盖同名文件即可,代码无需改动。 - IPv6:默认未内置(官方
ip2region_v6.xdb约 37MB)。需要时下载后放到lib/ip2region/data/ip2region_v6.xdb,无需改配置即自动启用;未安装时 IPv6 访客归属地显示「未知」。 - 内网 / 保留地址(
127.0.0.1、10.x、192.168.x等)会显示「内网 / 保留地址」。
目录结构
ip-record/
├── config.php # 全部配置
├── check.php # 命令行自检(php check.php)
├── demo.php # 服务端接入演示
├── demo-js.html # JS 上报演示
├── .htaccess # 禁止目录浏览 / 保护敏感文件
├── assets/admin.css # 后台样式
├── admin/
│ ├── login.php # 登录
│ ├── logout.php # 退出(POST + CSRF)
│ ├── index.php # 访客记录:统计 / 筛选 / 分页 / 拉黑 / 删除
│ ├── blacklist.php # 黑名单管理 + 命中检测
│ ├── clear.php # 按时间段清空 / 清理历史 / 清空全部
│ ├── export.php # CSV 导出
│ ├── password.php # 修改密码
│ └── _layout.php # 布局与导航
├── api/
│ └── track.php # JS 上报接口(CORS / 图片埋点 / 限流)
├── embed/
│ ├── ip-record.php # 一行接入(记录 + 拦截)
│ ├── auto_prepend.php # auto_prepend_file 全站接入
│ └── ip-record.js # 前端上报 SDK
├── lib/
│ ├── bootstrap.php # 引导 / 自动加载 / 辅助函数
│ ├── Config.php # 配置容器
│ ├── Database.php # SQLite 连接 + 建表 + 管理员初始化
│ ├── IpUtil.php # 取真实 IP、IP 校验、CIDR 匹配
│ ├── IpLocation.php # ip2region 查询封装
│ ├── Visits.php # 记录写入 / 分页 / 统计 / 时间段删除
│ ├── Blacklist.php # 黑名单 + 文件缓存
│ ├── Guard.php # 服务端拦截与记录
│ ├── Auth.php # 登录 / Session / CSRF / 限流
│ ├── View.php # 分页、闪存消息、格式化
│ └── ip2region/ # 官方 PHP SDK + xdb 数据
└── data/ # SQLite 数据库、黑名单缓存(自动创建)数据表结构
visits(访问记录)
| 字段 | 说明 |
|---|---|
ip / ip_ver | 规范化 IP / 4 或 6 |
country region province city isp area | 归属地拆解与展示文本 |
host url | 站点域名与完整页面地址 |
page_title | 页面标题(仅 JS 上报有值) |
referer ua method | 来源、User-Agent、记录方式(GET / BEACON) |
blocked | 1 = 命中黑名单被拦截 |
client_id | 浏览器本地标识,用于去重 |
created_at / created_day | Unix 时间戳 / 本地日期(用于按天统计) |
blacklist(ip 唯一,支持 CIDR)、admin_users(bcrypt 密码)、login_attempts(登录限流)、settings(元信息)。
常见问题
Q:加了 require_once 页面就打不开 / 白屏,但直接访问 ip-record.php 地址却正常?
A:九成是路径写成了网址。错误示例:
require_once 'http://192.168.1.110/ip-record/embed/ip-record.php'; // ❌ 网址不是文件路径require 只能加载本地文件,http:// 需要 allow_url_include=On(默认关闭),会报http:// wrapper is disabled in the server configuration 并致命错误。改成文件路径即可:
require_once 'C:/phpstudy_pro/WWW/your-site/ip-record/embed/ip-record.php'; // Windows 示例
// 或
require_once $_SERVER['DOCUMENT_ROOT'] . '/ip-record/embed/ip-record.php';即使强行开启 allow_url_include 也不要用:那是由服务器去请求这个网址,记录的会是服务器自己的 IP,
黑名单也拦不住访客页面,还存在远程代码执行风险。
如果改成文件路径后仍打不开,按顺序排查:
- 临时打开错误显示(或看 PHP 错误日志):
ini_set('display_errors', 1); error_reporting(E_ALL);,能看到真实原因; - 确认文件存在且可读:
var_dump(is_file($path), is_readable($path));; require必须是页面第一行语句,<?php之前不能有空格、空行或 UTF-8 BOM,否则拦截时无法发送 403 头;- 主机开启了
open_basedir时,路径必须在其允许目录内; - Linux 下检查权限:文件 644、目录 755,
data/需可写。
Q:开启 auto_prepend 后,某个站点首页 500,但其他站点和 ip-record 页面正常?
A:这是该站点代码与本工具的全局符号冲突,早期版本定义了全局函数 e(),而 Laravel、ThinkPHP 及不少主题也会定义 e(),prepend 先执行就会 Cannot redeclare e() 致命错误。
当前版本已改为 ipr_e(),并移除了其他通用全局函数、也不再修改宿主站点时区,替换新版文件即可。
如果仍 500,按以下顺序确认:
- 看该站点错误日志:
tail -n 30 /www/wwwroot/站点/error.log或/www/server/php/81/var/log/php-fpm.log,搜Fatal error; - 确认
auto_prepend_file路径存在且open_basedir允许访问(路径不对会让所有 PHP 页面 500); - 该站点根目录如果就是
ip-record,注意别让它自己的index.php与工具文件混淆; - 临时在该站点的
.user.ini里把auto_prepend_file置空,即可单独排除这个站点。
Q:某个站点(如 Z-Blog)首页 500,报 bootstrap.php on line 33 或 Class "Ipr\Config" not found?
A:本质是工具文件读不到,不是代码冲突。常见两类原因:
- 该站点在宝塔开启了「防跨站攻击(open_basedir)」,只允许自己的目录,而 ip-record 放在别的站点目录下 → PHP 拒绝读取
lib/→ 自动加载失败 → 类找不到; ip-record目录权限不是 PHP 运行用户可读(上传后属主是 root),用chown -R www:www ip-record && chmod -R 755 ip-record修正。
新版已做兜底:文件读不到时只写一条 [ip-record] 日志并跳过初始化,宿主站点不会 500。要恢复记录功能,任选其一:
- 把 ip-record 放进该站点目录内;
- 在该站点
.user.ini的open_basedir末尾追加 ip-record 路径(用冒号分隔); - 或对该站点关闭「防跨站攻击」。
注意:如果 auto_prepend 指向的文件本身就在 open_basedir 之外,PHP 会在执行任何代码前直接 500,这种兜底也救不了,必须先把路径放进允许列表。
另外确认该站点 PHP ≥ 7.4 且启用 pdo_sqlite;Z-Blog 官方推荐 8.0/8.1,PHP 8.5 的兼容性需自行确认。
Q:错误日志出现 [ip-record] ... 已跳过 是什么意思?
A:表示本次记录/SQL 操作出错,工具主动放弃以免影响宿主页面,站点仍正常访问。按日志里的原因(权限、open_basedir、数据库不可写)修复即可。
Q:为什么后台 IP 全是 127.0.0.1 / 服务器 IP?
A:站点前面有反代或 CDN,按上文配置 ip_source = auto 和对应请求头。
Q:加了黑名单,为什么还能访问?
A:① 确认站点使用服务端接入(方式一 / 二),JS 模式不能拦截;② 黑名单缓存默认 10 秒,等一会儿或把 guard.cache_ttl 设为 0;③ 检查 guard.enabled 是否为 true。
Q:记录量很大怎么办?
A:本工具按 WAL + 索引设计,单表百万级仍可用。建议:设置 log.dedupe_seconds(如 30)、用「清理历史」定期删旧数据、必要时把 db_path 放到 SSD 目录并定期 php check.php --vacuum。
Q:清空后数据库文件没变小?
A:SQLite 删除不会自动回收空间。「清空全部」会自动 VACUUM;部分删除可执行 php check.php --vacuum 或 sqlite3 data/ip_records.db "VACUUM;"。
Q:能在多个站点共用一个数据库吗?
A:可以,多个站点指向同一个 db_path 即可(SQLite 支持多进程读写,WAL 下并发良好)。但注意 data/ 目录权限与备份。
Q:拦截页想自定义?
A:改 config.php 的 guard.block_message,或用 guard.block_mode = redirect + guard.redirect_url 跳转到指定页面。
Q:会不会拖慢网站?
A:单次归属地查询约 0.1ms,SQLite 写入约 1ms 以内,且所有异常都会被吞掉(记录失败绝不影响页面)。黑名单命中走内存 + 文件缓存,几乎零开销。
License
本工具代码可自由用于商业/个人项目。内置的 ip2region SDK 与数据文件遵循其 Apache-2.0 License,版权归 lionsoul2014/ip2region 作者所有。
版本变更记录
v4.0.0(当前)
加载安全加固,工具加载失败绝不会拖垮宿主站点:
lib/bootstrap.php:核心类改为显式 require(Config / IpUtil / IpLocation / Database / Visits / Blacklist / Guard),
每个文件先is_file+is_readable预检,全部使用require_once;lib/bootstrap.php:Config.php不可读时写入[ip-record]日志并return,不再抛出致命错误;embed/auto_prepend.php:bootstrap 可读性预检 +try/catch Throwable+class_exists Guard守卫;embed/ip-record.php:同款预检与兜底;- 任何异常只写一条
[ip-record] ...日志,页面继续正常输出。
v3.0.0
修复「开启 auto_prepend 后某站点首页 500」:
- 全局助手函数改为
ipr_前缀(ipr_e等),不再定义e(),避免与 Laravel / ThinkPHP / Z-Blog 主题冲突; - 删除未使用的全局函数,引导结束后清理临时全局变量;
- 使用 auto_prepend 时不再修改宿主站点的默认时区(记录时间由
Visits::record显式换算)。
v2.0.0
- README 增加「用网址 require 引入 ❌」说明与排查清单;
- 补充绝对路径 /
$_SERVER['DOCUMENT_ROOT']/__DIR__三种正确写法。
v1.0.0
首个完整版本:SQLite 单文件存储、ip2region 本地归属地、后台分页/筛选/导出、
按时间段清空、IP 黑名单(支持 CIDR)、三种接入方式(服务端 require / auto_prepend / 前端 JS SDK)。