平时都是用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帖上来。

Snipaste_2026-11-20_16-20-41.png

IP 访问记录工具(PHP + SQLite + ip2region)

一个开箱即用的访客 IP 记录与拦截工具:记录 IP / 归属地 / 时间 / 页面 / 来源,后台分页查看、按时间段清空,支持 IP 黑名单,命中黑名单的访客在页面加载前直接被拦截。

  • 单文件 SQLite,无需 MySQL,无需 Redis,无需 Composer
  • 归属地查询使用内置的 ip2region 纯 PHP SDK + 官方离线库(本地文件,不联网)
  • 两种接入方式:服务端一行 require(推荐,记录 + 拦截)或 一段 JS 脚本(任意网站,仅记录)
  • 后台含登录、CSRF 防护、登录失败限流、CSV 导出、单条删除、按天趋势图

环境要求

项目要求
PHP7.4 及以上(推荐 8.1+)
扩展pdo_sqlite(必需)、sqlite3(可选)、mbstring(推荐)
Web 服务器Apache / Nginx / IIS / 宝塔 / 虚拟主机均可
目录权限data/ 可写(用于数据库与缓存)

查看环境是否满足:

php check.php

会输出 PHP 版本、SQLite 状态、数据库记录数、归属地库状态,并用几个样例 IP 实测归属地查询。


快速开始

  1. 把整个 ip-record/ 目录上传到网站目录,例如:
/www/wwwroot/your-site/ip-record/
  1. 访问 https://your-site.com/ip-record/admin/login.php

    • 默认账号:admin
    • 默认密码:admin123
    • 首次登录后请立刻在「修改密码」中修改(账号密码只在第一次初始化数据库时从 config.php 读取,之后改配置不会生效)
  2. 在网站页面接入记录(三选一,见下一节)。
  3. 打开后台「访客记录」即可看到数据。
首次访问任意入口会自动创建 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)

配置项默认说明
timezoneAsia/Shanghai时间显示与按天统计的时区
db_pathdata/ip_records.dbSQLite 文件路径,可改到 Web 根目录之外
ip_sourceremote_addr取 IP 的方式。只有接了 CDN / 反向代理才改成 auto
trust_proxy_headersCF / X-Real-IP / XFFauto 模式下依次尝试的请求头
ip2region.cache_policyfilefile 省内存;vector 更快;content 整库进内存(约 11MB/请求,FPM 下慎用)
guard.enabledtrue是否启用黑名单拦截
guard.block_mode403403 返回拦截页;redirect 跳转到 redirect_url
guard.cache_ttl10黑名单缓存秒数,0 = 每次查库、立即生效
log.dedupe_seconds0同 IP + 同页面在该秒数内只记一条,0 不去重
log.skip_extensions常见静态后缀这些请求不记录
log.ignore_ips[]不记录也不拦截的 IP(本机调试用)
cors.allow_origin*JS 上报允许的来源,可改成数组收紧
cors.max_per_minute120单 IP 每分钟上报上限,0 关闭
admin.default_username/passwordadmin / admin123仅首次初始化生效
admin.login_max_attempts5窗口内登录失败次数上限
admin.login_lock_seconds300失败计数窗口 = 锁定时长

真实 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;

安全加固清单

  1. 改掉默认密码(后台「修改密码」)。
  2. 不要暴露数据库目录。已内置 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',
  1. 生产环境删除 check.php、demo.php、demo-js.html,或至少限制访问。
  2. 后台建议走 HTTPS(Session Cookie 会自动加 secure)。
  3. 定期备份 data/ip_records.db(连同 -wal、-shm 文件一起,或先 PRAGMA wal_checkpoint(TRUNCATE))。
  4. 如担心被恶意刷量,调低 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)
blocked1 = 命中黑名单被拦截
client_id浏览器本地标识,用于去重
created_at / created_dayUnix 时间戳 / 本地日期(用于按天统计)

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,
黑名单也拦不住访客页面,还存在远程代码执行风险。

如果改成文件路径后仍打不开,按顺序排查:

  1. 临时打开错误显示(或看 PHP 错误日志):ini_set('display_errors', 1); error_reporting(E_ALL);,能看到真实原因;
  2. 确认文件存在且可读:var_dump(is_file($path), is_readable($path));;
  3. require 必须是页面第一行语句,<?php 之前不能有空格、空行或 UTF-8 BOM,否则拦截时无法发送 403 头;
  4. 主机开启了 open_basedir 时,路径必须在其允许目录内;
  5. Linux 下检查权限:文件 644、目录 755,data/ 需可写。

Q:开启 auto_prepend 后,某个站点首页 500,但其他站点和 ip-record 页面正常?
A:这是该站点代码与本工具的全局符号冲突,早期版本定义了全局函数 e(),而 Laravel、ThinkPHP 及不少主题也会定义 e(),prepend 先执行就会 Cannot redeclare e() 致命错误。
当前版本已改为 ipr_e(),并移除了其他通用全局函数、也不再修改宿主站点时区,替换新版文件即可。

如果仍 500,按以下顺序确认:

  1. 看该站点错误日志:tail -n 30 /www/wwwroot/站点/error.log 或 /www/server/php/81/var/log/php-fpm.log,搜 Fatal error;
  2. 确认 auto_prepend_file 路径存在且 open_basedir 允许访问(路径不对会让所有 PHP 页面 500);
  3. 该站点根目录如果就是 ip-record,注意别让它自己的 index.php 与工具文件混淆;
  4. 临时在该站点的 .user.ini 里把 auto_prepend_file 置空,即可单独排除这个站点。

Q:某个站点(如 Z-Blog)首页 500,报 bootstrap.php on line 33 或 Class "Ipr\Config" not found?
A:本质是工具文件读不到,不是代码冲突。常见两类原因:

  1. 该站点在宝塔开启了「防跨站攻击(open_basedir)」,只允许自己的目录,而 ip-record 放在别的站点目录下 → PHP 拒绝读取 lib/ → 自动加载失败 → 类找不到;
  2. 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)。

标签: none

添加新评论