SplitDB — 基于SQLite的分片数据库介绍

SplitDB v2.3 是 FlintHub（原 SoSite）底层数据引擎的架构定稿方案：基于原生 SQLite 构建的多分片存储系统。 核心思路：用时序分区 + 哈希分桶解决 SQLite 单文件锁竞争；分片作为唯一数据源，索引 / 搜索 / 统计为异步二级视图。 无需 MySQL、Redis、消息队列 —— 一个 PHP 进程 + 若干 SQLite 文件即可承载一个社区。 本文档依据《Splitdb V2.3 白皮书.txt》整理，并结合 SplitDB 在 FlintHub 中的实际落地情况与实测数据，最后给出与 MySQL 在小数据量 / 大数据量下的对比。

一、SplitDB 是什么

1.1 定位

SplitDB 面向中小型私有化社区、独立站长设计，精准适配低资源服务器（1 核 512M ~ 1 核 1G）：

• DAU 0~8000：稳定舒适运行；
• DAU 8000~15000：限流可控稳定运行；
• 不适用：超高并发刷屏、电商秒杀、复杂多表 JOIN 统计、大型门户（白皮书明示边界，预留了后期平滑切换 MySQL 驱动的适配器）。

1.2 三大核心设计理念（白皮书原文原则）

一句话概括：分片管写入（真相源），索引管读取（二级视图），队列管异步（最终一致），缓存管性能（读降级为拼缓存）。

1.3 与 MySQL 的本质差异（先给结论）

二、架构总览

2.1 数据目录（白皮书定稿）

data/
├── meta/                          # 元数据层
│   ├── main_index.sqlite          # 帖子主索引（列表、分页、路由）
│   ├── search_index.sqlite        # 全文检索库（落地改为季度分文件，见 3.2）
│   ├── stats_cache.sqlite         # 预计算全站统计（落地并入 business.sqlite 的 _runtime_*）
│   ├── task_queue/queue_{0..2}.sqlite   # 多队列（3 个打散锁竞争）
│   └── global_id.sqlite           # 全局 ID 生成器（写单点，高并发可扩展 ID 预分配）
├── bucket/
│   ├── active/{2026Q3}/{0..31}.sqlite   # 真相源分片：季度 × 32 桶
│   └── archive/                   # 18 个月前冷数据归档
├── extern/{年}/{季}/{桶}/{id}.txt # 正文外置（落地：存量合并 .bin/.idx 偏移索引）
├── runtime/  lock/  log/

2.2 分区与路由规则（ShardRouter）

• 一级分区：季度时序分区（YYYYQn）：新数据永远写当前季度，超 18 个月归档至 archive/；
• 二级分区：哈希分桶（默认 32 桶）：写入路由 = ID % 桶数量；
• 重大优化：读取永远以 main_index.bucket_path 为准，不再二次哈希 —— 未来季度可直接升级 32 → 64 → 128 桶，历史数据零迁移、零失效。

2.3 统一强制 PRAGMA（每个连接固定 6 条）

PRAGMA busy_timeout = 5000;        -- 写锁等待上限，防 SQLITE_BUSY 崩溃
PRAGMA journal_mode = WAL;         -- 读不阻塞写、写不阻塞读
PRAGMA synchronous = NORMAL;       -- WAL 下性能与安全的平衡
PRAGMA cache_size = -20000;        -- 20MB 页缓存
PRAGMA temp_store = MEMORY;        -- 临时表走内存
PRAGMA foreign_keys = OFF;         -- 分片架构不依赖跨文件外键

2.4 写入 / 读取流程

写入 = global_id 原子取号 → 季度 + ID2 哈希 → LRU 取桶连接 → 写 Bucket + extern 正文
     → 随机入 3 队列之一（打散锁竞争）→ 立即返回 topic_id + bucket_path
读取 = 列表/首页/分页走 main_index → 详情按 bucket_path 读单桶 → 搜索走 search_index

2.5 PHP-FPM 适配三件套

1. 单进程 LRU 轻量连接池：最多 8 个常驻句柄，请求结束自动清空（DBFactory，落地 MAX_HANDLES=8）；
2. 禁止持久连接：禁用 ATTR_PERSISTENT（防句柄泄漏与状态残留）；
3. 系统层兜底：ulimit -n 65535 / php-fpm rlimit_files = 65535。

三、SplitDB 在 FlintHub 的落地情况

白皮书是设计蓝图，FlintHub 1.0 是它的完整实现。落地过程中针对 PHP 8.0.2（SQLite 3.33.0，无 RETURNING 支持）与真实业务做了关键适配：

3.1 落地组件清单（app/SplitDB/）

3.2 与白皮书的关键差异（落地决策）

3.3 落地后的真实性能（19.2 万帖 / 5 万用户实测）

★ 最有说服力的一条：300 帖小数据集与 19.2 万帖真实库的 warm 渲染耗时相同（均 7-20ms）——SplitDB 的"读无限扩容"理念在真实数据下得到验证，性能不随数据量退化。

四、与 MySQL 的对比

对比基线：SoSite 5.0（MySQL 版）历史表现 vs FlintHub 1.0（SplitDB 版）落地实测；MySQL 数据来自项目历史与交接文档记录，SplitDB 数据来自真实环境实测。

4.1 小数据量（百帖 ~ 数千帖时代）

4.2 大数据量（19.2 万帖 / 5 万用户 / 235 万搜索行）

4.3 综合对比表

4.4 选型结论（白皮书边界 + 落地验证）

• 选 SplitDB 当：中小型私有化社区、独立站长、低配服务器（1 核 512M）、DAU ≤ 8000 舒适 / ≤ 15000 限流可控、想要"零运维 + 纯 SQLite"的极简部署；
• 选 MySQL 当：超高并发刷屏、电商秒杀、复杂多表 JOIN 统计分析、大型门户（超 SplitDB 边界）。
• 白皮书为极端场景预留了适配器模式（后期可平滑切换 MySQL 驱动），FlintHub 的 Model 层 API 已按此设计，切换成本可控。

五、开发红线与注意事项（沉淀）

5.1 白皮书开发红线（落地仍强制遵守）

1. 禁止前台实时跨桶统计 → 统计全走 _runtime_* / getCategoryStats() 缓存；
2. 禁止网页同步更新索引 → 搜索/统计索引走队列异步（sync 模式除外，用户确认的取舍）；
3. 禁止全局 LIKE 遍历桶文件 → 枚举库文件用显式 glob；
4. 禁止长事务、长快照 → 桶写原始 SQL BEGIN/COMMIT，business 用 beginTransaction/commit，不混用；
5. 禁止高峰期 truncate WAL → WAL 回收脚本定时（凌晨）执行；
6. 禁止 PDO 持久连接 → DBFactory 禁 ATTR_PERSISTENT；
7. 禁止依赖分片自增 ID → 一律 global_id 取号；
8. 禁止 HTTP 线程实时更新浏览量 → APCu 计数 + shutdown 批量 flush（无 APCu 降级直写）。

5.2 白皮书风险提示的落地处置

5.3 运维命令速查

# 语法检查
php -l app/SplitDB/DBFactory.php

# 重建搜索索引（二级视图可从分片全量重建）
php cli/rebuild_search.php

# 队列消费（--once 供 cron）
php cli/worker.php 0 --once

# 性能探针（纯 PHP 读缓存计时）
php cli/probe_page_cache.php --quiet

# WAL 回收（对应白皮书 splitdb_wal_reclaim.sh，凌晨执行）
# 数据库信息/备份/索引管理：后台 → 数据库维护

本文档完。SplitDB —— 分片之光：用纯 SQLite 分片引擎，把 PHP 社区系统做到零运维、低资源、与数据量无关的性能。