本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/说明.md。

FlintHub 程序介绍

轻量级 PHP 社区系统（论坛 + 博客 + 私信 + 插件生态）

版本：V1.0.0 ｜ 架构：自研 MVC + SplitDB 纯 SQLite 分片引擎（彻底剥离 MySQL）

语言：PHP 8.0.2（内置 SQLite 3.33.0）｜ 编码：UTF-8 without BOM + LF

运行环境：phpstudy（Nginx/Apache 均可）｜ 零 Composer 依赖、零数据库服务进程，开箱即用

一、目录结构图（V1.0.0 最新）

D:/phpstudy_pro/WWW                        # 站点根目录（安装包 FlintHub1.0.0/ 为同构骨架）
├── index.php                              # 前端控制器（路由分发入口 + 游客前置静态缓存 + ViewCounter flush）
├── install.php                            # 安装向导（环境检测/建管理员/自动生成 config.php，.install_done 防重装）
├── cron_trigger.php                       # 队列 Web 触发入口（cron 模式守卫 + 文件锁 + 有界消费）
├── config.php                             # 全局配置（SplitDB 数据路径/上传/邮件/Session）——由 install.php 生成
├── nginx-server.conf                      # ★ Nginx 站点配置（含 data/、protected/ 目录 deny 拦截）
├── favicon.ico / favicon.svg / logo.svg / flinthub-badge.svg
│
├── app/                                   # ★ 应用核心（自研框架）
│   ├── init.php                           # 应用初始化（自动加载/配置/SQLite Session/插件/维护模式）
│   ├── Core/                              # ── 自研 MVC 框架内核（6 个文件）──
│   │   ├── Autoloader.php                 #   PSR-4 风格自动加载
│   │   ├── Router.php                     #   路由引擎（GET/POST/ANY/分组/参数正则提取）
│   │   ├── Controller.php                 #   控制器基类（视图/JSON/重定向/防开放重定向）
│   │   ├── Model.php                      #   模型基类（CRUD/排序白名单/动态 Where 字符校验）
│   │   ├── Database.php                   #   SplitDB 门面（business 业务库 + sessions 独立会话库）
│   │   └── TemplateCompiler.php           #   模板引擎（编译缓存/安全转义 e()/分页 pagination()/区块）
│   ├── SplitDB/                           # ★ 分片引擎核心（9 个类，白皮书 v2.3 落地）
│   │   ├── DBFactory.php                  #   连接池（LRU ≤8 句柄、禁持久连接、统一 6 条 PRAGMA）
│   │   ├── IDGenerator.php                #   全局 ID 生成（BEGIN IMMEDIATE 原子取号，兼容无 RETURNING）
│   │   ├── ShardRouter.php                #   分片路由（季度时序 + ID%32 哈希；读取以 bucket_path 为准）
│   │   ├── ExternStorage.php              #   正文外置（tmp+rename 原子写；.bin/.idx 偏移索引 + .txt 回退）
│   │   ├── Queue.php / QueueConsumer.php  #   异步任务队列（3 队列打散锁竞争；CAS 抢占/超时恢复/重试上限）
│   │   ├── Schema.php                     #   初始化与种子（幂等 bootstrap：目录树+库+表+默认数据+.htaccess 防护）
│   │   ├── SearchIndexStore.php           #   搜索索引季度分文件存储（P21 剥离 business 库）
│   │   └── ViewCounter.php                #   浏览计数（APCu 内存计数 + shutdown 批量落库；无 APCu 降级直写）
│   ├── Controllers/                       # ── 前台控制器（13 个）──
│   │   ├── HomeController.php             #   首页聚合（版块快照/博客/在线/标签，游客整页缓存）
│   │   ├── ForumController.php            #   论坛版块（keyset 深翻页/权限过滤/置顶高亮/缓存钳制）
│   │   ├── ThreadController.php           #   帖子（浏览/回复/编辑/删除/附件/置顶高亮）
│   │   ├── PostController.php             #   回复/新帖（CSRF + 限流 + 权限二次校验）
│   │   ├── AuthController.php             #   登录/注册/找回密码/邮箱验证
│   │   ├── ProfileController.php          #   个人中心（资料/头像/改密）
│   │   ├── MessageController.php          #   站内私信（收/发/详情/删除）
│   │   ├── BlogController.php             #   博客（列表/详情/分类/评论）
│   │   ├── SearchController.php           #   全文搜索（倒排索引 + 时间范围 + 登录限流）
│   │   ├── TagsController.php             #   标签（列表/聚合页）
│   │   ├── ThemeController.php            #   主题/配色切换
│   │   ├── ApiController.php              #   API（投票/上传/远程拉图 SSRF 防护/验证码）
│   │   └── AttachmentController.php       #   附件下载（权限随版块）
│   │   └── Admin/                         #   ── 后台控制器（16 个）──
│   │       ├── BaseController.php         #     后台基类（isAdmin + 30 分钟二次验证 + 批量移动公共方法）
│   │       ├── DashboardController.php    #     控制台
│   │       ├── UserController.php         #     用户管理（关键词/字段/角色/状态查询）
│   │       ├── ThreadController.php       #     帖子管理（分类筛选 + 批量删除/移动联动）
│   │       ├── CategoryController.php     #     版块管理
│   │       ├── BlogController.php         #     博客管理
│   │       ├── TagController.php          #     标签管理
│   │       ├── LevelController.php        #     等级管理
│   │       ├── GroupController.php        #     用户组/权限矩阵管理
│   │       ├── ThemeController.php        #     主题管理
│   │       ├── SettingsController.php     #     站点/显示/邮件/搜索/任务调度设置
│   │       ├── DatabaseController.php     #     数据库备份/VACUUM/索引管理
│   │       ├── MaintenanceController.php  #     维护工具（缓存/计数器重建/清理）
│   │       ├── TrashedController.php      #     回收站
│   │       ├── PluginController.php       #     插件管理
│   │       └── VerifyController.php       #     二次验证页
│   ├── Helpers/                           # ── 自研工具库（20 个）──
│   │   ├── Auth.php                       #   登录态/管理员判定/当前用户缓存
│   │   ├── Permission.php                 #   版块权限体系（组×版块矩阵）
│   │   ├── Csrf.php                       #   CSRF Token 生成/校验/登录轮换
│   │   ├── Captcha.php                    #   自研图片验证码
│   │   ├── RateLimiter.php                #   文件/IP 级限流器（登录/发帖/评论/上传/搜索全覆盖）
│   │   ├── RememberMe.php                 #   记住登录（Token 轮换 + SHA-256 哈希）
│   │   ├── Content.php                    #   base64 解码 + HTML 净化白名单 + CSS style 白名单（sanitizeCssStyle）
│   │   ├── Emoji.php                      #   QQ 表情解析
│   │   ├── Segmenter.php                  #   中文二元分词器（bigram，纯 PHP）
│   │   ├── Search.php                     #   倒排索引全文检索（季度分文件读写）
│   │   ├── Settings.php                   #   站点配置三层缓存 + 统计计数器批量落库（shutdown flush）
│   │   ├── PageCache.php                  #   ★ 列表页静态缓存（永久化，发帖/回帖主动失效，游客命中直出）
│   │   ├── Points.php                     #   积分/等级体系
│   │   ├── Vote.php                       #   点赞/点踩
│   │   ├── Tag.php                        #   标签
│   │   ├── Theme.php                      #   主题体系
│   │   ├── Upload.php                     #   上传（扩展名+MIME 双白名单/像素炸弹防护/缩略图）
│   │   ├── Mailer.php                     #   邮件（SMTP/AES 密码加密）
│   │   ├── AuditLog.php                   #   审计日志
│   │   └── Plugin.php                     #   ★ 插件系统（钩子机制 + 插件独立库连接）
│   ├── Models/                            # ── 数据模型（10 个）──
│   │   ├── User.php / Thread.php / Post.php / Category.php / Tag.php
│   │   ├── Blog.php / BlogCategory.php / BlogComment.php / Message.php / Setting.php
│   └── Views/                             # ── 视图层（PHP 模板）──
│       ├── layouts/main.php               #   单模板主布局（页脚 Powered by FlintHub V1.0.0）
│       ├── _components/                   #   侧边栏组件
│       ├── errors/  emails/               #   通用错误页 / 邮件模板
│       ├── home/ forum/ thread/ post/ blog/ tags/ search/
│       ├── auth/                          #   登录/注册/找回密码/邮箱验证
│       ├── message/                       #   私信收/发/详情
│       ├── profile/ theme/               #   个人中心/主题设置
│       └── admin/                         #   后台视图
│
├── assets/                                # 静态资源
│   ├── css/
│   │   ├── modern.css                     #   ★ 主题基座（--mn-* 变量体系，含表格溢出双保险）
│   │   ├── components.css / admin.css / editor.css / style.css / fontawesome.css
│   │   └── themes/                        #   配色变体
│   ├── js/
│   │   ├── editor.js                      #   ★ 自研富文本编辑器（可视化+Markdown 双模式，localStorage 记忆）
│   │   ├── thread.js / auth.js
│   │   └── marked.min.js / turndown.js / turndown-plugin-gfm.js   # Markdown 转换（第三方，表格保真）
│   ├── lib/
│   │   ├── fhstate.js                    #   FhState 状态管理（Alpine.js 定制）
│   │   ├── fhajax.js                     #   FhAjax AJAX（htmx 定制）
│   │   └── qrcode.min.js                  #   二维码（第三方）
│   ├── img/emoji/  fonts/  medals/  themes/  uploads/
│
├── plugins/                               # ★ 插件目录（15 个，目录即插件，数据独立存放自身 data/）
│   ├── announcements/  content_review/  daily_checkin/  dice/  edit_info/
│   ├── friend_links/   icon_generator/   invite/        medal/ notifications/
│   ├── post_favorite/  quiz_duel/        red_packet/    seo/   user_profile/
│   └── plugins_cache.php                  #   插件扫描缓存
│
│   # 每个插件目录内部结构：
│   #   plugins/{id}/plugin.json           插件清单（name/version/activated/hooks）
│   #   plugins/{id}/Plugin.php            生命周期（activate/deactivate/uninstall）
│   #   plugins/{id}/hook/*.php            钩子文件
│   #   plugins/{id}/views/*.php           视图模板（view('plugins/xxx/yyy') 解析到此处）
│   #   plugins/{id}/data/{id}.sqlite      ★ 插件独立数据库（不依赖核心库）
│   #   plugins/{id}/assets/*              静态资源
│
├── cli/                                   # ★ 命令行工具（精简三件套，运行必需）
│   ├── worker.php                         #   队列消费者（常驻 / --once，supervisor 或 cron 调用）
│   ├── rebuild_search.php                 #   重建搜索索引（二级视图从分片全量重建）
│   └── archive.php                        #   冷数据归档（18 个月以上桶归档）
│   # 注：migrate_*/seed_*/smoke_*/probe_* 等迁移/测试/诊断脚本为开发期工具，发行版已精简
│
├── data/                                  # ★ SplitDB 数据目录（运行时生成；.htaccess + web.config 防下载）
│   ├── meta/                              #   元数据层（SQLite 库）
│   │   ├── business.sqlite                #   非分片业务：用户/版块/设置/博客/私信/附件/标签/投票
│   │   ├── main_index.sqlite              #   帖子主索引 topic_index(19.2万) + 回复定位索引 reply_index(16万)
│   │   ├── search/                        #   搜索索引季度分文件 search_{YYYYQn}.sqlite（235 万行）
│   │   ├── global_id.sqlite               #   全局 ID 生成器游标
│   │   ├── sessions.sqlite                #   会话存储（SQLite handler）
│   │   └── task_queue/queue_{0..2}.sqlite #   异步任务队列（三队列打散锁竞争）
│   ├── bucket/active/{季度}/{0..31}.sqlite  # 帖子/回复真相源（季度 × 32 桶哈希分片）
│   ├── bucket/archive/                    #   18 个月以上冷数据归档桶
│   ├── extern/{年}/{季}/{桶}/             #   正文外置：存量 .bin/.idx 偏移索引，新帖 .txt（读取自动回退）
│   ├── runtime/                           #   列表页静态缓存 pages/*.html、版块快照 category_*_latest.json
│   ├── lock/  log/                        #   文件锁 / 运行日志
│   └── .htaccess / web.config             #   ★ 目录访问防护（Apache/IIS，禁止 HTTP 直下）
│
└── protected/                             # 受保护数据（.htaccess + web.config 防下载）
    ├── .htaccess / web.config             #   ★ 目录访问防护
    ├── database/legacy/                   #   旧 MySQL 初始化归档（init/install/schema.sql，仅存档）
    ├── sessions/                          #   Session 文件兜底
    ├── cache/                             #   模板编译缓存 / 统计缓存
    ├── rate_cache/                        #   限流器 IP 记录
    ├── backups/                           #   数据库备份（含 config.php 升级备份）
    ├── error.log                          #   错误日志
    └── settings_cache.php                 #   站点设置缓存

V1.0.0 结构要点：核心从 MySQL 单库单表重构为 SplitDB 纯 SQLite 分片引擎（详见 Splitdb V2.3 白皮书.txt），app/SplitDB/ 为引擎落地；data/ 运行时自动生成；update/ 目录为与根目录同步的「可运行骨架」镜像（本安装包即取自该镜像 + 防护文件）。

二、程序特点

2.1 整体定位

• 极致轻量：零 Composer 依赖、零数据库服务进程（SQLite 嵌入式），复制文件 + data/ 可写即可部署，1 核 512M 流畅运行
• 数据引擎：SplitDB 分片引擎——季度时序分区 + 32 桶哈希分片（多文件分散锁竞争）、正文外置 extern、索引/搜索/统计为异步二级视图、队列管最终一致性
• 单模板体系：前台/后台共用 layouts/main.php 三栏骨架，Modern 主题 + --mn-* CSS 变量 + 配色变体热切换
• 全栈自研：路由、模板编译、ORM、SQLite Session、中文分词、倒排索引、富文本编辑器、验证码、限流器、插件系统全部自研
• 插件化：15 个功能插件通过钩子机制注入，数据独立存放自身 data/ 目录，可独立启停

2.2 安全特性（自研安全体系）

• SQL 注入：全库 PDO 预处理 + ATTR_EMULATE_PREPARES=false，IN/LIMIT 显式强转，排序/列名白名单，LIKE 通配符转义 + ESCAPE
• XSS：模板引擎 e() 全量转义 + 富文本 HTML 净化白名单（标签/属性双重校验）+ CSS style 白名单（sanitizeCssStyle 拦截 url()/expression/@import 等）
• CSRF：全局 Token 生成/校验，所有写操作（前台/后台/API 投票上传）全覆盖
• 上传安全：扩展名 + finfo MIME 双白名单、16 字节随机文件名、Imagick/GD 缩略图、5000px 像素炸弹拒绝
• SSRF 防护：远程拉图协议校验 + 内网段封禁 + DNS 解析后真实 IP 校验 + 跳转链逐跳校验
• 会话加固：SQLite 会话（独立连接防游标冲突）+ HttpOnly / SameSite=Lax / Strict Mode + 定期 GC（LIMIT 5000 分批）
• 认证加固：Auth::isAdmin 数据库双重确认（role=admin 且 group_id=4）、后台敏感操作 30 分钟二次验证、唯一管理员降级/删除保护、审计日志全记录
• 暴力破解防护：登录用户名级锁定 + 验证码 + 注册/发帖/搜索限流（RateLimiter Session+IP 双标识）
• 目录防护：data/、protected/ 均带 .htaccess（Apache）+ web.config（IIS）+ nginx-server.conf deny 规则（Nginx）三套防护，杜绝 SQLite 库/日志/备份被直接下载

2.3 性能特点（19.2 万帖 / 5 万用户实测）

• 首页：游客前置静态缓存命中 ~2.3ms（keep-alive，跳过框架引导）
• 统计：永久化缓存（发帖/回帖主动失效），GROUP BY 99ms → 2.14ms
• 深翻页：keyset 行值比较游标，第 12000 页 188ms → 0.36ms
• 个人中心/主页：uid 复合索引，按用户查帖子 80ms → 0.03~0.1ms
• 写放大硬上限：online_users 清理 / Session GC 均 LIMIT 5000 分批

2.4 功能矩阵

三、自研模块详解（重点）

3.1 自研 MVC 框架内核（app/Core）

3.2 SplitDB 分片引擎（app/SplitDB，白皮书 v2.3 落地）🗄️

• 数据分层：business（非分片业务） / main_index（帖子/回复索引） / search_{季度}（搜索索引） / global_id（ID 游标） / sessions / queue_{0..2} 六类 SQLite 库
• 分片规则：一级季度时序分区（YYYYQn）+ 二级 ID % 32 哈希分桶；读取永远以 main_index.bucket_path 为准，未来可平滑升级 32→64→128 桶、历史零迁移
• 写入链路：global_id 原子取号（BEGIN IMMEDIATE，兼容 SQLite 3.33 无 RETURNING）→ 季度+哈希路由 → extern 正文原子写（tmp+rename）→ 桶真相源 → main_index 索引行
• 读取链路：列表/分页走 main_index（索引行含 bucket_path）→ 详情读桶 + extern（.bin/.idx 偏移索引优先，缺失回退 .txt）
• 队列三模式（后台可切换）：sync 同步直写（数据 100% 实时）/ cron 定时触发（cron_trigger.php web 入口 + 文件锁）/ cli 常驻消费（worker.php）
• 浏览计数：APCu 内存计数 + shutdown 批量落库；无 APCu 静默降级为直写 UPDATE（不崩站）
• 连接池：单进程 LRU ≤8 句柄，统一 6 条 PRAGMA（WAL/busy_timeout/禁持久连接）
• 实测一致性：桶 topic=192111 = 索引 192111、桶 reply=160753 = 索引 160753（全盘审计对拍零偏差）

3.3 自研中文全文检索（Segmenter + Search + SearchIndexStore）🔍

• Segmenter.php：中文二元切词（bigram），纯 PHP、零扩展依赖
• Search.php：倒排索引检索（标题/正文权重分词），帖子/博客/用户三类对象，SQL 层版块权限过滤
• SearchIndexStore.php：搜索索引季度分文件存储（data/meta/search/search_{YYYYQn}.sqlite），与 business 库物理隔离（P21 瘦身 306MB → 19MB），写入不阻塞业务库
• 支持时间范围过滤（近 30/180/365 天）、rebuild_search.php 全量重建（二级视图可从分片重建）

3.4 自研富文本编辑器（assets/js/editor.js）✍️

• 基于 contenteditable + 原生 Selection/Range，可视化 + Markdown 双模式（marked + turndown，GFM 表格插件保真）
• 支持：加粗/斜体/标题/列表/对齐/字体颜色/背景色/字号/分割线/引用/链接/图片粘贴上传/QQ 表情/全屏/撤销重做/字数统计
• 编辑器模式 localStorage 记忆（默认可视化，切换即存，隐私模式安全回退）
• 安全：内容 base64 提交 + Content::decode 严格校验 + sanitizeHtml 白名单净化 + style 属性白名单（仅 color/font-size/text-align/background-color/border-radius，拦截危险 CSS）
• 表格溢出双保险：max-width:100% + table-layout:auto + word-break + 容器 overflow-x:auto（前台/编辑器同步）

3.5 自研插件系统（Plugin + plugin.json）🧩

• 目录即插件：plugins/{id}/ 一个目录包含全部（plugin.json 声明 + Plugin.php 生命周期 + hook/ 钩子 + views/ 视图 + assets/ 资源 + data/{id}.sqlite 独立库）
• 独立数据库：每个插件数据独立存放 plugins/{name}/data/{name}.sqlite（Plugin::db($name) 经 DBFactory 统一 PRAGMA），互不依赖，核心库只读访问保留
• 钩子机制：核心 25+ 个 hook 触发点（init_after/route_register/admin_route_register/admin_sidebar_links/nav_/layout_head_end/announcements_display/controller_view_before/route_before_dispatch/route_after_dispatch/auth_/avatar_upload_after/thread_create_after/post_create_after/thread_edit_after/post_edit_after/vote_after 等）
• 后台可激活/禁用/卸载；扫描结果缓存到 plugins_cache.php
• 现有 15 个插件：公告、内容审核、每日签到、掷骰子、编辑历史、友情链接、图标生成、邀请注册、勋章系统、通知、帖子收藏、答题对决、红包、SEO、用户主页

3.6 自研权限体系（Permission.php）🔐

• 用户组 × 版块权限矩阵（查看/发帖/回复/附件）
• Auth::isAdmin 双重确认（role=admin + group_id=4）
• 后台基类强制 isAdmin + admin_verified_at 30 分钟二次验证
• 帖子列表/搜索/标签聚合 SQL 层权限过滤，分页准确不泄露

3.7 自研基础设施

3.8 前端交互体系

• FhState（Alpine.js）+ FhAjax（htmx）双引擎：投票、批量操作、表单提交局部刷新
• 图片灯箱：PC 滚轮缩放 + 移动端双指捏合
• 移动端优先：底部导航、侧栏折叠、响应式三档断点

四、技术栈一览

五、安装与部署

1. 上传本目录全部文件到站点根目录（Nginx/Apache/IIS 均可，PHP ≥ 8.0 + PDO_SQLITE）
2. 浏览器访问 install.php → 环境检测 → 创建管理员 → 完成（自动生成 config.php 与 data/ 目录树）
3. 防护确认：

• Apache：data/、protected/ 下 .htaccess 自动生效
• IIS / Win 主机：web.config 自动生效
• Nginx：将 nginx-server.conf include 进站点配置并 reload（含 data/protected deny 规则）

1. 安装完成后删除 install.php；data/、protected/ 目录不可被 HTTP 直访（自检：访问 /data/meta/business.sqlite 应 403/404）
2. 可选：配置队列模式（后台「任务调度」：sync 默认 / cron 虚拟主机 / cli 常驻）

本文档完。FlintHub 1.0 —— 用纯 SQLite 分片引擎实现 PHP 社区系统的极致轻量与可靠性能。