本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/待办事宜/FlintHub_MySQL版本改造方案.md。

FlintHub MySQL 版本改造方案

编制日期：2026-10-11

编制依据：站点根 D:\phpstudy_pro\WWW 全量代码通读（核心 app/、cli/、plugins/、install.php、config.php）

结论定位：这是一次数据访问层的整体替换，不是"改几处 SQL"。可做，但必须按阶段推进，且第一刀要落在"抽象层"上。

0. 结论先行（TL;DR）

1. 现状摸底（全部有据）

1.1 当前数据层架构全景

FlintHub 当前是自研的 SplitDB 纯 SQLite 分片引擎，不是单库。共 7 类物理库 + 1 类外置存储：

1.2 建表位置（改造清单的来源）

全部 DDL 集中在 1 个文件：app/SplitDB/Schema.php（1049 行）

• ensureBusiness() Schema.php:294-634 — 23 张业务表 + 全部索引
• ensureMainIndex() Schema.php:806-878 — topic_index / reply_index
• ensureSessions() Schema.php:883-894 — sessions
• ensureBucketTables() Schema.php:929-996 — 桶内 topic / reply
• ensureGlobalId() Schema.php:1045-1048 — id_generator
• Queue::initTable() Queue.php:41-68 — task_queue
• SearchIndexStore::createTable() SearchIndexStore.php:74-86 — search_index

幂等补列机制：Schema::ensureColumnPatches() Schema.php:641-765（哈希 marker 门控）——MySQL 下需要整套重设计。

1.3 SQL 调用规模（改造面统计）

⚠️ 但真正需要改的远少于此：约 95% 是标准参数化 SELECT/INSERT/UPDATE/DELETE，MySQL 直接兼容。

真正要动的是下面 §3.2 的方言清单（约 60 处）+ 双引号标识符（约 40 处）。

1.4 关键证据：本项目原本就是 MySQL

cli/migrate.php:1-22    「旧 MySQL 数据迁移脚本（CLI）」——一次性历史工具
cli/migrate.php:28-34   $MIGRATE = ['host'=>'localhost','name'=>'fastbb','user'=>'fastbb',...]
cli/migrate.php:89-128  class MySqlMigrateSource —— PDO mysql 非缓冲查询
flinthub1.0.23/cli/migrate.php  同样存在（538 行）
app/init.php:28-37      「★ 原 MySQL 探测逻辑（恢复时参考）：$db->fetchOne("SHOW TABLES LIKE 'sessions'")」
install.php:146         「不再支持"旧 MySQL 配置升级为 SplitDB"」

⇒ cli/migrate.php 的 MigrateSourceInterface 抽象（migrate.php:72-84）就是为"源/目标可互换"设计的，反向迁移器可以直接复用它的骨架。

2. 路线选择

路线 A：直接替换 SQLite → MySQL（单引擎）

把 app/SplitDB/* 整体改写为 MySQL 实现，SQLite 代码删除。

• ✅ 代码最干净，无分支
• ❌ 不可回退——一旦上线，想回 SQLite 就得重写第二遍
• ❌ 与现有发布体系冲突（发布包、升级器、老站都要跟着改）
• ❌ 违反项目一贯的"最小变更 + 零依赖回滚"原则

路线 B：抽象层 + 双引擎适配器 ✅ 推荐

引入 app/Db/ 驱动抽象，Database 门面按 DB_DRIVER 常量分派到 SqliteDriver / MysqlDriver。

• ✅ SQLite 现有站点零影响（默认仍走 SQLite）
• ✅ MySQL 作为可选引擎，老站可平滑切换
• ✅ 回滚 = 改一个常量
• ✅ 与现有发布体系兼容（核心包里同时带两套驱动）
• ❌ 需要先做抽象层（额外 1~2 天）
• ❌ 双引擎 = 双份测试矩阵

路线 C：恢复历史 MySQL 版

从 flinthub1.0.23/ 或更早版本恢复 MySQL 实现。

• ❌ 不可行：1.0.x 已经历 28 个增量版本（update/ 目录），业务逻辑、表结构、插件体系都大幅演进，旧 MySQL 版远落后于当前功能，回退等于丢掉半年工作
• ⚠️ 仅可作为方言参照（旧版怎么写 SQL 的），不能作为基线

⇒ 采用路线 B。 下面所有方案基于路线 B 展开。

3. 核心改造：数据访问层

3.1 新增目录结构

app/Db/                          ← 新增
├── DriverInterface.php          连接 + 执行 + 元数据 抽象
├── SqliteDriver.php             现有逻辑搬入（DBFactory 的 PRAGMA 等）
├── MysqlDriver.php              新增
├── Grammar.php                  方言（DDL / 标识符引用 / upsert / 分页）
├── SqliteGrammar.php
├── MysqlGrammar.php
└── Migrator.php                 Schema 建表（DDL 按 Grammar 生成）

改造原则：app/SplitDB/ 目录保留不删（它是 SQLite 专属实现），但 app/Core/Database.php 门面改为按驱动分派。

3.2 SQLite 专有语法清单（逐条 + 位置 + 改法）

这是必须逐条改的清单。已全部定位到 文件:行号。

① 幂等插入 INSERT OR IGNORE → INSERT IGNORE

② 覆盖插入 INSERT OR REPLACE → REPLACE INTO

⚠️ 语义陷阱：REPLACE INTO 在 MySQL 里是 DELETE + INSERT，会触发级联删除、重置自增、丢失未列出的列。推荐改用 INSERT ... ON DUPLICATE KEY UPDATE，语义更接近 INSERT OR REPLACE 但更安全。

③ 条件更新 UPDATE OR IGNORE → UPDATE IGNORE

④ UPSERT ON CONFLICT(x) DO UPDATE → ON DUPLICATE KEY UPDATE

⚠️ excluded.value → VALUES(value)：MySQL 8.0.20+ 已弃用 VALUES() 函数，推荐表别名写法 INSERT ... AS new ON DUPLICATE KEY UPDATE value = new.value。为兼容 5.7/8.0 双版本，建议统一用 VALUES() 并接受弃用告警，或按版本分支。

⑤ 日期函数

⑥ 类型转换 CAST(x AS TEXT) → CAST(x AS CHAR)

• Settings.php:423

⑦ 元数据查询

⑧ 连接/事务/只读

⑨ 备份/维护

⑩ DDL 语法差异

3.3 ⚠️⚠️ 双引号标识符（最容易漏、后果最严重）

SQLite："key" 是标识符引用（等同于反引号）

MySQL：默认 sql_mode 不含 ANSI_QUOTES 时，"key" 是字符串字面量！

⇒ SELECT * FROM settings WHERE "key" = :k 在 MySQL 里会变成「常量字符串 'key' 等于 :k」，不报错、返回错误结果。

受影响位置（需全部改为反引号）：

改造建议：在 Grammar 里提供 quoteIdent($name)，Model / Settings 等统一走它，禁止手写引号。

附带风险：settings 表的列名 key 是 MySQL 保留字，任何地方漏引号都会语法错误 → 建议顺手把列名改为 skey（但会牵连迁移与所有引用，收益不高，建议只做引号统一）。

3.4 其他 MySQL 严格模式陷阱（需全量扫描）

4. 架构降维设计（SplitDB → MySQL）

这是整个方案最需要拍板的部分。SQLite 时代的"分库分表"在 MySQL 下要重新设计。

4.1 映射总表

4.2 bucket_path 字段的处置

现状：topic_index.bucket_path 是读取路由的唯一依据（Schema::bucketFromPath() Schema.php:1014）。

MySQL 下：

• 字段保留但废弃（bucket_path 恒为 ''），避免大改 Thread/Post 的读取链路
• 或彻底删除并清理所有引用点（Thread.php 65 处 SQL 调用里有多处）
• ⚠️ 建议阶段一保留、阶段二清理，降低单次改动面

4.3 归档机制

现状：cli/archive.php 把 18 个月以上冷数据从 bucket/active/ 移到 bucket/archive/（物理文件移动）。

MySQL 下两个选项：

• A：topic 表加 is_archived 标记（topic_index 已有此列，Schema.php:826），归档 = 批量 UPDATE，推荐
• B：MySQL 8.0 原生分区表（PARTITION BY RANGE on create_time）——更优雅但引入运维复杂度

4.4 计数器与并发

5. 后台改造方案（重点）

后台数据库模块是受影响最集中的地方。现状：1 个控制器 1113 行 + 3 个视图，几乎全部围绕 SQLite 设计。

5.1 后台路由现状

index.php:285-291：

$r->get('/database',           [AdminDatabaseController::class, 'index']);
$r->post('/database',          [AdminDatabaseController::class, 'index']);
$r->get('/database/engine',    [AdminDatabaseController::class, 'engine']);
$r->post('/database/engine',   [AdminDatabaseController::class, 'engine']);
$r->get('/database/overview',  [AdminDatabaseController::class, 'overview']);
$r->get('/database/settings',  [AdminDatabaseController::class, 'settings']);
$r->post('/database/settings', [AdminDatabaseController::class, 'settings']);

建议：路由全部保留（保老书签不失效），但页面内容按引擎分派。

5.2 页面一：数据库管理页 /admin/database

现状（DatabaseController::index() :23-145 + 视图 admin/database.php）

5.2.1 ⚠️⚠️ 备份方案的硬约束

核心矛盾：mysqldump 是命令行工具，需要 shell 执行；而项目红线明确「站长不用 SSH，升级器必须纯 Web」（见 REF_环境与数据 §A）。同时宝塔 disable_functions 常见禁 exec/shell_exec。

可选方案对比：

推荐组合：A（服务器端留存）+ 流式下载。备份文件名约定保持 forum_backup_{ts}.sql，与现有 forum_backup_*.zip 的轮转逻辑（rotateBackups() :742-760）复用。

5.2.2 导入/恢复的服务端确认

现状已有服务端 CONFIRM 硬校验（CONFIRM_TOKEN :703、:888、:938），这套机制原样保留，只把"文件类型"从 .zip/.sqlite 改为 .sql。

5.3 页面二：SplitDB 引擎概览 /admin/database/overview

现状（DatabaseController::overview() :177-195 + 视图 admin/database/overview.php）

展示：分片分布（32 桶 × topic/reply 行数）、总帖子数、建议桶数、当前季度。

MySQL 下这些概念全部消失。三个选项：

5.4 页面三：引擎设置 /admin/database/settings

现状（DatabaseController::settings() :201-290 + 视图 admin/database/settings.php 23KB）

连带影响：app/SplitDB/BucketAutoScaler.php（224 行）在 MySQL 下整体废弃。但它里面的 config.php 安全写入逻辑（备份 → 正则替换 → 原子写 → opcache 失效，:54-157）非常有价值，建议抽成 app/Core/ConfigWriter.php 复用到「MySQL 连接配置」场景。

5.5 新增页面：MySQL 连接配置

为什么必须新增：现在 config.php 里没有任何 DB 配置项（全是 SPLITDB_*），MySQL 需要 host/port/name/user/pass/charset。

设计：

后台 → 系统 → 数据库配置（新增路由 /admin/database/connection）
├── 表单：主机 / 端口 / 库名 / 用户名 / 密码 / 字符集 / 表前缀
├── 按钮：测试连接（实时探测，返回版本 + 权限）
├── 按钮：保存（写入配置）
└── 展示：当前驱动、连接状态、服务器版本

⚠️ 密码存储：不能明文写 config.php（config.php 进包/可被下载）。参照现有 MAIL_PASS_KEY / CRON_KEY 的治理模式（config.php:44-62、:132-150）：

• 写入 protected/db.php（内容 <?php return ['pass' => '...'];，不进发行包）
• 或环境变量 FLINTHUB_DB_PASS

⚠️ 同时必须：按项目红线，config.php 由 install.php::configTemplate() 生成、不进包 → 老用户永远拿不到新配置项 → 必须在 index.php（进包）做兼容前移（同 SITE_URL 那套处理，config.php:105-123）。

5.6 新增功能：SQLite → MySQL 迁移工具（Web 化）

这是"让存量站切过来"的关键。现状只有 CLI 版（cli/migrate.php），但站长不用 SSH。

设计（直接参照 extern 合并的续批模式，DatabaseController::index() :41-60 + 视图 :104-118）：

后台 → 数据库 → 迁移到 MySQL
├── 步骤 1：填写 MySQL 连接 → 测试连接
├── 步骤 2：预检（dry-run）→ 展示各表行数、预计耗时、磁盘占用
├── 步骤 3：建表（执行 MySQL DDL）
├── 步骤 4：迁数据（分表分批，进度条 + meta refresh 自动续批 + 断点续跑）
│          每批：读 SQLite 一页 → 写 MySQL → 记录断点
├── 步骤 5：校验（逐表行数对拍 + 抽样字段比对）
└── 步骤 6：切换（写 config.php 的 DB_DRIVER=mysql + 连接信息）

红线（沿用 cli/migrate.php 的既有设计，:397-409）：

• 绝不删源库（SQLite 保持原样，可随时回滚）
• 迁移中断可重跑（INSERT ... ON DUPLICATE KEY UPDATE 幂等）
• 迁移期间建议置维护模式（settings.site_closed，init.php:126）

5.7 安装向导 install.php

现状（752 行）：5 步向导（欢迎 → 许可 → 环境检测 → 管理员 → 完成），全程无数据库配置。

改造点：

5.8 其他后台受影响点

6. 存量数据迁移方案

6.1 迁移器设计（反向复用 cli/migrate.php）

cli/migrate.php 已经定义了干净的抽象（:72-84）：

interface MigrateSourceInterface {
    public function tableNames(): array;
    public function rows(string $table): iterable;   // 逐行 yield，大表防 OOM
    public function count(string $table): int;
    public function close(): void;
}

反向实现：

• SqliteSplitDbSource implements MigrateSourceInterface —— 源改为「SplitDB 7 类库 + extern 文件」
• rows('threads') → 遍历全部桶文件的 topic 表 + 读 extern 正文
• rows('posts') → 遍历全部桶文件的 reply 表 + 读 extern 正文
• MysqlTarget —— 目标改为 PDO mysql

6.2 迁移顺序（依赖序）

1. 建表（MySQL DDL，全部表 + 索引）
2. business 23 表（users/categories/... → 逐表，保留 ID）
3. topic_index + reply_index（main_index）
4. topic + reply（遍历全部桶，季度 × 32 桶；正文从 extern 读入 LONGTEXT）
5. task_queue（3 队列合并为 1 表）
6. search_index（全部季度文件合并为 1 表）
7. sessions（可选，建议不迁——迁了会踢全站下线）
8. id_generator（游标推进到 max(id)）
9. 全部 AUTO_INCREMENT 对齐（ALTER TABLE ... AUTO_INCREMENT = max+1）

6.3 校验（必须做，不能省）

6.4 回滚方案

这是路线 B 的最大优势：

1. SQLite 数据原样保留（迁移器只读源库）
2. 回滚 = 后台把 DB_DRIVER 改回 sqlite（或手工改 config.php）
3. 迁移期间的写入（若没置维护模式）需要二次同步 → 强烈建议迁移时置维护模式

7. 插件兼容性

7.1 现状

• 48 个插件，约 1200 处 SQL 调用点
• 每个插件自带独立 SQLite 库（plugins/<name>/data/*.sqlite）
• 插件通过 Plugin::db() 获取连接（经 DBFactory）

7.2 兼容策略

⇒ 推荐 A：Plugin::db() 继续返回 SQLite 连接，与核心驱动解耦。

7.3 必须排查的插件

即使用了策略 A，以下插件仍需检查（它们跨库引用核心表）：

⚠️ 注意：以上计数是全部 SQL 调用，不等于"需要改的"。真正要改的仍以 §3.2 的方言清单为准。

7.4 插件开发规范要同步更新

docs/插件开发规范.md 需要新增一节「双引擎兼容」：插件写 SQL 时禁用 INSERT OR IGNORE / ON CONFLICT / strftime 等 SQLite 专有语法，改用 Grammar 提供的兼容方法。

8. 分阶段实施计划

阶段 P0：抽象层（前置，无功能变化）

这一阶段不碰 MySQL，纯粹为后续铺路。完成后可以单独发一版，验证抽象层无副作用。

阶段 P1：MySQL 驱动 + 建表

阶段 P2：核心 SQL 方言适配

阶段 P3：后台模块重写

阶段 P4：存量迁移 + 校验

阶段 P5：插件兼容 + 文档

9. 风险清单与红线

10. 工作量估算

11. 改造工作区 D:\phpstudy_pro\WW2（全量独立副本）

2026-10-11 已建：WW2 不是「只放待改文件的补丁区」，而是 MySQL 版的完整独立副本——

全量复制 WWW 的全部代码 + 全部样式 + 全部插件 + 全部数据，可独立启动运行（已实测通过）。

从建立之日起，MySQL 版与 SplitDB（spd）版彻底分离，各自独立演进；源站 WWW 一个字节未动。

工作区说明 → D:\phpstudy_pro\WW2\_WW2工作区说明.md；逐文件改动索引 → D:\phpstudy_pro\WW2\_改造清单.md。

11.1 复制口径（实测数据）

11.2 明确排除项（均非本站运行代码）

⚠️ data/ 与 assets/uploads/ 已整体复制，所以副本现在就能独立跑起来。

等进入 MySQL 阶段后，data/meta/*.sqlite、data/bucket/、data/extern/ 才会被 MySQL 取代 —— 届时再清。

⚠️ WW2 从此不再随 WWW 的升级包覆盖（两版已分离）；需要同步某次修复时，手工挑文件搬。

11.3 需要改动的文件（索引 —— 不是工作区全貌）

收录口径：「含 SQLite 专有语法」∪「结构 / 文案必须改」的并集。

全仓 SQL 调用点约 1800 处，真正要改的约 100 处。逐文件明细见 WW2/_改造清单.md。

11.4 可整份下线的「废弃 4 件套」

若采纳「正文入 LONGTEXT」，以下 4 个文件（合计 1736 行）可整体删除：

同理可下线 BucketAutoScaler.php（224 行，桶扩容）与 ShardRouter.php 的分片路由逻辑。

11.5 需新建的文件（WW2 内原本不存在，属新增）

app/Db/DriverInterface.php      驱动契约
app/Db/SqliteDriver.php         现有逻辑搬入
app/Db/MysqlDriver.php          新增
app/Db/Grammar.php              + SqliteGrammar / MysqlGrammar（方言收口）
app/Db/Migrator.php             建表（DDL 按 Grammar 生成）
app/Core/ConfigWriter.php       从 BucketAutoScaler 抽出的 config.php 安全写入

11.6 对照方法

# 单文件对照
diff -u /d/phpstudy_pro/WWW/app/SplitDB/Schema.php \
        /d/phpstudy_pro/WW2/app/SplitDB/Schema.php

# 批量看改动概况（两棵目录现在完全同构，可直接 -r 比对）
diff -rq /d/phpstudy_pro/WWW/app /d/phpstudy_pro/WW2/app

# ⚠️ 全仓 -r 比对必须排除无关树，否则会扫到 flinthub-client（19 110 文件）
diff -rq -x 'flinthub-client' -x 'release' -x 'update' -x 'flinthub1.0.23' -x '*.zip' \
     /d/phpstudy_pro/WWW /d/phpstudy_pro/WW2

12. 待你拍板的 5 个决策点

1. 路线：是否采纳路线 B（双引擎）？还是直接单引擎替换？
2. 正文存储：extern 正文是入 MySQL LONGTEXT（推荐，可下线 1400 行 extern 代码）还是保留文件外置？
3. 全局 ID：保留 id_generator 表（改动小）还是改 AUTO_INCREMENT（更原生）？
4. 插件库：是否采纳策略 A（插件库保持 SQLite）？
5. 迁移范围：是否需要存量数据迁移（决定是否要做 P4 阶段，影响 2~3 天工期）？

本文档为方案设计，未改动任何代码。 确认路线后，建议从 P0 抽象层起步——那一阶段不引入 MySQL、不改变现有行为，是风险最低的切入点。