轻量级 PHP 社区系统（论坛 + 博客），基于自研 SplitDB 纯 SQLite 分片引擎。
版本：V1.0.0 ｜ 兼容 PHP 8.0.2（SQLite 3.33.0）｜
编码：UTF-8 without BOM + LF，用于快速了解本程序的全貌与优势。
一、项目概述
FlintHub（原名 SoSite）是一套轻量级 PHP 社区系统，提供论坛（帖子/回复/版块）、博客、用户中心、后台管理、插件系统等完整能力。它最核心的特点是：彻底剥离 MySQL，全部数据由纯 SQLite 分片引擎（SplitDB）承载，从"单库单表"升级为"分片 + 索引 + 缓存"的架构，在保留 PHP 极简部署优势的同时，解决了大数据量下的性能问题。
| 项 | 说明 |
|---|---|
| 项目定位 | 轻量级 PHP 社区系统（论坛 + 博客一体） |
| 当前版本 | FlintHub V1.0.0（由 SoSite 5.0 MySQL 版重构而来） |
| 运行环境 | PHP 8.0.2（SQLite 3.33.0），Nginx / Apache / phpstudy 均可 |
| 数据引擎 | SplitDB —— 纯 SQLite 分片引擎（无任何 MySQL 依赖） |
| 数据规模实测 | 5 万用户、19.2 万帖、16 万回复、235 万搜索索引行 |
| 目录约定 | 站点根目录为可运行骨架；update/ 为同步镜像 + 全部文档 |
演进脉络：SoSite 5.0（MySQL 单库）→ 重构为 SoSite 1.0（SplitDB 纯 SQLite 分片引擎）→ 品牌重命名 FlintHub。
二、核心架构：SplitDB 纯 SQLite 分片引擎
2.1 数据分层
data/
├── meta/ # 元数据层（SQLite 库）
│ ├── business.sqlite # 非分片业务：用户/版块/设置/博客/私信/附件/标签/投票
│ ├── main_index.sqlite # 帖子主索引 topic_index(19.2万行) + 回复定位索引 reply_index(16万行)
│ ├── search/ # 搜索索引季度分文件 search_{YYYYQn}.sqlite（4 文件，235 万行）
│ ├── global_id.sqlite # 全局 ID 生成器（topic/reply 原子取号游标）
│ ├── sessions.sqlite # 会话存储（SQLite handler）
│ └── task_queue/queue_{0..2}.sqlite # 异步任务队列（三队列打散锁竞争）
├── bucket/active/{季度}/{0..31}.sqlite # 帖子/回复真相源（季度时序 + ID2 哈希分桶）
├── bucket/archive/ # 18 个月以上冷数据归档桶
└── extern/{年}/{季}/{桶}/ # 正文外置：存量 .bin/.idx 偏移索引，新帖 .txt（读取自动回退）
2.2 分片与路由规则（ShardRouter）
- 一级分区：季度时序分区（
YYYYQn，如 2026Q3），新数据写入当前季度； - 二级分区：哈希分桶（默认 32 桶），写入路由 =
ID % 桶数量； - 读取永远以
main_index.bucket_path为准，不再二次哈希；未来季度可平滑升级 32 → 64 → 128 桶，历史数据零迁移。
2.3 写入与读取链路
写入 = global_id 原子取号 → 季度分区 + ID2 哈希 → extern 正文原子写(tmp+rename)
→ 桶 topic/reply 真相源 → main_index 索引行（最终一致性，队列可选）
读取 = 列表/分页走 main_index（索引行含 bucket_path）→ 详情读桶 + extern（.bin/.idx 优先，缺失回退 .txt）
搜索 = 自研 bigram 倒排索引（季度分文件，SearchIndexStore）
2.4 引擎关键组件（app/SplitDB/）
| 组件 | 职责 | 亮点 |
|---|---|---|
DBFactory |
SQLite 连接池 | 单进程 LRU 最大 8 句柄，统一 6 条 PRAGMA（WAL/busy_timeout），禁持久连接 |
IDGenerator |
全局 ID 生成 | BEGIN IMMEDIATE 写锁事务原子取号（兼容无 RETURNING 的 SQLite 3.33） |
ShardRouter |
分片路由 | 季度 + 哈希双级分区，路径推导唯一依据 |
ExternStorage |
正文外置存储 | tmp+rename 原子写；存量 .bin/.idx 偏移索引（fseek 定位，懒加载）；编辑后作废 .idx 条目回退 .txt（修复虚拟主机编辑不生效） |
Queue / QueueConsumer |
异步任务队列 | 三队列打散锁竞争；CAS 抢占/超时恢复/重试上限；sync/cron/cli 三模式 |
Schema |
初始化与种子 | 幂等 bootstrap（目录树 + 8 库 + 22 表 + 默认种子） |
ViewCounter |
浏览计数 | APCu 内存计数 + shutdown 批量落库；无 APCu 静默降级为直写 UPDATE（不崩站） |
SearchIndexStore |
搜索索引 | 季度分文件存储，与 business 库物理隔离（P21 瘦身 306MB → 19MB） |
2.5 事务与一致性
- 桶写入用原始 SQL
exec('BEGIN')/exec('COMMIT')；business 库用beginTransaction()/commit()，二者不混用； - 正文外置红线：先原子写 extern → 再写索引行，绝不允许"索引导入成功但正文丢失"（迁移故障注入已验证）；
- 计数延迟合并：统计/浏览数先走内存/APCu 计数，请求结束时批量写回，把写放大钉死在量化边界。