本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/docs/队列调度模式改造执行计划 (2).md。

SoSite 1.0 — 异步任务队列调度模式后台开关 改造执行计划

文档状态：待确认（2026-08-13）

目标版本：SoSite 1.0（SplitDB 纯 SQLite 分片引擎）

背景：已有完整任务队列（Queue / QueueConsumer / cli/worker.php），但业务侧（发帖/回帖）无条件入队，不适应"虚拟主机无 SSH"环境。本计划新增可配置的「队列任务处理模式」开关，覆盖三种部署形态。

一、需求评估结论

1.1 现状盘点（已读代码确认）

1.2 关键设计确认

1. 存储：settings 表键 queue_mode，值 sync / cron / cli，默认 sync。

• 新装：Schema::seedDefaults() 补默认值（幂等）。
• 老库：Settings::get('queue_mode', 'sync') 兜底，无需迁移脚本。

1. 同步直写语义（模式 A）：

• 发帖：Search::indexThread($id)（实时索引）+ Settings::runtimeBuild()（实时统计）——与 worker handler 完全同构，数据 100% 实时。
• 回帖：Settings::runtimeBuild()（实时统计）。

1. 入队语义（模式 B/C）：保持现状 Queue::push，立即返回。
2. cron_trigger.php 安全设计：

• 仅当 queue_mode === 'cron' 时执行（防止 cli 模式下误触发双消费）；
• lock/ 目录文件锁防并发重复消费；
• 有界消费全部 3 个队列（复用 worker handler 逻辑，drain 后退出）。

二、改造执行计划表（严格串行，每步自测）

说明：cli/worker.php、Queue.php、QueueConsumer.php 无需改动（模式 B/C 复用现有消费链路）。

三、详细设计

3.1 业务接入（S1 / S2）

在 Thread::insert() 步骤 5、Post::insert() 步骤 6 处，读取模式并分支：

// Thread::insert 步骤 5（原为无条件入队）
$mode = \app\Helpers\Settings::get('queue_mode', 'sync');
if ($mode === 'sync') {
    // 模式 A：同步直写（实时索引 + 实时统计）
    \app\Helpers\Search::indexThread($id);
    \app\Helpers\Settings::runtimeBuild();
} else {
    // 模式 B/C：入队，立即返回
    Queue::push('rebuild_search', ['topic_id' => $id]);
}

// Post::insert 步骤 6（原为无条件入队）
$mode = \app\Helpers\Settings::get('queue_mode', 'sync');
if ($mode === 'sync') {
    // 模式 A：同步刷新全站统计
    \app\Helpers\Settings::runtimeBuild();
} else {
    \app\SplitDB\Queue::push('stats', ['type' => 'reply', 'thread_id' => $threadId, 'user_id' => ...]);
}

语义对齐：sync 直写执行的函数与 cli/worker.php 中同名 handler 完全一致，保证三种模式下最终数据一致。

3.2 配置存储（S3）

Schema::seedDefaults() 的默认 settings 数组追加：

'queue_mode' => 'sync',   // sync=同步直写 / cron=Cron 定时触发 / cli=CLI 常驻消费

（setValue 走 ON CONFLICT DO UPDATE，幂等；老库靠 get(..., 'sync') 兜底，无需迁移。）

3.3 后台 UI（S4）——布局预览

在 admin/settings_basic.php 新增「队列任务调度」区块（置于"功能开关"之后）：

┌─ 队列任务调度模式 ─────────────────────────────────────────┐
│  队列任务处理模式  [ 同步直写 (默认)        ▾ ]              │
│                                                           │
│  ● 同步直写：无需额外配置，数据实时，适合小型社区            │
│  ○ Cron 定时触发：适合虚拟主机（无 SSH）                    │
│  ○ CLI 常驻消费：适合 Linux VPS（Supervisor）               │
│                                                           │
│  [模式 B 选中时显示] 请在虚拟主机控制面板添加 Cron 任务：    │
│  ┌─────────────────────────────────────────────────────┐ │
│  │ wget -q -O /dev/null http://你的域名/cron_trigger.php │ │
│  └─────────────────────────────────────────────────────┘ │
│  [模式 C 选中时显示] 请确保服务器已安装 Supervisor 并       │
│  配置运行 cli/worker.php                                   │
└───────────────────────────────────────────────────────────┘

• 表单：<select name="queue_mode"> 三项（sync/cron/cli）；
• 联动提示：利用后台已加载的 Alpine（sostate.js），x-data="{qm:'...'}" + x-show 按选中项显示对应指引；
• 保存：SettingsController::basic 的 $keys 数组加入 'queue_mode'；保存后 Settings::buildCache() 已存在，自动生效。

3.4 cron_trigger.php（S5）设计

1) 加载框架（Autoloader）
2) 守卫：Settings::get('queue_mode') !== 'cron' → 输出提示并退出（防 cli 模式双消费）
3) 文件锁：lock/cron_trigger.lock（LOCK_EX|LOCK_NB），拿不到锁说明上次未结束，直接退出
4) 复用 worker 的 handler（rebuild_search / stats），对 3 个队列各 drain() 一次（有界）
5) 释放锁，输出处理统计，退出

安全说明：cron 模式是"公开可触发但只做队列消费"，无写权限放大风险；锁防并发重入；模式守卫防误配。

四、交付清单

五、验收流程（用户侧）

1. 后台 → 基本信息 → 选择「同步直写」保存 → 发帖 → 立即搜索可见、统计即时变化；
2. 改选「Cron 定时触发」保存 → 页面显示 wget 指引 → 发帖 → 搜索暂无新帖 → 浏览器访问 cron_trigger.php → 搜索命中、队列清空；
3. 改选「CLI 常驻消费」保存 → 显示 Supervisor 指引 → php cli/worker.php 消费验证；
4. 重复执行 cron_trigger.php 不产生重复消费（锁生效）。

六、备注

• 博客/分类等其余业务（BlogController 等）已是同步写入（Search::indexBlog 直调），不涉及队列，无需改动。
• cli/worker.php 的 --once 模式已可被 cron 直接调用，本计划新增 cron_trigger.php 仅为 Web 入口（虚拟主机无法执行 PHP CLI 时使用）。
• 全部改动文件 UTF-8 without BOM + LF，php -l 校验。