本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/docs/插件审计报告.md。

FlintHub 插件审计报告

一、结论摘要

没有发现「一票否决」级的安全漏洞（无反序列化/动态执行、无 SQL 注入、无路径穿越、无 XSS 输出绕过、CSRF 覆盖率 100%）。

问题集中在 1 个功能性致命 BUG、积分/用户组绕过核心封装、以及主题变量化改造不彻底三类。

扫描器原始命中 285 条，经逐条源码复核剔除 43 条误报（占位符变量 {$ph}、注释内关键词、var(--mn-*, #fff) 合法 fallback、PDO::quote() 已转义、白名单 in_array 守卫等），下表为复核后确认值。

最需要立刻处理的两件事：

1. plugins/invite/InviteController.php:46 —— 邀请码生成功能 100% 报 500（$db->begin() 调用了不存在的方法）。
2. plugins/user_level/views/admin.php:273 —— 后台按钮使用内联 onclick，违反零内联 P0 红线。

二、审计范围与方法

2.1 检查维度（对应规范章节）

2.2 审计手法（可复现）

# ① 静态扫描（词法预处理：剥离注释与字符串，避免注释内关键词误报）
C:/Users/Administrator/.workbuddy-ai/binaries/python/versions/3.13.12/python.exe .workbuddy-ai/tmp/audit2.py

# ② PHP 语法校验（单进程 token_get_all + TOKEN_PARSE，等价 php -l，390 文件约 2s）
/d/phpstudy_pro/Extensions/php/php8.2.9nts/php.exe .workbuddy-ai/tmp/lint_plugins.php

# ③ 双触发钩子双 include 回归（§9.4 ③；必须带框架引导，否则类未加载会产生假失败）
/d/phpstudy_pro/Extensions/php/php8.2.9nts/php.exe .workbuddy-ai/tmp/reinclude_test.php

# ④ 顶层符号静态普查（§9.4 ①）
grep -rnE '^[ \t]*(abstract |final )?(function|class|interface|trait) [A-Za-z_]' plugins/*/hook/

方法学提示：规范 §9.4 ③ 给出的 php -r 'include $f; include $f;' 不带框架引导，实测会对 12 个正常钩子文件报 Class "app\Helpers\I18n" not found 之类的假失败（类未自动加载，与双 include 无关）。必须改为先 require app/Core/Autoloader.php 再 include，才测得出真实结论（本报告结论基于带引导版本）。

三、问题分级定义

四、P0 致命问题（2 条）

P0-1 🔴 invite 邀请码生成功能 100% 报 500

证据链：

1. InviteController.php:20-22 —— public static function db(): \PDO { return \app\Helpers\Plugin::db('invite'); } → 返回原生 PDO；
2. InviteController.php:30 —— $db = self::db();；
3. InviteController.php:46 —— 在 else 分支（即积分足够、即将生成邀请码）中调用 $db->begin();；
4. 实测：

$ php -r '$p=new PDO("sqlite::memory:"); try { $p->begin(); } catch (\Throwable $e) { echo get_class($e).": ".$e->getMessage(); }'
Error: Call to undefined method PDO::begin()

影响：抛出的 Error 不是 Exception，InviteController.php:58 的 catch (\Exception $e) 捕不到 → 未捕获致命错误 → 用户每次点击「生成邀请码」都得到 500 页面（积分不足时因走 if 分支反而正常，掩盖了问题）。

修复建议：

// plugins/invite/InviteController.php:46
- $db->begin();
+ $db->beginTransaction();

// :58  catch 内同时补 inTransaction 守卫（见 P2 项 ROLLBACK_NO_GUARD）
  } catch (\Exception $e) {
-     $db->rollback();
+     if ($db->inTransaction()) { $db->rollBack(); }

同类排查结论：全仓 ->begin() 共 9 处，其中 app/Controllers/PostController.php:133、ThreadController.php:132、app/Helpers/Points.php:222、Permission.php:331、app/Models/Blog.php:124、User.php:609 以及 red_packet 的 3 处，接收者均为 app\Core\Database（该类确有此方法，Database.php:130 且带嵌套事务保护）→ 仅 invite 这一处是真实缺陷。

P0-2 🔴 user_level 后台按钮使用内联 onclick

影响：该行文本虽已用 $this->e() 转义（无 XSS），但内联事件属性违反零内联红线，且受 CSP script-src 策略限制时确认弹窗会失效。

修复建议（对齐 announcements / medal / content_review 的既有整改方式）：

// assets/script.js
document.querySelectorAll('[data-ul-confirm]').forEach(function (el) {
    el.addEventListener('click', function (e) {
        if (!confirm(el.dataset.ulConfirm)) e.preventDefault();
    });
});

五、P1 高危 / 规范问题（121 条）

5.1 核心库直写 —— 绕过 Points / User 封装（6 处）

违反 §11.8-1「禁止直写核心库用户/积分表」。绕过封装会同时丢失：积分日志（points_log）、等级重算、用户缓存失效、points_award_after / points_deduct_after 钩子。

修复建议：

// 积分增加
\app\Helpers\Points::award($userId, $points, $reason, $refId, $refType);
// 积分扣减（原子、防负）
\app\Helpers\Points::deduct($userId, $points, $reason, $refId, $refType); // 返回 bool
// 用户组变更
(new \app\Models\User())->updateGroupId($uid, $groupId);

quiz_duel:304 注释自述「避免 Points::award 的级别计算可能导致异常」——属已知取舍，但应按规范改为「Points::award 外层 try/catch 兜底」而非绕过封装；invite:54 用 Points::award($userId, -$pointsCost, ...) 传负数扣分，应改用 Points::deduct()。

5.2 主题硬编码颜色 —— 暗夜星辰主题下失读（105 处 / 15 个插件）

违反 §11.7。这是本次审计数量最多的一类问题：核心主题只定义 :root 变量，不为插件类补样式，硬编码色值在深色主题下表现为「白卡片 + 浅色字」不可读。

典型样本：

/* plugins/announcements/assets/style.css:34 */
.fl-modal { background:#fff; ... }
/* plugins/announcements/assets/style.css:38 */
.fl-modal-field label { ... color:#555; }
/* plugins/code_repo/assets/style.css:57-60 */
.repo-btn-ghost { background:#fff; color:#556; border:1px solid #d9dee8; }
/* plugins/code_repo/assets/style.css:65 */
.repo-btn-disabled { color:#999; }

修复模板（fallback 值 = 浅色主题下的目标色，保证浅色零副作用）：

.fl-modal        { background: var(--mn-bg-card, #fff); }
.fl-modal-field label { color: var(--mn-text-secondary, #555); }
.repo-btn-ghost  { background: var(--mn-bg-card, #fff); color: var(--mn-text-secondary, #556); border: 1px solid var(--mn-border, #d9dee8); }
.repo-btn-disabled { color: var(--mn-text-muted, #999); }

验证（§11.7 发布前必做）：

grep -nE 'background: *#fff|color: *#[0-9a-fA-F]{3,6}' plugins/{插件名}/assets/style.css   # 应零命中
# 实机切换「暗夜星辰」主题走查：卡片 / 文字 / 按钮 / 结果框 / 提示框

5.3 零内联违规（5 处）

draft_saver 修复模板（对齐 §7.3 P1-6「i18n 文案注入 JS」的 data 属性承载方案）：

// hook/layout_head_end.php
echo '
';
// assets/draft.js
const cfg = document.getElementById('flintDraftCfg');
window.FlintDraftUserId = cfg ? Number(cfg.dataset.userId) : 0;

5.4 语言键缺失（1 处）

修复：三个语言包同步补键（键序保持一致，UTF-8 无 BOM + LF）：

'plugin.code_audit.truncated' => '结果已截断，仅显示前若干条',  // zh.php
'plugin.code_audit.truncated' => 'Results truncated; only the first entries are shown.',  // en.php
'plugin.code_audit.truncated' => '結果已截斷，僅顯示前若干筆',  // zh_tw.php

复核说明：扫描器另报 6 个插件共 6 条 i18n 缺键，逐键溯源后确认全部为动态拼接前缀误报（plugin.mod_system.cat.{类型}、plugin.task_center.seed.、plugin.user_level.lv{N}、plugin.ai_assistant.reply_type_、plugin.points_mall.type_、plugin.third_party_login.fld_ 等），对应键族在字典中均齐备。

5.5 结构与元数据（4 处）

说明：

• ai_assistant/config.php.bak 删除即可（config.php 为现行版本）。
• edit_info 的两处属「表不存在则建表后重试」的惰性兜底，与 init_after 的定位相同，但按规范应把 DDL 上移到 activate()（或至少 init_after），业务钩子只做插入。
• post_favorite 的钩子文件内容已改为 return;（空转），删除 plugin.json 中的注册项即可；注意改 hooks 清单后必须重建 plugins/plugins_cache.json（§11.5-30）。

六、P2 改进项（119 条）

七、分插件总览

零问题插件：dice、floor_reply、single_page（3 个）。

八、通过项（合规确认）

以下维度经全量扫描 + 抽样复核，未发现任何违规：

8.1 安全（8 条最高级别红线）

8.2 结构、元数据与钩子

8.3 数据库与 i18n

九、修复优先级建议

第 1 批 —— 立即（P0，2 条）

1. plugins/invite/InviteController.php:46 → beginTransaction()；:59 catch 内补 inTransaction() 守卫。
2. plugins/user_level/views/admin.php:273 → 内联 onclick 改 data-ul-confirm + assets/script.js。

第 2 批 —— 本迭代（P1 核心库直写 6 条）

1. daily_checkin / quiz_duel / red_packet 的 5 处积分直写改 Points::award() / Points::deduct()；daily_checkin 同时补齐 points_log。
2. points_mall/Plugin.php:508 改 User::updateGroupId()。

⚠️ 这几处涉及积分与用户组，改动前务必按 §11.8-1 核对 Points 接口（award/deduct 均带条件原子更新与 rowCount() 检查），并在改动后回归「积分扣减无负数、等级联动、points_deduct_after 钩子触发」三项断言。

第 3 批 —— 本迭代（P1 其余 115 条）

1. 主题硬编码 105 处：按 §11.7 对照表批量替换为 var(--mn-*, fallback)，改完必须双主题（浅色 + 暗夜星辰）走查。
2. 零内联 5 处（draft_saver 1、forum_required_tag 3、third_party_login 1）。
3. code_audit 补 plugin.code_audit.truncated 三语键（注意键序一致、UTF-8 无 BOM + LF）。
4. 删 ai_assistant/config.php.bak；edit_info 两处 DDL 上移；post_favorite 移除死钩子注册并重建 plugins_cache.json。

第 4 批 —— 排期（P2 119 条）

1. 旧变量 55 处 → --mn-*；icon_generator 主色 17 处 → --mn-primary。
2. 直查 users 表 16 处 → User::batchGetNames()/batchGetUsers()。
3. 其余风格项（ensureSchema、占位符、inTransaction 守卫、命名空间、xiuxian::activate()）随相关文件改动时顺带修正。

发布前必做（§11.5 / §11.7）

# ① 改过 hooks 清单的插件 → 重建缓存
#    删除 plugins/plugins_cache.json 或调用 \app\Helpers\Plugin::refresh()
# ② 改过 nav_* / layout_head_end / footer_links → 清前台页面缓存
#    \app\Helpers\PageCache::invalidate()   （注：只覆盖列表页且仅游客）
# ③ 零内联复查（应零命中，

十、附录

10.1 审计产物

10.2 扫描器误报成因（供后续复用参考）

10.3 已知但未计入的问题（规范 §11 已登记，本次未重复发现）

• mod_system 的 users.status 不校验、写路径零事务；
• AuditLog 无痕、外部正文锁不一致；
• pagination() 出口不转义、搜索页 type 反射 XSS；
• fr_replies.thread_id 有 1 处既有不一致（id=28 post=1425 存 76，实际主题 81）—— 已记录未改。

以上均属核心层问题，不属于插件规范范畴，故未计入本报告问题总数。