本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/待办事宜/PHP8.5兼容性与安装链路审计报告.md。

FlintHub — 安装链路审计 + PHP 8.4/8.5 兼容性报告（含实施计划）

一、结论摘要

安装链路

PHP 8.4（你手机服务器当前命中）

PHP 8.4 只引入两类与本项目相关的弃用：session_set_save_handler() 独立回调 与 隐式可空参数。

其余告警项（ord() / curl_close / imagedestroy / finfo_close）均为 8.5 才引入，8.4 下不会触发。

两项都是「每请求级」日志刷屏，现已全部消除。

PHP 8.5

本报告结论已用真实 PHP 8.4.25 / 8.5.10 便携版实测复核（见 §3.7），不是纯静态分析。

唯一的真实生产运行时证据来自你的手机服务器。

二、第一部分：安装链路审计

2.1 链路全貌

访问 install.php
  │
  ├─ ① 基础防护：error_reporting / 常量定义 / 载入 version.php
  ├─ ② 已安装判定：config.php 含 SPLITDB_DATA_PATH 或 data/meta/business.sqlite 存在
  │      └─ 命中 → renderAlreadyInstalled()（HTTP 410）并 exit
  ├─ ③ Session 加固：HttpOnly / SameSite=Lax / use_strict_mode / Secure（按 HTTPS 判断）
  │      └─ 生成 install_csrf 存入 session
  │
  ├─ ④ 分步向导（Alpine 控制，5 步）
  │      1 欢迎 → 2 许可协议（勾选） → 3 环境检测 → 4 管理员 → 5 安装中
  │
  └─ ⑤ POST action=install
         ├─ CSRF 校验（hash_equals，先 is_string 防护）
         ├─ 环境复检 envAllOk()
         ├─ 协议复检 $_POST['agree_license'] === '1'
         ├─ 字段校验（用户名 ≥2 / 邮箱格式 / 密码 ≥6）
         └─ runInstall()
              ├─ flock install.lock（非阻塞，防并发双装）
              ├─ session_write_close()（避免 config.php 的 session ini_set 告警）
              ├─ writeConfig() → 生成 config.php（MAIL_PASS_KEY 随机 32 字节）
              ├─ Schema::bootstrap()  ← 实测通过
              ├─ Schema::seedDefaults() ← 实测通过
              ├─ 创建管理员（users，role=admin，level=11，points=9999）
              ├─ 分配确定性 seed 头像
              └─ 原子写 protected/.install_done（tmp + rename）

2.2 核心链路实测结果

以临时 dataPath 跑真实代码（不触碰站点 data/），PHP 8.0.2：

【1】Schema::bootstrap() 完成，耗时 1625 ms，新建 9 个目录条目
【2】目录树：meta / meta/task_queue / meta/search / bucket/active/2026Q3
            / bucket/archive / extern / lock / log / runtime   全部 ✓
【3】meta 库：business.sqlite(23 表) / main_index.sqlite(2 表)
            / sessions.sqlite(1 表) / global_id.sqlite(id_generator)  全部 ✓
【4】队列库：queue_0 / queue_1 / queue_2  全部 ✓
【5】默认数据：settings 12 行 / categories 1 行 / level_config 11 行  ✓
【6】reply_index 索引：idx_reply_index_pid, idx_reply_index_uid,
                    idx_reply_index_status   ← P-2 新装路径生效 ✓
【7】data 防护文件：.htaccess ✓  web.config ✓
【8】幂等复跑：新建 0 条目，无报错 ✓

关键交叉验证 —— 新装库与生产库逐表比对：

→ 全新安装产出的库结构与现网一致，安装链路核心无缺陷。

2.3 协议勾选专项核查

先说结论：当前代码的勾选逻辑是正确的，没有发现缺陷。

实现方式（install.php:586-599）：

        
  
     
    
...协议全文...
    
      
      我已阅读并同意上述《许可协议》（MIT License）
    
    下一步 →
  

逐环节验证：

未完成的一步（需说明）：本应再用真实浏览器点击验证，但沙箱拦截了 Chromium 下载

（agent-browser install 写入 ...\chrome-153.0.8010.36\locales\et_NEUTER.pak 被拒），

故未做真人点击实测。这一环建议你自己 5 秒确认：

http://127.0.0.1/.workbuddy-ai/tmp/install-test/install.php

（该极小测试目录仅含 install.php / version.php / LICENSE / fhstate.js，

不依赖站点已安装状态，经你的 Nginx 已返回 200。）

2.4 发现的问题（安装链路）

问题 1｜⚠️ 设计脆弱点：整个向导强依赖 Alpine，无降级

[x-cloak]{display:none!important} 配合 5 个步骤卡片全部带 x-cloak。

**若 assets/lib/fhstate.js 加载失败（404 / JS 被禁 / CDN 拦截 / 路径错误），

所有步骤卡片将永久 display:none** —— 页面只剩步骤指示条，

用户既看不到协议也无法勾选，更无法进入下一步。

这高度符合「协议不能勾选」的历史反馈特征：用户看到的不是"勾选框点不动"，

而是"协议步骤没有内容/点了没反应"。

当前状态：install.php 与 assets/lib/fhstate.js 均与 flinthub1.0.0/ 发行版

逐字节一致，说明修复（若曾修复）已包含在发行版内。但**无 <noscript> 兜底、

无"Alpine 未启动"检测**这一脆弱性依然存在。

建议：加一段极轻量的兜底 —— 在向导末尾脚本里检测 window.Alpine，

若不存在则移除所有 x-cloak 并给出提示；或补 <noscript> 提示块。

（属加固项，非缺陷修复。）

问题 2｜ℹ️ 服务端协议校验形同虚设（低危）

步骤 4 的表单里硬编码了 <input type="hidden" name="agree_license" value="1">，

而服务端只校验该字段等于 '1'。因此直接 POST 即可绕过协议勾选，

前端勾选框实际只起提示作用。协议为 MIT，风险可忽略，如需要可改为

"步骤 4 提交时由前端把 agreed 一并提交"再服务端校验。

问题 3｜ℹ️ 无"安装前置自检"独立入口

环境检测只在向导第 3 步与 POST 时执行。若环境不达标，用户要先点完前两步才知道。

非缺陷，属体验优化空间。

三、第二部分：PHP 8.4 / 8.5 兼容性

3.1 扫描方法

1. 取 PHP 官方 migration84.deprecated + migration85.incompatible + migration85.deprecated 全量条目，逐条转为可扫描规则；
2. 对 app/ plugins/ cli/ lang/ + 根目录共 556 个 PHP 文件做正则扫描，

剔除注释行、字符串内反引号、已可空参数等误报；

1. 对无法正则判定的项（解构非数组、浮点转 int、printf 精度、字符串自增）

做定向人工复核；

1. 补充：首轮 8.5 扫描漏掉了 8.4 的 session_set_save_handler()，

后经用户手机服务器线上报错暴露，遂扩写为 scan_php81_85.py（覆盖 8.0–8.5）重扫全库，

补齐本节 §3.3。

3.2 HIGH（8.5）— 必修（1 处）

H-1 app/Helpers/CoverTemplate.php:155 — ord() 传多字节字符串

PHP 8.5 变更：ord() 传入非单字节字符串已弃用（官方注释：这通常是 bug 的征兆）。

触发条件（必然触发）：

// CoverTemplate.php:118
$chars = \preg_split('//u', $title, -1, PREG_SPLIT_NO_EMPTY);  // 按「字符」切分

// CoverTemplate.php:126-131
foreach ($chars as $ch) { $u = self::charUnits($ch); ... }

// CoverTemplate.php:155
private static function charUnits(string $ch): float {
    $o = \ord($ch);      // ← 中文"中"是 3 字节，ord() 在此收到多字节字符串

preg_split('//u', ...) 按 UTF-8 字符切分，中文/全角字符是 2–4 字节。

即：任何含中文的标题在生成封面图时都会触发 E_DEPRECATED。

对一个中文论坛而言，这是最常见路径，且日志会被刷屏。

✅ 真机实测（PHP 8.5.10）—— 已确认触发：

实际报错原文：

Deprecated: ord(): Providing a string that is not one byte long is deprecated.
Use ord($str[0]) instead in app/Helpers/CoverTemplate.php on line 155

实测告警条数（与非 ASCII 字符数完全成正比）：

结论：8.5 下必触发、8.4 下不触发，与版本矩阵完全一致；纯 ASCII 标题不触发。

修复方向（语义等价，零行为变更）：

private static function charUnits(string $ch): float
{
    if (\strlen($ch) > 1) {
        return 1.0;                       // 多字节 = 中文/全角，直接返回 1 单位
    }
    $o = \ord($ch);                       // 此时必为单字节，安全
    return ($o < 0x80) ? (\preg_match('/[MWmw@#%&]/', $ch) ? 0.9 : 0.5) : 1.0;
}

依据：\strlen($ch) === 1 时 ord() 必为单字节；>= 0x80 的单字节分支原样保留，

且原代码对多字节字符也是返回 1.0，故行为完全一致。

3.3 PHP 8.4 专项 — 线上实测命中项

本节由真实运行时报错驱动（用户手机服务器，PHP 8.4+），优先级高于静态扫描结论。

H-2 ✅ 已修 app/init.php:41 — session_set_save_handler() 传「独立回调」

PHP 8.4 变更：session_set_save_handler() 若传入「独立回调」（第 1~8 个参数为 callable），

必须改为传入一个实现 SessionHandlerInterface 的对象。

线上原始报错（用户提供）：

Deprecated: session_set_save_handler(): Providing individual callbacks instead of
an object implementing SessionHandlerInterface is deprecated
in /storage/emulated/0/Android/data/com.xiaojiangi.wstoolbox/files/WSToolbox/flinthub/app/init.php on line 41

原实现：6 个闭包（open / close / read / write / destroy / gc）直接传给

session_set_save_handler()。该写法每次请求都会触发一次 E_DEPRECATED ——

对论坛而言等于每个页面请求都往日志写一行，日志会被迅速刷满。

修复方案（已落地）：

关键设计决策（防行为漂移）：

1. 刻意不实现 SessionUpdateTimestampHandlerInterface（validateId / updateTimestamp）。

原写法只传了 6 个回调，未提供第 7/8 个；PHP 在 session.use_strict_mode=1 下走的是

「read() 返回空串即判定为新 ID」的默认路径。若补上 validateId，会改变会话固定攻击防护的判定路径，

属于隐性行为变更，故明确不补。

1. 失败返回值与原实现逐一对齐：read → ''、write → false、destroy → false、gc → 0。
2. TTL 保持 1800 秒（expires = time() + 1800），与原闭包完全一致。
3. 沿用 Database::getSessionConnection()（独立 PDO 连接，与业务连接物理隔离），

避免 SplitDB 的 2014 游标冲突。

实测验证（本机 PHP 8.0.2 + 真实 sessions.sqlite）：

关于 PHP 7.3.4：php -l 在 7.3.4 下报联合类型 string|false 语法错误 —— 这是预期的。

项目本就要求 PHP 8.0+（install.php:74 有版本门禁），且 app/SplitDB/CountingPDO.php:32

早已使用 int|false。7.3 不在支持范围内，无需处理。

✅ 真机复核（PHP 8.4.25 / 8.5.10）—— 复现 + 修复双验证

用便携版 PHP 跑同一脚本，分别注册「旧闭包写法」与「新对象写法」：

8.4.25 / 8.5.10 上旧写法输出的告警与你手机上那条逐字一致：

Deprecated: session_set_save_handler(): Providing individual callbacks instead of
an object implementing SessionHandlerInterface is deprecated

这证明：① 你手机服务器的报错被准确复现；② 修复后该告警在 8.4 与 8.5 上均彻底消失。

M-4 ⚠️ 严重度由 MED 上调为 HIGH 隐式可空参数（2 处）

PHP 8.4 起弃用，8.5 仍弃用 —— 类型前缺 ? 会发 E_DEPRECATED。

佐证：两处 docblock 已写明 @param PDO|null $mainDb，即意图本就是可空，

只是语法漏了 ?。修复纯属补全，零行为变更。

✅ 真机实测：为什么它是 HIGH 而不是 MED

静态扫描时按「命中 2 处」记为 MED，但实测发现它每次请求都会触发 2 条：

[15-Sep-2026 11:44:51 Asia/Shanghai] PHP Deprecated:  app\SplitDB\ViewCounter::inc(): Implicitly marking
parameter $mainDb as nullable is deprecated, the explicit nullable type must be used instead
in ...\app\SplitDB\ViewCounter.php on line 30

[15-Sep-2026 11:44:51 Asia/Shanghai] PHP Deprecated:  app\SplitDB\ViewCounter::flush(): Implicitly marking
parameter $mainDb as nullable is deprecated, the explicit nullable type must be used instead
in ...\app\SplitDB\ViewCounter.php on line 57

触发链（关键在 index.php:285）：

// index.php:280 —— 每次请求都会注册这个 shutdown 钩子
register_shutdown_function(function () {
    \app\Helpers\Settings::flushCounters();
    try {
        \app\SplitDB\ViewCounter::flush();   // ← index.php:285 无条件调用
    } catch (\Throwable $e) { ... }
});

ViewCounter::flush() 是无条件调用的，因此类文件 ViewCounter.php 每次请求都会被编译，

两个隐式可空参数就在编译期各发一条告警 → 每请求固定 2 条。

⚠️ 修正一处早先的判断：先前曾推测「未启用 APCu 时只有 inc() 一条路径会命中」——

这是错的。隐式可空参数是编译期告警，只要 ViewCounter.php 被加载就必然触发，

与 APCu 是否启用、是否真的浏览主题都无关。实测已证实每请求 2 条。

实测计数：19 条路由的冒烟测试中，8.4.25 与 8.5.10 均在 protected/error.log 中

留下 各 21 次 inc() + 21 次 flush() = 42 行（对应约 21 次请求）。

结论：这与 H-2 属于同一性质的问题（每请求级日志刷屏），

在 8.4 和 8.5 上都会触发。只改 2 个字符即可彻底消除，性价比最高，

建议与 H-2 同批发布。

⚠️ 顺带发现：日志被应用改道

config.php:85 有 ini_set('error_log', __DIR__ . '/protected/error.log');

——应用的告警不会写到 php.ini 指定的日志，而是全部落到

protected/error.log。排查线上问题时请直接看这个文件（手机端路径同理）。

3.4 MED — 建议修（7 处）

M-1 弃用函数：curl_close()（2 处）

PHP 8.5 起 curl_close() 已弃用（CurlHandle 对象自动释放）。

修复：直接删除该行。注意：删除前确认该句柄不再被引用（两个位置都是请求内局部句柄，安全）。

M-2 弃用函数：imagedestroy()（4 处）

PHP 8.5 起已弃用（GdImage 对象自动释放）。

修复：删除调用即可（对象在作用域结束/引用清零时自动释放）。

Upload.php:220 需保留 return;，仅删 \imagedestroy($src);。

M-3 弃用函数：finfo_close()（1 处）

修复：删除该行。上下文是 $finfo 局部变量，finfo_file() 已调用完毕。

M-5 gc_collect_cycles() 返回值语义变更（1 处，LOW）

修复：无需改动，登记备查即可。

3.5 已确认「清白」的项（无需处理）

以下变更点已逐项扫描，本项目未命中：

3.6 风险总览

合计：7 个文件（1 新增 + 6 修改）、11 个代码位置，全部为「删除调用」或「补 1 个字符」级别，无逻辑重构。

全部 ✅ 已修复，已打包为 update/3/（V1.0.3）。

修复后复核：全库 568 个 PHP 文件在 8.4.25 与 8.5.10 下编译期告警归零；

19 条路由冒烟后 protected/error.log 为空（修复前为 42 行）。详见 §3.7。

3.7 真机实测记录（PHP 8.4.25 / 8.5.10）

为把结论从「静态分析」升级为「实测」，本轮下载了 PHP 官方便携版

8.4.25 与 8.5.10（Windows NTS x64）并配置 pdo_sqlite / mbstring /

fileinfo / curl / gd / openssl，做了四组验证。

7.1 全库编译期扫描（568 个 PHP 文件）

用 php -l 对 app/ cli/ plugins/ lang/ update/ 待办事宜/ + 根目录共 568 个 PHP 文件

逐一做编译检查（脚本：.workbuddy-ai/tmp/scan_compile_84_85.py）：

✅ 这是权威结论：全库除 ViewCounter.php 外，再无任何编译期弃用

（包括此前静态扫描怀疑的各类隐式可空参数）。比正则扫描可靠得多。

7.2 站点路由冒烟（19 条路由）

用 PHP 内置服务器 + 模拟 nginx try_files 的路由脚本

（.workbuddy-ai/tmp/router.php）跑真实路由：

两个版本结果完全一致，页面字节数一致（首页 63,863 字节）。

⚠️ 但日志并非干净 —— 见 7.3。

7.3 运行期告警实测

结论：版本矩阵 100% 得到实测验证 —— 8.4 只中 H-2 与 M-4，其余为 8.5 专属。

7.4 关键运维发现

1. 告警不写在 php.ini 指定的日志里 —— config.php:85 会

ini_set('error_log', __DIR__ . '/protected/error.log')。

排查线上问题请直接看 protected/error.log（手机端同理）。

1. 实测 19 条路由后，protected/error.log 中新增 42 行 M-4 告警，

证明「每请求 2 条」的判断成立。

1. 日志中另有 15 条 Template not found: home/index_default (/)，

均为 9-14 的历史记录，本轮冒烟未复现，且 app/Views/home/index_default.php

文件存在 —— 属已解决的旧问题，与 PHP 版本无关。

四、第三部分：实施结果

4.0 全部完成 ✅

2026-09-15 已按用户指令一次性完成全部 11 处修复，并打包为 update/3/（V1.0.3）。

交付物：update/3/ —— 7 个源码文件 + version.php（V1.0.3）+ 改动说明.md（9 个文件）。

不涉及 CSS/JS（sw.js 无需递增）、不涉及数据库结构、不涉及配置项。

4.1 修复后复核结果

4.2 验证方法（可复跑）

4.3 后续可选：安装链路加固（阶段 D，未做）

本次未做（不在用户指令范围内）。属锦上添花，建议单独评估后再定。

4.4 上线前你需自行确认的环境项（代码之外）

先确认手机服务器到底是哪个版本（决定上面哪些项真的会命中）：

查版本的方法：手机端建一个 pv.php，内容 <?php echo PHP_VERSION;，浏览器访问即可。

或在 WSToolbox 的 PHP 设置页看版本号。

看日志的正确位置：不是 php.ini 里 error_log 指向的文件，

而是站点目录下的 protected/error.log（config.php:85 会改写 error_log）。

其余环境项：

1. php.ini 是否含 zend_extension=opcache.so / php_opcache.dll

→ PHP 8.5 起 opcache 始终内置，该行会触发告警，应删除。（8.4 无此问题）

1. php.ini 是否含 disable_classes → 8.5 已移除该指令，应删除。
2. php.ini 的 register_argc_argv → 建议显式设 0（非 CLI 从查询串推导 argc/argv 已弃用）。
3. display_errors / error_reporting → 建议生产关闭 E_DEPRECATED 显示，

避免升级后日志/页面被弃用告警污染（但不应掩盖 H-1 / M-4，仍应修）。

1. 服务器 PHP 是否已装 pdo_sqlite / mbstring / fileinfo / gd 或 imagick / curl / openssl

→ 与 install.php 的环境检测项一致。

1. ~~是否启用 APCu~~ → 已证实与 M-4 无关（编译期告警，无条件触发），无需确认。

4.5 红线约束（沿用既有约定）

• 本次只动上述 7 个文件；H-2 例外地新增了 app/Core/SessionHandler.php

（新增独立类，未触碰 app/Core/ 既有任何文件）；

• 不碰 app/Controllers/Admin/、其它插件；
• 所有 SQL 走 prepare() + 参数绑定；
• 输出统一 $this->e() / htmlspecialchars()；
• 所有文件 UTF-8 无 BOM + LF；
• 打包放 update/3/，版本文件末位数字 = 目录号；若涉及 CSS/JS 需同步递增 sw.js 版本。

（H-2 与 M-4 均不涉及任何 CSS/JS，故若只发这两项，sw.js 无需递增。）

4.6 回滚方案

本次全部改动均为「消除告警」性质，不涉及业务逻辑、SQL、模板与静态资源，回滚后行为与升级前完全一致。

五、附录

5.1 审计产物

交付物（源码侧）：

发布包：update/3/（V1.0.3）—— 上述 7 个文件 + version.php + 改动说明.md；

另有 update/增量补丁1.0.3.zip（同内容压缩包，便于上传）。

5.2 遗留事项

1. 待清理目录：.workbuddy-ai/tmp/install-e2e/（一次未采用的整项目复制尝试留下）、

.workbuddy-ai/tmp/install-core-data/（测试库）、.workbuddy-ai/tmp/php84、php85

（便携版 + zip，约 140MB）。等你确认后我再删（保留着方便后续复测）。

1. 未完成的实测：协议勾选的真人点击验证（Chromium 下载被沙箱拦截）。

可自行访问 http://127.0.0.1/.workbuddy-ai/tmp/install-test/install.php 确认。

1. ~~8.4 / 8.5 运行时实测缺失~~ → 已解决：本轮下载了 8.4.25 / 8.5.10 便携版，

全部结论已实测复核（见 §3.7）。

1. ~~M-4 尚未修~~ → 已修，见 §4.0。
2. ~~H-2 / M-4 尚未打包~~ → 已打包为 update/3/（V1.0.3），含全部 7 个源码文件。
3. 是否要同步 flinthub1.0.0/ 发布目录：该目录是发布快照，

本次修复未同步进去（保持快照纯净）。若要做下一个发行版，需另行同步。

1. protected/error.log 已清空：原 57 行（含 15 条 9-14 的 Template not found 历史记录）

已备份到 .workbuddy-ai/backup/20260915_errorlog/error.log.before-truncate，当前为空。

1. app/Helpers/Plugin.php 使用 CRLF 换行 —— 既有状态，非本次引入

（flinthub1.0.0 与 update/1 中该文件同样为 CRLF）。本次刻意保持原样以免产生整文件 diff。

全库共 15 个文件含 CRLF，若要统一为 LF 建议单独做一次格式化提交。

1. 阶段 D（安装链路加固）未做 —— 不在本次指令范围内，见 §4.3。