v1.4.1

本版要点

项目宠物「小盾」与设计图

• 新增项目宠物 docs/mascot.svg（小盾：盾 + 放大镜），以及架构设计 / 功能设计 / 请求生命周期三张 SVG 设计图（docs/svg/）
• 被拦截的浏览器请求现在收到一页 HTML 拦截页（src/BlockPage.php）：小盾 + 状态码 + 命中的检测器名称；API / curl 等客户端仍收到纯文本 block_message，行为不变
• 拦截页只展示检测器名，载荷与正则细节仍只进日志；页面带 noindex，跟随系统深浅色

原生 PHP 支持

• 不装 Composer 也能用：把 src/ + config/ 拷进项目，require 'src/helpers.php' 即可 —— 该文件自带 PSR-4 加载器（Composer 存在时它什么都不做）
• 新增 prepend.php，配合 auto_prepend_file 让整个站点零改动接入；CLI（cron / 队列）自动跳过，配置可用环境变量 SECURITY_CONFIG 指向自己的副本
• 配置缺失时抛出可捕获的说明性异常，不再泄露绝对路径的致命错误
• 文档补上原生环境两个必改项：identity.session.cookie 要改成 PHPSESSID（否则会话劫持检测静默失效）、反代下要配 trusted_proxies

性能

同一台机器交替测量（PHP 8.3，300 次取最优）：

请求形态	优化前	优化后
3 个小字段	8.9 ms	2.5 ms
典型表单 · 10 字段	21.7 ms	6.0 ms
含 128 KB 大字段	16.4 ms	12.4 ms

• 正则预筛：每个检测器的 pattern 按 flag 分组拼成备用表达式，一次 preg_match 返回 0 就整组跳过；只有确定的"不匹配"才跳过，false 一律回退逐条跑，结果与逐个匹配完全一致（tests/Detector/PrefilterTest.php 用全量语料两万多条断言守住）
• 超过 8 KB 的值绕过预筛直接跑单条 pattern（组合表达式在大文本上反而更慢）
• 空值不进扫描循环；会话指纹不再每次重写整条记录；Redis all() 改为一次 MGET
• 新增 scripts/benchmark.php，可自行复测

修复

• 具名 HTML 实体绕过：<script> 之前完全没进检测（数字形式 < 会命中）
• FileStorage 读加共享锁：写入方会截断文件，无锁读能读到「空状态」，而所有调用方都当成"还没绑定过" —— 并发下会话劫持检测静默失效、暴力破解计数被重置
• IPv4-mapped IPv6：::ffff:203.0.113.5 之前被归一成 ::，双栈 / Swoole 下所有客户端塌缩到同一个 ::/64，会话指纹里的 IP 因子形同失效
• IP 黑名单：窗口过期的计数条目不再永久驻留（攻击者轮换 IP 可无限撑大存储）；生效中的封禁不再被窗口滚动提前解除；存储里读到非数组不再被当作封禁
• 日志轮转同一秒内的两次轮转不再互相覆盖（原会丢文件）
• 登录锁定对缺 locked_until 的旧格式记录不再抛警告（Laravel 错误处理器下曾变 500）
• UploadDetector 直接以对象作为字段值调用时不再致命错误

兼容性与测试

• PHP 8.0 – 8.4 全版本验证：lint、全检测器运行时、完整测试套件在 8.3 / 8.4 全绿（测试套件本身需要 PHPUnit 12，故跑测试要求 PHP >= 8.3）
• 451 个测试、31603 条断言
• 运行时零扩展依赖（不依赖 mbstring），不需要 Composer

---

Highlights (EN): project mascot + three SVG design diagrams; HTML block page with the mascot for browsers (API clients keep plain text); Composer-free install (src/helpers.php self-loads its PSR-4 map) and prepend.php for auto_prepend_file; regex prefilter making scans ~3.5x cheaper (plus scripts/benchmark.php); fixes for a named-HTML-entity detection bypass, unlocked storage reads, IPv4-mapped IPv6 masking, IP blacklist entry reaping, log rotation collision and a lockout warning; PHP 8.0–8.4 verified, 451 tests / 31603 assertions.