燧石论坛(FlintHub) —— 轻量级、高性能、零 MySQL 依赖的 PHP 社区系统。 内核:SplitDB 纯 SQLite 分片存储引擎 v2.3 运行环境:PHP ≥ 8.0(推荐 8.2/8.4)· SQLite ≥ 3.33 · 无 MySQL / Redis / Composer 依赖 当前版本:
FLINTHUB_VERSION = V1.5.16(version.php是唯一版本源) 对应代码日期:2026-11-18
0. 关于本文档
0.1 文档定位
本文档不是"功能介绍页",而是随代码发行的技术手册,覆盖:
- 程序整体架构与一次请求的完整生命周期;
- 内核各层(入口 / 路由 / 控制器 / 模型 / 数据库门面)的职责边界;
- SplitDB 分片引擎的目录、路由、索引、外置正文、队列、搜索实现;
- 插件体系的加载、钩子、独立数据库、权限、市场与升级;
- 后台模块、安全体系、缓存体系、CLI 工具与运维方式;
- 开发约定与常见坑,以及版本与文档的对应关系。
0.2 版本同步约定(重要)
从本版开始,README 与代码版本一一对应:
- 版本号只允许在 version.php 中修改,README / CHANGELOG / 安装器全部读取同一常量;
- 每次发版必须同步更新本文档的以下位置:
- 文件头"当前版本 / 对应代码日期";
- 第 17 章"版本记录摘要"新增一条;
- 若新增/删除核心路由、钩子、数据表、CLI 工具,必须同步更新对应附录;
- 文档中涉及行号的位置一律只作参考,以文件 + 锚点描述为准(代码会漂移,锚点不会);
- 本 README 随核心包一起分发;插件不在核心包内,插件文档见 docs/插件开发规范.md。
0.3 读者对象
| 读者 | 建议重点阅读 |
|---|---|
| 站长 / 运维 | 第 2、3、12、14、15 章 |
| 二次开发者 | 第 4、5、6、7、8、9、16 章 |
| 插件作者 | 第 7.4、8、9 章 + docs/插件开发规范.md |
| 审计 / 安全 | 第 11 章 + 第 7.10 节 |
1. 项目概览
1.1 项目定位
FlintHub 面向低资源虚拟主机、轻量服务器、个人社区场景。它放弃对 MySQL 的重依赖,改用自研 SplitDB 纯 SQLite 分片引擎,让普通 PHP 虚拟主机也能承载可观的社区规模。
核心理念:
- 零外部依赖:纯 PHP + SQLite,无 Composer、无 Redis、无专用 Nginx 模块;
- 单一入口:所有动态请求经
index.php前端控制器分发; - 分片存储:季度时序分区 + 哈希分桶,单库文件小、读写均衡;
- 外置正文:帖子/回复正文从 SQLite 剥离为文本/归档文件,库文件保持轻量;
- 插件驱动:核心保持微内核,功能通过钩子插件扩展,插件拥有独立数据库;
- 渐进增强:服务端渲染为主,Alpine.js / htmx 只做局部交互。
1.2 规模基准(参考值)
以下为历史生产环境实测基准,仅用于说明设计目标,不代表任意部署的性能承诺:
- 19 万+ 主题、16 万+ 回复、5 万+ 用户、235 万+ 搜索索引行;
- 游客列表页静态缓存命中约 3~10ms(不含网络传输);
- 单次详情页请求约 0.12s(
init_after聚合戳生效后,v1.5.12 实测)。
1.3 核心特性
| 维度 | 实现 |
|---|---|
| 数据库 | 纯 SQLite;business.sqlite + main_index.sqlite + 季度分片桶 + 独立会话库 + 独立搜索库 |
| 分片 | 一级按季度(YYYYQn)、二级按 id % 32 哈希;支持 32 → 64 → 128 平滑扩容,历史数据零迁移 |
| 正文存储 | .txt 外置正文 + .bin/.idx 归档块,支持 APCu 读缓存,缺失 APCu 自动降级 |
| 搜索 | 自研倒排索引(季度分库)+ 中文二元切词;索引不可用时才降级 LIKE |
| 缓存 | 游客列表页静态 HTML、Settings 三层缓存、插件建表令牌、init_after 聚合戳、APCu 浏览量 |
| 插件 | 钩子系统 + 独立 SQLite + 多语言 + 权限声明 + 入口级开关 + 故障健康记录 + 跨站市场 |
| 多语言 | zh / en / zh_tw,核心键优先合并,缺 key 逐级回退 |
| 主题 | 单模板体系 modern + assets/themes/<theme> 模板覆盖层 + CSS 变量配色 |
| 前端 | 服务端渲染 + Alpine.js + htmx + 自研编辑器;PWA(Service Worker + 动态 manifest) |
| 安全 | 参数化查询、模板转义、CSRF 门禁、XSS 白名单、上传白名单 + MIME、PoW/验证码、限流、审计日志 |
| 部署 | 根目录或任意二级目录;Apache / Nginx / IIS 配置随包提供 |
| 升级 | 后台在线升级:检查 → 预检 → 下载验签 → 备份 → 应用 → 回滚 |
1.4 与常规论坛程序的差异
| 常规做法 | FlintHub 做法 | 原因 |
|---|---|---|
| MySQL 单库多表 | SQLite 多库 + 季度分桶 | 虚拟主机无数据库服务,SQLite 零运维 |
| 帖子正文存库 | 正文外置文件 | 控制单库体积,列表查询不拖正文 |
| 插件与核心同库 | 插件独立 SQLite | 隔离故障与写锁,卸载即删库 |
| 插件改核心模板 | 只允许钩子注入 | 升级可覆盖核心,降低维护成本 |
| 全站动态渲染 | 游客列表页静态缓存 | 低配主机扛住游客流量 |
2. 运行环境
2.1 必需环境
| 项 | 要求 | 说明 |
|---|---|---|
| PHP | ≥ 8.0,推荐 8.2 / 8.4 | 生产已验证 PHP 8.4 |
| PDO | pdo + pdo_sqlite | 所有数据访问入口 |
| SQLite | ≥ 3.33 | 依赖 ON CONFLICT、WAL;兼容基线不要求 RETURNING |
| mbstring | 必需 | 中文截断、长度计算 |
| fileinfo | 必需 | 上传 MIME 检测 |
| curl | 必需 | 远程抓图、升级、插件市场 |
| gd 或 imagick | 二选一 | 缩略图 |
| openssl | 必需 | SMTP 密码加密、签名校验 |
| zip | 必需 | 插件/升级包解压 |
| dom | 必需 | HTML 净化(DOMDocument) |
2.2 不需要的组件
- MySQL / MariaDB;
- Redis / Memcached(APCu 为可选加速,不是必需);
- Composer / Node.js(运行期不需要);
- 额外 Nginx 模块(伪静态使用标准
rewrite/try_files)。
2.3 目录写权限
以下路径需要可写(Linux 建议目录 755、文件 644;data/、protected/ 建议 770):
- 站点根目录(安装时生成
config.php); data/(SQLite 库、正文、缓存、锁、日志);protected/sessions、protected/cache、protected/rate_cache;assets/uploads/。
3. 快速开始
3.1 全新安装
- 上传核心包到站点根目录(或子目录);
- 配置伪静态:
- Apache:使用随包
.htaccess,确保AllowOverride FileInfo; - Nginx:使用
nginx-server.conf/nginx-baota.conf; - IIS:使用
web.config;
- Apache:使用随包
- 浏览器访问
install.php:- 第 1 步:环境检测(PHP / PDO SQLite / SQLite 版本 / 扩展 / 目录可写 / zip / dom);
- 第 2 步:
Schema::bootstrap()初始化 SplitDB(建目录树、建库建表、写防护文件); - 第 3 步:创建管理员;
- 完成后生成
protected/.install_done,再次访问安装器会被拒绝; - 登录
/admin配置站点。
详细步骤见 INSTALL.md。
3.2 升级
两种方式:
- 后台在线升级:
/admin/update,流程为"检查 → 预检 → 取包 → 校验 → 备份 → 应用 → 回滚"; - 完整包覆盖:解压覆盖程序目录,保留
data/、protected/、assets/uploads/、plugins/,随后清理前台页面缓存。
在线升级的纳管范围有硬黑名单:config.php、data/、protected/、plugins/、assets/uploads/、assets/themes/、release/ 等永不覆盖、永不删除。
3.3 二级目录部署
- 安装器会按实际子目录写入
BASE_PATH与UPLOAD_URL; - 手工部署时在
config.php中设置:
define('BASE_PATH', '/forum');
Router、Controller、PageCache、I18n、Url 全链路会自动剥离/拼接该前缀。
3.4 定时任务
队列与低频维护建议每 5 分钟触发一次:
*/5 * * * * curl -s -H "X-Cron-Key: YOUR_CRON_KEY" "https://your-site/cron_trigger.php"
约束:
- 仅当
settings.queue_mode = cron时执行; - 必须携带
CRON_KEY(HeaderX-Cron-Key或?key=),未配置直接 503; - 文件锁
data/lock/cron_trigger.lock防止并发重入; - 执行上限 600 秒。
3.5 安装后自检
- 首页、
/forum、版块页是否正常; /admin能否登录并完成二次验证;- 后台"数据库 → 概览"是否显示各库文件;
- 上传一张图片,确认缩略图与访问 URL 正常;
- 发送一封测试邮件;
- 访问
/manifest.webmanifest与/offline验证 PWA。
4. 目录结构
站点根/
├── index.php 前端控制器:前置缓存、308 归一、静态逃生口、路由注册与分发
├── config.php 站点配置(安装时生成,不进发行包):数据路径 / 上传 / 邮件 / Session / SITE_URL
├── version.php 唯一版本源:FLINTHUB_VERSION
├── install.php Web 安装器(环境检测 / SplitDB 初始化 / 创建管理员)
├── cron_trigger.php Cron Web 触发入口(队列消费 + 低频维护)
├── sw.js PWA Service Worker
├── .htaccess Apache 伪静态 + 敏感目录防护
├── nginx-server.conf Nginx 站点完整配置模板
├── nginx-baota.conf 宝塔面板适配配置
├── web.config IIS 配置
│
├── app/ 核心应用(微内核)
│ ├── init.php 应用引导:Session、i18n、自动登录、在线状态、插件初始化、维护模式
│ ├── Core/ 框架内核
│ │ ├── Autoloader.php PSR-4 风格自动加载(app\ 与 Plugin\ 双命名空间)
│ │ ├── Router.php GET/POST/ANY、分组、参数提取、分发、CSRF 门禁、404
│ │ ├── Controller.php 视图 / JSON / 重定向 / 安全头 / 缓存头 / 权限门禁
│ │ ├── Model.php 基础 ORM:CRUD、参数化、可更新列白名单
│ │ ├── Database.php DB 门面:业务库 / 会话库 / 查询计数 / 事务
│ │ ├── SessionHandler.php SessionHandlerInterface + SessionUpdateTimestampHandlerInterface
│ │ ├── TemplateCompiler.php 自研模板编译器(变量/条件/循环/包含/继承/区块)
│ │ └── SecurityHeaders.php 统一安全响应头(CSP / HSTS / Permissions-Policy 等)
│ │
│ ├── SplitDB/ SplitDB 存储引擎
│ │ ├── Schema.php 建库建表、桶表、会话库、ID 库、队列库、列补丁
│ │ ├── ShardRouter.php 季度分区、哈希分桶、写路由、正文路径、扩容路由
│ │ ├── DBFactory.php SQLite 连接池(LRU 8 句柄)+ 统一 PRAGMA + WAL 校验
│ │ ├── ExternStorage.php 外置正文读写(原子替换 + APCu 缓存 + 路径安全)
│ │ ├── ExternMerger.php 正文碎片合并
│ │ ├── ExternIdxRepairer.php 外置索引修复
│ │ ├── ExternNamespaceMigrator.php 主题/回复正文命名空间迁移
│ │ ├── IDGenerator.php 全局 ID 原子取号(BEGIN IMMEDIATE,兼容 SQLite 3.33)
│ │ ├── SearchIndexStore.php 搜索索引季度分库
│ │ ├── Queue.php 任务队列(queue_0 ~ queue_2)
│ │ ├── QueueConsumer.php 队列消费(同步 / Cron / CLI)
│ │ ├── ViewCounter.php 浏览量计数(APCu 累加 + 请求结束批量落库)
│ │ ├── BucketAutoScaler.php 桶自动扩容
│ │ └── CountingPDO.php PDO 包装:统一 SQL 计数
│ │
│ ├── Helpers/ 公共服务(38 个文件)
│ │ ├── Auth.php 登录态、密码校验、管理员判定、回跳
│ │ ├── Permission.php 用户组 / 版块权限矩阵
│ │ ├── Csrf.php CSRF Token 生成与一次性消费
│ │ ├── CsrfGate.php 全局 CSRF 门禁(路由命中后、控制器实例化前)
│ │ ├── RateLimiter.php 频率限制(Session + IP)
│ │ ├── LoginThrottle.php 登录失败锁定
│ │ ├── PoW.php 工作量证明
│ │ ├── Captcha.php 图形验证码
│ │ ├── PasswordPolicy.php 密码策略
│ │ ├── Settings.php 设置三层缓存 + 运行时计数器
│ │ ├── I18n.php 多语言探测 / 合并 / 回退
│ │ ├── Theme.php 主题发现 / 切换 / 列表偏好
│ │ ├── Url.php URL 生成的唯一出口(伪静态感知)
│ │ ├── PageCache.php 游客列表页静态缓存
│ │ ├── RewriteProbe.php 伪静态实测探针
│ │ ├── RewriteRules.php 伪静态规则生成(支持插件扩展)
│ │ ├── Plugin.php 插件加载 / 钩子分发 / 独立库 / 权限 / 健康
│ │ ├── PluginUpdater.php 插件安装升级编排
│ │ ├── Market.php 跨站插件市场(Client 侧)
│ │ ├── Updater.php 核心在线升级内核
│ │ ├── Upload.php 上传、缩略图、URL 改写钩子
│ │ ├── Content.php HTML 净化、摘要、楼中楼引用
│ │ ├── Emoji.php 表情映射
│ │ ├── Search.php 搜索入口(倒排优先,LIKE 兜底)
│ │ ├── Segmenter.php 中文二元切词
│ │ ├── SearchRebuild.php 搜索索引重建
│ │ ├── Tag.php 标签
│ │ ├── Points.php 积分与等级
│ │ ├── Vote.php 投票 / 点赞
│ │ ├── Notification.php 通知
│ │ ├── Mailer.php SMTP / mail() / 插件接管
│ │ ├── AuditLog.php 审计日志
│ │ ├── RememberMe.php 记住我
│ │ ├── KeyGuard.php 密钥加固检测
│ │ ├── Cache.php 通用文件缓存
│ │ └── UserPrefs.php 用户界面偏好
│ │
│ ├── Controllers/ 前台控制器(15 个)+ Admin/(19 个后台控制器)
│ ├── Models/ 模型:Thread / Post / User / Category / Message / Tag / Setting
│ └── Views/ 视图
│ ├── layouts/ 布局(main.php)
│ ├── _components/ 左栏 / 右栏 / 移动侧栏 / 附件卡 / 通知铃 / 灯箱 / 页脚备案
│ ├── admin/ 后台视图
│ ├── auth/ 登录 / 注册 / 找回 / 重置
│ ├── forum/ 首页 / 版块
│ ├── thread/ 详情 / 编辑
│ ├── post/ 发帖 / 编辑
│ ├── message/ 私信
│ ├── notifications/ 通知
│ ├── profile/ 个人中心
│ ├── search/ 搜索
│ ├── tags/ 标签
│ ├── user/ 用户公开主页
│ └── errors/ 404 / 429
│
├── assets/ 前端静态资源
│ ├── css/ modern.css / admin.css / editor.css / portal.css 等
│ ├── js/ editor.js / pow.js / layout.js / lightbox.js / pwa.js 等
│ ├── img/ logo / badge / 默认图
│ ├── fonts/ 字体
│ ├── medals/ 勋章图
│ ├── pwa/ PWA 图标与截图
│ ├── themes/<theme>/ 主题模板覆盖层(如 graphite)
│ └── uploads/ 用户上传(按月归档,禁止 PHP 执行)
│
├── cli/ 命令行维护工具(见第 14 章)
├── lang/ 语言包:zh.php / en.php / zh_tw.php
├── plugins/ 插件目录(一目录一插件;核心包默认不含插件)
├── docs/ 项目文档(插件开发规范、各插件方案与验收报告)
│
├── data/ 运行时数据(安装时生成,禁止 Web 直访)
│ ├── meta/ business.sqlite / main_index.sqlite / sessions.sqlite / global_id.sqlite / search/
│ ├── bucket/active/<季度>/ 当前写入桶
│ ├── bucket/archive/<季度>/ 冷数据归档桶
│ ├── extern/<年>/<季度>/ 外置正文
│ ├── runtime/ 页面缓存、升级包、插件缓存、探针结果
│ ├── market/ 插件市场清单 / 包 / 截图 / 投稿
│ ├── backup/ 升级与操作备份
│ ├── lock/ 文件锁
│ └── log/ 业务日志
│
├── protected/ 运行产物(安装时生成,禁止 Web 直访)
│ ├── sessions/ 文件 Session 兜底
│ ├── cache/templates/ 模板编译缓存
│ ├── rate_cache/ 频率限制缓存
│ ├── settings_cache.php 设置缓存
│ └── error.log 错误日志
│
├── release/ 发版产物(core / plugins / submit)
├── update/ 历史增量补丁
└── flinthub-client/ 独立客户端工程(Vite)
flinthub-deployer/ Windows 一键部署工具(Go + Wails)
版本库里的
plugins/是开发环境已安装插件集合;官方核心发行包不包含任何插件。
5. 总体架构
5.1 分层视图
┌──────────────────────────────────────────────────────────────────────┐
│ 浏览器 / PWA / 客户端 │
└───────────────────────────────┬──────────────────────────────────────┘
│ HTTP
┌───────────────────────────────▼──────────────────────────────────────┐
│ 入口层 index.php │
│ 错误抑制 → HEAD 处理 → 308 归一 → 静态逃生口 → 前置页面缓存 │
│ → app/init.php → 路由注册 → Router::dispatch() │
└───────────────────────────────┬──────────────────────────────────────┘
│
┌───────────────────────────────▼──────────────────────────────────────┐
│ 应用层 Router → Controller → Service/Model │
│ CSRF 门禁、权限门禁、视图数据装配、JSON / 重定向 │
└───────────────┬───────────────────────────────────┬──────────────────┘
│ │
┌───────────────▼──────────────────┐ ┌─────────────▼──────────────────┐
│ 存储层 SplitDB │ │ 展示层 TemplateCompiler │
│ Database 门面 │ │ 布局继承 + 主题覆盖层 │
│ Schema / ShardRouter / DBFactory │ │ 变量 / 条件 / 循环 / 包含 │
│ ExternStorage / Search / Queue │ │ i18n / 图标 / 转义 │
└───────────────┬──────────────────┘ └─────────────┬──────────────────┘
│ │
┌───────────────▼──────────────────┐ ┌─────────────▼──────────────────┐
│ SQLite 文件族 │ │ HTML / CSS / JS │
│ business / main_index / bucket │ │ modern.css / Alpine / htmx │
│ sessions / global_id / search │ │ editor.js / lightbox / PWA │
└──────────────────────────────────┘ └────────────────────────────────┘
▲ ▲
└────────────── 插件钩子 ────────────┘
(Plugin::hook 在入口、控制器、视图、写操作处注入)
5.2 一次请求的完整生命周期
以游客访问 /thread/123 为例:
- Web 服务器:真实文件直接返回;动态路径按伪静态规则转发到
index.php; index.php顶部:- 关闭
display_errors,开启log_errors; - 处理
HEAD:复用 GET 管线,丢弃响应体; - 未安装(无
config.php)→ 跳转install.php; - 预读
settings_cache.php注入SITE_URL_OVERRIDE(兼容老config.php); - 伪静态开启时,
/index.php/...的 GET/HEAD 请求 308 到干净 URL(后台/登录/注册/登出例外); - 直接访问模式下,
/index.php/静态资源若物理文件存在则 301 到干净地址;
- 关闭
- 前置缓存判定:纯游客或"有会话但未登录"的游客,且路径属于首页/论坛/版块 → 读取
data/runtime/pages/*.html,命中直接输出并退出(跳过 Session / DB / 插件); app/init.php:- 注册自动加载;
- 加载
config.php(常量、Session 参数、SITE_URL); - 使用
SessionHandler(sessions.sqlite)启动 Session; - 处理
?lang=切换(PRG 回跳); RememberMe::check()自动登录;- 更新在线状态;
- 创建
TemplateCompiler全局实例; Plugin::init()加载插件清单;- 触发
init_after(有 60 秒聚合戳门控); - 维护模式检查;
- 路由注册:前台路由 →
/admin分组 →/api分组 →route_register→/u/{id}兜底 →route_before_dispatch; Router::dispatch():- 归一化 URI(剥离
BASE_PATH与/index.php,支持?r=); - 触发一次无参
route_before_dispatch(封禁拦截); - 按注册顺序匹配方法与正则;
- 命中后先过
CsrfGate::guard(),再实例化控制器并调用动作; - 未命中输出 404(
Cache-Control: no-store);
- 归一化 URI(剥离
- 控制器:
requireLogin()/requireAdmin()等门禁;- 调用 Model / SplitDB 读取数据;
Controller::view()合并默认数据(当前用户、未读数、主题、CSRF、渲染耗时)→ 触发controller_view_before→ 渲染模板;
- 模板:
TemplateCompiler先查assets/themes/<当前主题>/覆盖层,再查app/Views/;- 编译为 PHP 并缓存到
protected/cache/templates/; - 布局
main通过{section}/{yield}组合页面;
- 输出:安全头(
SecurityHeaders)+ 分级缓存头;请求结束回调批量刷计数器与浏览量; - 收尾:
route_after_dispatch触发(异步型收尾任务挂这里)。
5.3 架构取舍
| 决策 | 收益 | 代价 / 约束 |
|---|---|---|
| 单入口前端控制器 | 路由、鉴权、缓存统一 | 所有动态请求都经过 PHP |
| SQLite 多库分片 | 无数据库服务、单库小 | 跨库事务不存在,删除需业务层显式清理 |
| 正文外置 | 库小、列表快 | 正文读写走文件系统,依赖磁盘 IO |
| 微内核 + 插件 | 核心可升级、功能可裁剪 | 插件质量参差,需要权限与健康机制约束 |
| 服务端渲染为主 | 首屏快、SEO 友好 | 局部交互依赖 Alpine/htmx |
| 永久页面缓存 + 主动失效 | 游客命中极快 | 写操作必须显式失效缓存 |
6. 内核层详解
6.1 前端控制器 index.php
职责按执行顺序:
| 阶段 | 作用 |
|---|---|
| 错误抑制 | 早于 config.php,避免老配置文件的 Warning 污染 JSON 响应 |
| BOM 兜底 | 检测密钥文件 BOM,必要时启用输出缓冲剥离 BOM |
APP_START_TIME | 记录服务端渲染起点 |
| HEAD 处理 | 开启丢弃响应体的输出缓冲 |
| 安装检测 | 无 config.php 跳转安装器 |
| SITE_URL 前置 | 兼容老 config.php 的 SITE_URL 取值链 |
| 308 归一 | 伪静态开启时把 /index.php/... 归一为干净 URL |
| 静态逃生口 | 直接访问模式下把 /index.php/assets/... 301 到真实静态地址 |
| 前置缓存 | 游客列表页静态 HTML 命中即输出 |
$_GET 规整 | 剥离数组型参数,防止任意访客触发 500 |
| 路由注册 | 前台、后台、API、插件钩子、用户主页兜底 |
| 分发 | Router::dispatch(),异常统一 500 |
| 收尾 | Settings::flushCounters() + ViewCounter::flush() + route_after_dispatch |
6.2 应用引导 app/init.php
顺序固定,不可随意调整:
- 自动加载;
- 加载配置;
- Session 存储(
sessions.sqlite,失败回退文件); session_start();- i18n 初始化(
?lang=切换 + 预热); - 自动登录 + 在线状态;
- 模板引擎实例;
Plugin::init();init_after钩子(聚合戳门控);BASE_PATH兜底(仅当未定义);- 维护模式拦截(管理员 / 登录 / 注册 / API / 探针放行)。
6.3 自动加载 app/Core/Autoloader.php
支持两个命名空间:
| 前缀 | 映射 | 说明 |
|---|---|---|
app\ | app/<相对路径>.php | 核心类 |
Plugin\ | plugins/<目录>/<相对路径>.php | 插件类,按目录名、下划线转蛇形、全小写三种候选 |
安全措施:
- 拒绝类名中的
..; realpath()校验目标必须位于app/或plugins/根内,防软链/兄弟目录逃逸。
6.4 路由 app/Core/Router.php
能力:
get()/post()/any();group($prefix, $callback):立即执行回调并拼接前缀;- 参数占位符
{name}编译为命名捕获组(?P<name>[^/]+); - 分发时剥离
BASE_PATH与/index.php; ?r=/path兼容入口(禁止访问/admin);- HEAD 复用 GET;
- 命中后先过
CsrfGate::guard(); - 未命中输出 404 视图。
路由按注册顺序匹配,先注册先赢。插件路由在核心之后注册,
/u/{id}兜底刻意放在插件路由之后,避免抢占插件主页。
6.5 控制器基类 app/Core/Controller.php
| 方法 | 作用 |
|---|---|
view($template, $data) | 合并默认数据、触发 controller_view_before、渲染并挂 main 布局 |
viewRaw() | 不挂布局,用于片段/特殊页 |
json($data, $status) | JSON 响应,no-store + nosniff |
redirect($url) | 站内跳转,自动补 BASE_PATH / 入口前缀,关闭 Session 写锁 |
requireLogin() | 未登录跳登录并记录回跳 |
requireAdmin() | 前台管理员门禁(302) |
requireAdminVerified() | 管理员二次验证门禁(超时 60s ~ 7 天) |
setSecurityHeaders() | 统一安全头 |
cacheHeaders() | 分级缓存头(no-store / private, no-cache) |
默认视图数据:站点名、站点描述、当前用户、登录态、管理员态、未读私信数、渲染耗时、当前主题、CSRF Token、当前导航。
6.6 模型基类 app/Core/Model.php
find()/all()/findWhere()/findAllWhere();insert()/update()/delete();- 可更新列白名单
$fillable,白名单外字段忽略并记日志(fail-closed); ORDER BY统一经sanitizeOrderBy()清洗,防注入;- 表列元数据
PRAGMA table_info请求内缓存。
具体模型:
| 模型 | 负责 |
|---|---|
Thread | 主题列表 / 详情 / 发帖 / 编辑 / 删除 / 计数 / 归档 |
Post | 回复读写、楼中楼、回复分页 |
User | 用户 CRUD、密码、注册、级联删除 |
Category | 版块 CRUD、版块统计缓存 |
Message | 私信 |
Tag | 标签 |
Setting | 设置 KV |
6.7 数据库门面 app/Core/Database.php
getInstance():业务库单例;getConnection():原始 PDO(business.sqlite);getSessionConnection():会话库独立连接;query()/fetchAll()/fetchOne()/lastInsertId();begin()/commit()/rollback():嵌套事务保护(已在事务中直接放行);- 查询计数:
getQueryCount()/getTotalSqlCount(); - 异常处理:真实 SQL 与错误只写日志,对外抛通用异常;
closeAll():请求结束释放连接池与强引用。
6.8 会话 app/Core/SessionHandler.php
- 实现
SessionHandlerInterface+SessionUpdateTimestampHandlerInterface; - 存储于
data/meta/sessions.sqlite,与业务库物理隔离; validateId()使session.use_strict_mode=1真正生效;- 文件
protected/sessions/仅作兜底; - 过期清理迁移到
cron_trigger.php低频维护,不占热路径。
6.9 模板辅助方法
视图内通过 $this 调用:
| 方法 | 作用 |
|---|---|
e($value) | HTML 转义输出 |
t($key, $params) | 多语言文案 |
asset($path) | 静态资源 URL(自动补 BASE_PATH,不补入口脚本) |
url($path) | 站内 URL(伪静态感知) |
icon($name, $size, $class) | 图标输出 |
7. SplitDB 存储引擎
7.1 设计目标
- 单库文件保持小体积,避免 SQLite 大库锁竞争与备份困难;
- 写入按时间与哈希分散,读路径可预测;
- 扩容不迁移历史数据;
- 正文与索引分离,列表查询不触碰正文;
- 所有连接统一 PRAGMA,避免"某处连接参数不同"导致静默故障。
7.2 数据目录布局
data/
├── meta/
│ ├── business.sqlite 非分片业务表
│ ├── main_index.sqlite topic_index / reply_index
│ ├── sessions.sqlite Session
│ ├── global_id.sqlite 全局 ID 发生器
│ ├── task_queue/ queue_0.sqlite ~ queue_2.sqlite
│ └── search/ search_2026Q3.sqlite ...
├── bucket/
│ ├── active/2026Q4/0.sqlite ... 31.sqlite
│ └── archive/2025Q1/... 冷数据
├── extern/2026/Q4/5/t123.txt 外置正文(t=主题,r=回复)
├── runtime/
│ ├── pages/ 游客列表页缓存
│ ├── packages/ 升级包
│ ├── plugin_schema.json 插件建表令牌
│ ├── hook_symbols.json 钩子符号缓存
│ └── rewrite_probe.json 伪静态探针结果
├── market/ 插件市场
├── backup/ 备份
├── lock/ 文件锁
└── log/ 业务日志
7.3 meta 库职责
| 库 | 表 | 职责 |
|---|---|---|
business.sqlite | users、categories、messages、attachments、settings、online_users、password_resets、points_log、viewed_replies、level_config、user_groups、category_permissions、tags、thread_tags、thread_votes、post_votes、notifications、audit_logs | 所有非分片业务 |
business.sqlite | threads、posts | 过渡期兼容表,分片后退役,新数据写桶 |
main_index.sqlite | topic_index | 主题主索引:列表排序字段、统计、bucket_path、摘要 |
main_index.sqlite | reply_index | 回复定位索引:pid、uid、bucket_path |
sessions.sqlite | sessions | 会话,独立写锁 |
global_id.sqlite | id_generator | 主题/回复全局 ID |
task_queue/queue_n.sqlite | 队列表 | 异步任务,3 个队列分散写 |
search/search_YYYYQn.sqlite | 倒排索引表 | 按季度分文件 |
7.4 分片路由 ShardRouter
| 规则 | 说明 |
|---|---|
| 一级分区 | 季度 YYYYQn,新数据写当前季度 |
| 二级分区 | id % SPLITDB_BUCKET_SIZE(默认 32) |
| 写入路由 | bucketForWrite($id, $createdAt);扩容后新帖进入新增桶区间 |
| 读取路由 | 永远以 main_index.*.bucket_path 为准,不再二次哈希 |
| 桶路径 | bucket/active/{季度}/{桶}.sqlite |
| 归档路径 | bucket/archive/{季度}/{桶}.sqlite |
| 正文路径 | extern/{年}/{季度}/{桶}/t{id}.txt 或 r{id}.txt |
| 扩容 | SPLITDB_BUCKET_SIZE 32→64→128,配合 SPLITDB_LAST_EXPANSION_AT / SPLITDB_PREV_BUCKET_SIZE;历史数据零迁移 |
路径安全:
externRel()严格校验季度格式、内容类型、桶号;ExternStorage折叠./..并校验最终路径必须位于数据根内。
7.5 外置正文 ExternStorage
- 写入:临时文件 +
rename原子替换; - 读取:优先 APCu(TTL 600s),无 APCu 自动降级直读;
- 归档:
.bin+.idx块,按类型前缀(t/r)隔离; - 命名空间:主题与回复 ID 区间重叠,文件名必须带类型前缀;
- 兼容:缺带前缀块时回退旧版裸名块;
- 安全:拒绝 NUL、绝对路径、穿越路径。
7.6 全局 ID IDGenerator
id_generator(table_name, last_id);- 使用
BEGIN IMMEDIATE写锁事务完成SELECT + UPDATE,兼容 SQLite 3.33(不用RETURNING); - 取号期间把
busy_timeout临时降为 1000ms,结束后恢复 5000ms; - 带重试;超过重试次数抛异常。
7.7 搜索
| 层 | 实现 |
|---|---|
| 分词 | Segmenter:中文二元切词 + 英文/数字分词 |
| 索引 | SearchIndexStore:按季度落 search_YYYYQn.sqlite |
| 写入 | 发帖/回帖/编辑后同步写索引 |
| 查询 | 按时间范围计算覆盖季度集合,只查相关文件,各文件取候选后归并 TOP N |
| 降级 | 仅当索引缺失/损坏(no such table 等)才回退 LIKE;其他异常照常抛出 |
| 重建 | cli/rebuild_search.php / cli/rebuild_index.php / 后台维护 |
7.8 队列与异步任务
- 3 个独立队列库:
queue_0.sqlite~queue_2.sqlite,写入随机分散; - 消费模式由
settings.queue_mode控制:sync:请求内同步执行(默认,适合低负载);cron:cron_trigger.php每次各 drain 一次;cli:cli/worker.php/cli/worker2.php常驻消费;
cron_trigger.php带模式守卫、密钥校验、文件锁、600 秒上限。
7.9 浏览量 ViewCounter
- APCu 可用:
apcu_inc内存累加,请求结束flush()用APCUIterator批量写main_index.view_count; - APCu 不可用:直接
UPDATE实时计数; - 用
apcu_cas抢占,避免重复落库; - 任何异常只记日志,不影响页面。
7.10 连接池与 PRAGMA DBFactory
| 项 | 值 |
|---|---|
| 最大常驻句柄 | 8(LRU) |
| 持久连接 | 禁止 |
busy_timeout | 10000ms |
journal_mode | WAL(强制校验,非 WAL 拒绝使用) |
synchronous | NORMAL |
cache_size | -20000(约 20MB) |
temp_store | MEMORY |
foreign_keys | OFF(分片架构下跨库外键不成立,删除由业务层显式清理) |
| 事务保护 | 淘汰前检测 PDO 事务与原生 BEGIN 事务,避免丢弃未提交事务 |
7.11 桶库与归档
- 桶内表:
topic(主题真相源)、reply(回复真相源); - 时间统一秒级
INTEGER,模型层转字符串; - 桶 schema 版本写入
PRAGMA user_version,命中即跳过建表 DDL; - 归档桶默认只读(
PRAGMA query_only=1),仅后台维护/迁移/删除路径显式允许写; BucketAutoScaler负责自动扩容判定,cli/archive.php/cli/archive_mark.php负责冷数据归档。
8. 视图与模板引擎
8.1 模板语法
| 语法 | 作用 |
|---|---|
{$var} | 转义输出 |
{$var:raw} | 原始输出(仅可信 HTML) |
{$icon:name} | 图标 |
{$t:key} | 多语言文案 |
{if expr} / {elseif expr} / {else} / {/if} | 条件 |
{loop $arr $item} / {loop $arr $k $v} / {/loop} | 循环 |
{include path} | 包含模板 |
{extend layout} | 继承布局 |
{section name} / {/section} | 定义区块 |
{yield name} / {yield name default} | 输出区块 |
{* comment *} | 注释,不输出 |
安全约束:
{php ...}标签在编译前整段抹除,既不执行也不残留;{loop}的数组表达式限制为标识符 + 数组键 + 引号 +->,禁止函数调用;- 变量输出默认
htmlspecialchars(ENT_QUOTES, UTF-8)。
8.2 模板查找顺序
assets/themes/<当前主题>/<template>.php;assets/themes/<当前主题>/<template>.html;- 插件模板:
plugins/<id>/views/<rest>.php|.html(当模板名以plugins/开头); app/Views/<template>.php;app/Views/<template>.html。
后台请求(/admin 前缀)不套用前台主题覆盖层。
8.3 编译缓存
- 编译结果写入
protected/cache/templates/; - 目录权限
0750; - 主题/模板变更后由后台"清缓存"或文件 mtime 机制失效。
8.4 布局与组件
- 布局:
app/Views/layouts/main.php(约 46KB); - 组件:
left_sidebar.php:PC 左栏;right_sidebar.php:PC 右栏(列表页 / 详情页两套结构);mobile_sidebar.php:移动端侧栏;notification_bell.php:通知铃;attachment_card.php:附件卡;image_lightbox.php:图片灯箱;footer_beian.php:备案页脚。
9. 插件系统
9.1 插件目录结构
plugins/<plugin_name>/
├── plugin.json 清单:名称、版本、钩子、权限、配置项、后台入口
├── Plugin.php 主类(生命周期、安装/卸载、权限声明)
├── AdminController.php 后台控制器(可选)
├── ApiController.php 前端/接口控制器(可选)
├── hook/ 钩子文件,按钩子名命名
├── views/ 插件视图
├── assets/ 插件 CSS / JS
├── lang/ 插件语言包
├── data/ 插件独立 SQLite(运行时生成,禁止 Web 直访)
└── 说明.md 插件说明(可选)
9.2 plugin.json 关键字段
| 字段 | 说明 |
|---|---|
name | 展示名 |
version | 插件版本 |
min_core | 最低核心版本 |
author / description / category / icon | 元信息 |
activated | 是否启用 |
sort_order | 加载/渲染排序 |
admin_url | 后台入口(推荐,取代 admin_sidebar_links) |
hooks | 钩子名 → 钩子文件相对路径 |
permissions | 权限声明(如 route:admin、system:settings) |
provides | 能力声明(如 ["level"],v1.5.16 起) |
level_priority | 多等级提供者优先级(v1.5.16 起) |
go | 兼容/迁移元数据(schema 版本、资源、设置项、别名等) |
9.3 加载与生命周期
Plugin::init()读取plugins/plugins_cache.json;- 缓存失效时扫描各插件
plugin.json重建; - 按
sort_order+ 目录名稳定排序; hook()首次调用时构建"钩子 → 文件"索引;- 启用插件后可在后台执行"刷新插件"重新载入。
生命周期约定(详见插件规范第 4.1 节):
启用 activate → 每请求 init_after → 路由注册 → 钩子渲染
→ 业务钩子 → 停用 deactivate → 卸载 uninstall(删除 data/)
9.4 钩子机制
关键实现细节:
- 钩子文件在独立闭包作用域中
include,参数通过extract()注入; - 声明了全局函数/类/接口/trait 的钩子文件只
include_once,避免Cannot redeclare; - 未声明符号的钩子文件每次调用都执行;
- 每个钩子文件外层包
ob_start():抛错时丢弃半截 HTML,页面只缺一块,不变形; - 单插件异常只记日志与健康指纹,不阻断其他插件;
init_after有 60 秒聚合戳门控(data/runtime/init_after.<指纹>.ok);admin_route_register未声明route:admin时,强制模式下拒绝分发;- 钩子文件路径经
realpath校验必须位于插件目录内。
9.5 核心钩子分类清单(53 个核心钩子 + 5 个插件侧扩展点)
A. 应用与路由生命周期
| # | 钩子 | 时机 |
|---|---|---|
| 1 | init_after | 应用初始化完成(惰性建表兜底,60s 聚合戳) |
| 2 | route_register | 注册前台路由 |
| 3 | route_before_dispatch | 分发前全局拦截(一次请求触发两次) |
| 4 | route_after_dispatch | 分发完成、响应输出后(异步收尾) |
| 5 | admin_route_register | 注册后台路由(需 route:admin) |
B. 视图渲染与布局
| # | 钩子 | 时机 |
|---|---|---|
| 6 | controller_view_before | 视图渲染前(可改 $data) |
| 7 | layout_head_end | </head> 前 |
| 8 | nav_main_links | 主导航 |
| 9 | nav_plugin_links | 左栏"应用"面板 + 顶部"应用"下拉(双触发) |
| 10 | nav_user_menu_items | 用户下拉(PC / 移动) |
| 11 | nav_drawer_links | 移动端抽屉 |
| 12 | footer_links | 页脚链接区 |
| 13 | admin_sidebar_links | 后台侧边栏(新插件不推荐) |
| 14 | right_sidebar_after | 列表页右栏用户面板之后 |
| 15 | sidebar_above_friend_links | 友链上方(PC 右栏 + 移动侧栏) |
| 16 | home_sidebar_bottom | 侧栏底部 |
| 42 | right_sidebar_user_actions_above | 右栏用户面板内部(登录态) |
| 43 | layout_body_end | </body> 前(全站,含后台) |
| 51 | right_sidebar_detail_after | 详情页右栏专用 |
| 52 | rewrite_rules_collect | 后台伪静态规则扩展 |
| 53 | left_sidebar_modules | PC 左栏"应用"面板之前 |
| 54 | sidebar_stats_extra | 站点统计面板追加行 |
| 57 | admin_dashboard_cards | 后台仪表盘统计卡片 |
C. 内容展示
| # | 钩子 | 时机 |
|---|---|---|
| 17 | announcements_display | 列表页公告区 |
| 18 | thread_redpacket_area | 主帖内嵌区 |
| 19 | thread_operation_after | 帖子详情操作区 |
| 20 | post_operation_after | 每层回复操作区 |
| 21 | post_report_button | 回复举报按钮区 |
| 22 | post_create_extra | 发帖表单附加区 |
| 23 | blog_detail_operation_after | 博客详情操作区(插件视图) |
| 24 | blog_comment_operation_after | 博客评论操作区(插件视图) |
| 25 | profile_user_card_after | 他人主页用户卡之后(插件视图) |
| 41 | thread_show_top | 详情页顶部提示区 |
| 55 | profile_sections | 个人中心页尾 |
| 58 | user_profile_header | 核心兜底版个人主页资料区 |
D. 写操作后置事件
| # | 钩子 | 时机 |
|---|---|---|
| 26 | auth_login_check | 密码通过、写 Session 前 |
| 27 | auth_login_after | 登录成功 |
| 28 | auth_register_before | 注册提交前 |
| 29 | auth_register_after | 注册成功 |
| 30 | avatar_upload_after | 头像上传后 |
| 31 | thread_create_after | 发帖成功(事务已提交) |
| 32 | post_create_after | 回帖成功(事务外) |
| 33 | thread_edit_after | 主题编辑后 |
| 34 | post_edit_after | 回复编辑后 |
| 35 | vote_after | 投票 / 点赞后 |
| 36 | attachment_download_before | 附件下载前 |
| 37 | points_award_after | 积分增加后 |
| 38 | points_deduct_after | 积分扣除后 |
| 56 | user_delete_before | 后台删除用户前 |
E. 插件自定义扩展点
全表 58 行中,有 5 个触发点在插件侧:#23 / #24 / #25(插件视图内触发)与本组的 #39 / #40。
| # | 钩子 | 触发方 |
|---|---|---|
| 39 | points_mall_medal_redeem | points_mall 插件 |
| 40 | ai_assistant_content_filter | ai_assistant 插件 |
F. 其他
| # | 钩子 | 时机 |
|---|---|---|
| 44 | mail_send_before | 发信驱动前(可接管) |
| 45 | upload_url | 每个上传 URL(高频,禁止查库) |
| 46 | upload_thumb_url | 缩略图 URL 改写 |
| 47 | upload_after | 文件落盘后 |
| 48 | auth_register_form_extra | 注册表单内 |
| 49 | auth_login_form_extra | 登录表单内 |
| 50 | thread_reply_form_extra | 回复表单内 |
完整参数、触发锚点与陷阱见 docs/插件开发规范.md 第 9 章。
9.6 插件独立数据库
// 获取插件独立库:plugins/{name}/data/{name}.sqlite
$pdo = \app\Helpers\Plugin::db('my_plugin');
// 幂等建表(带令牌门控,DDL 不变时不建连、不执行)
\app\Helpers\Plugin::ensureSchema('my_plugin', 'CREATE TABLE IF NOT EXISTS ...');
约束:
- 插件库与业务库物理隔离;
- 插件名必须匹配
^[A-Za-z0-9_\-]{1,64}$; data/自动生成 Apache / IIS 防护文件;- 跨插件写操作不属于同一事务。
9.7 权限、入口与健康
| 机制 | 说明 |
|---|---|
| 权限声明 | plugin.json.permissions,如 route:admin、system:settings |
| 权限模式 | 警告模式(记录并放行)/ 强制模式(拒绝分发) |
| 入口开关 | 后台按插件、按钩子入口粒度启停,状态存 settings |
| 故障健康 | 钩子异常记录指纹;基础设施类异常豁免;后台可"消黄" |
| 自动降级 | 单钩子异常不影响页面其他部分 |
9.8 跨站插件市场
FlintHub 内置插件市场双角色:
| 角色 | 职责 |
|---|---|
hub | 托管插件清单、包体、截图、投稿;包体经 /api/market/download 鉴权流式下发 |
client | 本地缓存清单(TTL 6h)、安装/升级编排、Token 本地存取 |
安全约束:
- 同机存在
release/plugins/index.json或data/market/时优先本地,不发网络请求; - 包体不放静态可读目录;
- Token 存
data/(公网不可读),Linux 下0600。
9.9 插件开发红线(摘要)
详见 docs/插件开发规范.md:
- 文件操作必须
basename,禁止路径拼接落盘; - SQL 必须预处理,
IN (...)必须强转 + 占位符; - 入库/出库字符串必须转义或
strip_tags; - 禁止反序列化与动态执行;
- 上传必须白名单 + 随机文件名;
- 数量扣减必须原子更新;
- AJAX 必须带 CSRF Token;
- 渲染钩子禁止
die()/exit()/header(); - 插件命名空间首段必须逐字节等于目录名;
- 插件前台路由不得与站点根真实文件/目录同名。
10. 后台管理
后台入口 /admin,所有后台控制器继承 Admin\BaseController,构造函数执行:
- 管理员身份校验,未登录跳
/login; - 二次验证校验(
admin_verified_at,超时 60s ~ 7 天),未验证跳/admin/verify。
10.1 模块清单
| 模块 | 路由 | 职责 |
|---|---|---|
| 仪表盘 | /admin | 统计、环境信息、密钥加固告警、插件卡片 |
| 数据库 | /admin/database、/engine、/overview、/settings | SplitDB 概览、引擎设置、维护 |
| 站点设置 | /admin/settings、/basic、/system、/display、/mail、/search、/queue、/pwa | 全部站点配置 |
| 伪静态检测 | /admin/settings/test-rewrite | 服务端实测探针 |
| 用户 | /admin/users | 用户管理、编辑、封禁 |
| 帖子管理 | /admin/threads、/threads/{id} | 主题管理、编辑、移动、删除 |
| 版块 | /admin/categories | 版块 CRUD、排序 |
| 标签 | /admin/tags | 标签管理 |
| 用户组 / 权限 | /admin/groups、/admin/permissions | 用户组与版块权限矩阵 |
| 等级 | /admin/levels | 积分等级配置、当前等级体系只读状态 |
| 验证 | /admin/verify | 管理员二次验证 |
| 维护 | /admin/maintenance | 缓存清理、索引重建、维护操作 |
| 回收站 | /admin/trashed | 软删内容恢复/彻底删除 |
| 审计日志 | /admin/logs/audit | 操作审计 |
| 插件 | /admin/plugins、/edit/{name}、activate、deactivate、uninstall、entries/{name}、health/clear | 插件生命周期、入口开关、健康 |
| 在线升级 | /admin/update、check、preflight、fetch、backup、apply、rollback、state、reset-state、prune-packages、ignore、unignore | 核心升级全流程 |
| 插件市场 | /admin/market、sync、callback、install、activate、auth-start、auth-clear、selfcheck、prune | 跨站插件市场 |
10.2 后台约束
- 后台页面不套用前台主题覆盖层;
- 后台响应
Cache-Control: no-store; - 后台弹层 markup 必须位于
<main class="admin-content">内; - 后台 Tab 复用核心
.admin-tabs,不要自造; - 插件后台路由不要重复写
/admin前缀。
11. 安全体系
11.1 认证与账户
| 机制 | 实现 |
|---|---|
| 密码存储 | password_hash()(bcrypt/argon 由 PHP 决定) |
| 密码策略 | 长度 ≥ 8,至少一个字母 + 一个数字;模型层再次断言 |
| 登录防爆破 | PoW 工作量证明为主 + 图形验证码兜底 |
| 登录锁定 | LoginThrottle,失败计数存 protected/rate_cache/ |
| 记住我 | RememberMe,Token 校验 + 轮换 |
| 邮箱验证 | Token + 过期时间 |
| 密码重置 | 一次性 Token + 过期 + used 标记 |
| 管理员二次验证 | admin_verified_at,超时 60s ~ 7 天 |
11.2 请求安全
| 机制 | 实现 |
|---|---|
| SQL 注入 | 全量参数化;ORDER BY 白名单清洗 |
| CSRF | Csrf::token() + hash_equals 一次性消费;CsrfGate 在路由命中后统一守卫 |
| XSS | 模板默认转义;Content::sanitizeHtml() 白名单净化;缺 DOMDocument 时降级纯文本 |
| 开放重定向 | 仅允许单个 / 开头的同站相对路径,拒绝 // 与反斜杠 |
| 点击劫持 | 安全响应头(CSP / frame 限制) |
| MIME 嗅探 | X-Content-Type-Options: nosniff |
| 数组参数攻击 | $_GET 非标量项在入口剥离 |
11.3 上传安全
- 扩展名白名单;
- MIME 检测(
fileinfo); - 文件大小上限(
MAX_FILE_SIZE); - 上传目录禁止 PHP 执行;
- 图片重采样/缩略图;
- 上传 URL 可经
upload_url钩子切换到对象存储。
11.4 权限与越权
- 用户组 + 版块权限矩阵(
user_groups/category_permissions); - 前台
requireLogin()/requireAdmin(); - 后台
BaseController三重门禁(登录 + 管理员 + 二次验证); - 附件下载跟随版块
can_view; - 插件权限声明 + 强制模式。
11.5 敏感目录与文件
| 路径 | 防护 |
|---|---|
data/ | Apache .htaccess + IIS web.config + Nginx deny;初始化时校验防护文件完整性 |
protected/ | 同上 |
cli/ | Apache 拒绝直访 |
plugins/*/data/ | 自动生成防护文件 |
assets/uploads/ | 禁止 PHP 执行 |
| 密钥文件 | 优先环境变量,其次 protected/*_key.php;读文本不执行 |
11.6 密钥治理
MAIL_PASS_KEY/CRON_KEY优先环境变量:FLINTHUB_MAIL_PASS_KEYFLINTHUB_CRON_KEY
- 其次读取
protected/mail_key.php/protected/cron_key.php(纯文本或return '...'); - 仍使用源码默认值时,后台仪表盘显示"未加固"告警;
- SMTP 密码 AES-256-GCM 存储(兼容旧 CBC 密文)。
11.7 审计与日志
audit_logs记录后台关键操作;- 错误统一写
protected/error.log; - SQL 错误只记录真实 SQL 与异常,不向前端泄露;
- 插件钩子异常记录插件名 + 钩子名 + 指纹。
12. 性能与缓存体系
12.1 缓存分层
| 层 | 位置 | 失效方式 | 作用 |
|---|---|---|---|
| 游客页面缓存 | data/runtime/pages/*.html | 发帖/回帖主动失效;按主题/语言/摘要偏好分键 | 命中即输出,跳过框架 |
| 设置缓存 | 内存 → protected/settings_cache.php → DB | 后台保存设置时重建 | 避免每请求查 settings |
| 模板编译缓存 | protected/cache/templates/ | 模板变更/清缓存 | 避免重复编译 |
| 插件建表令牌 | data/runtime/plugin_schema.json | DDL 变化/清缓存/启停插件 | 避免每请求建表 |
| 钩子符号缓存 | data/runtime/hook_symbols.json | 插件变化/清缓存 | 避免每请求读文件正则 |
init_after 聚合戳 | data/runtime/init_after.<fp>.ok | TTL 60s;插件启停/升级/清缓存立即作废 | 把 41 次 include 压成 1 次 filemtime |
| 伪静态探针 | data/runtime/rewrite_probe.json | TTL 120s | 只在后台直连形态实测 |
| 版块统计 | 文件缓存 | 发帖/回帖/移动版块主动失效 | 避免大表 COUNT |
| 浏览量 | APCu | 请求结束批量落库 | 避免每请求写库 |
| 正文读缓存 | APCu | TTL 600s | 减少文件读取 |
12.2 数据库性能设计
- 列表查询使用
topic_index复合索引,LIMIT免排序; - 回复分页使用
(pid, status, create_time, id)组合索引; - 桶 schema 版本写入
user_version,命中跳过 DDL; - ID 取号使用短事务 + 重试;
- 连接池 LRU 8 句柄,禁止持久连接;
- WAL 强制校验,避免网络盘静默回退。
12.3 前端性能
- 静态资源版本化(
?v=); - 页面级 CSS 按需加载;
- 图片缩略图 + 灯箱懒加载;
- htmx 局部刷新(收藏数、摘要展开);
- PWA 缓存静态资源。
13. 多语言、主题、PWA、前端
13.1 多语言
- 语言包:
lang/zh.php、lang/en.php、lang/zh_tw.php; - 插件语言包:
plugins/<name>/lang/*.php,运行时合并,核心键优先; - 探测顺序:Cookie → Session → 后台设置 → 浏览器;
- 缺 key 回退链,永不白屏;
- 切换语言使用
?lang=+ PRG 回跳。
13.2 主题
- 默认主题
modern; - 主题目录:
assets/themes/<theme>/,可覆盖任意前台模板; - 主题元数据:
config.json或style.css头部注释; - 配色:
--mn-*CSS 变量 + 内置配色 + 夜间模式 + 用户自定义 CSS; - 主题切换影响页面缓存键(
_t<theme>)。
13.3 PWA
sw.js:静态资源缓存 + 离线页;/manifest.webmanifest:动态生成,站点名/描述/主题色跟随后台设置;scope与start_url适配伪静态与二级目录;- 后台可关闭 PWA 并注销 Service Worker。
13.4 前端技术
| 技术 | 用途 |
|---|---|
| Alpine.js | 下拉、抽屉、弹层、Tab 状态 |
| htmx | 局部 AJAX(收藏数、摘要展开) |
| editor.js 体系 | 自研编辑器(Markdown / 富文本、粘贴、拖拽上传) |
| marked / turndown | Markdown 渲染与 HTML→Markdown |
| lightbox.js | 图片查看 |
| pow.js | 登录/注册工作量证明 |
| layout.js | 布局偏好、侧栏开关 |
| pwa.js | Service Worker 注册 |
14. CLI 工具与运维
cli/ 下为正式维护工具:
| 工具 | 用途 |
|---|---|
env_check.php | 环境检测 |
migrate.php | 数据迁移 |
migrate_extern_namespace.php | 正文命名空间迁移 |
migrate_extern_to_bin.php | 正文转归档块 |
migrate_notifications_builtin.php | 通知迁移 |
migrate_plugins.php | 插件迁移 |
migrate_search_quarters.php | 搜索索引季度迁移 |
migrate_uploads_by_month.php | 上传按月归档 |
archive.php / archive_mark.php | 冷数据归档 |
rebuild_index.php | 主索引重建 |
rebuild_search.php | 搜索索引重建 |
repair_extern_idx.php | 外置索引修复 |
backfill_excerpts.php | 摘要回填 |
backfill_md_thumbs.php | Markdown 缩略图回填 |
shrink_business.php | 业务库收缩 |
worker.php / worker2.php | 队列常驻消费 |
site_stats_rollup.php | 站点统计汇总 |
seed_content.php | 演示内容生成 |
bench_write.php | 写入基准测试 |
probe_page_cache.php | 页面缓存探针 |
release_build.php | 发行包构建 |
release_keygen.php | 发布签名密钥生成 |
update_probe.php / update_fetch_probe.php | 升级链路探针 |
set_site_lang.php | 站点语言设置 |
user_level_rebuild.php | 用户等级重建 |
plugin_points_relay.php | 插件积分转发 |
运维建议:
- 生产关闭
display_errors; data/与protected/不要暴露到 Web;- 定期备份
data/meta/*.sqlite、data/bucket/、assets/uploads/; - 升级前备份;
- 关注
protected/error.log与data/log/。
15. 在线升级与版本发布
15.1 核心升级流程
检查版本 → 预检(权限/空间/环境)→ 下载包 → 校验签名/哈希
→ 备份 → 计算差异 → 应用(白名单写/删)→ 清理缓存 → 完成
↘ 失败可回滚
纳管范围:
- 白名单目录:
app/、assets/、lang/、cli/、docs/; - 白名单根文件:
index.php、cron_trigger.php、install.php、sw.js、version.php、.htaccess、web.config、nginx-*.conf、README.md、INSTALL.md、CHANGELOG.md、LICENSE等; - 硬黑名单:
config.php、data/、protected/、plugins/、assets/uploads/、assets/themes/、release/、update/、.zip/.bak/.log/.sqlite等。
15.2 插件安装/升级
PluginUpdater:首装 + 升级 + 保留 R8 数据 + 命名空间实测;- 包体校验、解压落地、清单更新;
- 失败保留原插件目录。
15.3 发布物
release/
├── core/ 核心包(flinthub-core-x.y.z.zip + manifest + latest.json)
├── plugins/ 插件市场包与清单
└── submit/ 投稿包
核心包不包含:
config.php;data/;protected/;plugins/;assets/uploads/;- 用户上传与站点运行时数据。
16. 开发约定与常见坑
16.1 编码规范
- UTF-8 without BOM;
- LF 换行;
- 时间统一秒级时间戳(页面展示时格式化);
- PHP ≥ 8.0 兼容,生产已验证 8.4;禁止隐式可空参数;
- SQLite ≥ 3.33 兼容,不使用
RETURNING; - 所有文件访问必须防路径穿越;
- 所有 SQL 必须参数化。
16.2 路径与 URL
| 场景 | 正确做法 |
|---|---|
| 站内页面链接 | Url::to() / $this->url() |
| 静态资源 | Url::base() / $this->asset() |
| 绝对 URL(邮件/二维码) | Url::absolute() / SITE_URL |
| 插件资源 | 必须用 asset(),不能拼 webBase() |
| 目录读写 | 必须 basename + 白名单 + realpath 校验 |
16.3 常见坑
| 坑 | 说明 |
|---|---|
init_after 语义 | v1.5.12 起"最多每 60 秒跑一次",插件周期任务节流必须 ≤ 60s |
| 插件命名空间 | 首段必须逐字节等于目录名,Windows 假通过、Linux 直接 500 |
| 插件路由 | 不得与站点根真实文件/目录同名 |
| 后台路由 | admin_route_register 内不要再写 /admin 前缀 |
| 浏览器缓存 | 游客页统一 private, no-cache,切换主题/语言必须回源 |
| 页面缓存键 | 主题/语言/摘要偏好都会分键,插叙变更需清缓存 |
| 伪静态 | 关闭时全站链接带 /index.php;静态资源不能带入口前缀 |
| CSRF | 所有写操作必须带 Token;AJAX 同样 |
| 编辑器钩子 | 接管核心编辑器需阅读插件规范 11.39 的 14 条约束 |
| 固定定位浮层 | 不要放在 sticky / transform / filter 祖先内 |
| 后台弹层 | markup 必须留在 <main class="admin-content"> 内 |
| 圆角 | 必须走 CSS 变量,禁止硬编码像素 |
| 后台保存 | 字段缺失会被静默写成最小值,表单必须提交完整字段 |
17. 版本记录摘要
完整记录见 CHANGELOG.md。本章只保留与架构/接口相关的高层变更。
| 版本 | 日期 | 关键变更 |
|---|---|---|
| 1.5.16 | 2026-11-18 | 单一等级体系仲裁(provides / level_priority);新增 user_profile_header 钩子;头像角标插槽;插件规范扩容;缺 ext-dom / ext-zip 时 fail-closed 降级 |
| 1.5.15 | 2026-11-13 | 密码策略统一;首装日志清理;data/ 防护校验加强;{php} 整段抹除;二级目录修复 |
| 1.5.14 | 2026-11-11 | PWA manifest scope 修复 |
| 1.5.13 | 2026-11-09 | 插件市场 TLS 传输回退 |
| 1.5.12 | 2026-11-08 | init_after 聚合戳门控(45.3% 提速);插件周期任务节流约束 |
| 1.5.11 | 2026-11-08 | 伪静态判定改服务端实测;开关回显修复;插件静态资源 404 修复 |
| 1.5.10 | 2026-11-08 | 无伪静态站点可用性修复;授权回跳;伪静态安全阀 |
| 1.5.9 | 2026-11-08 | 安全自查收口;登录锁定重构;HTTPS 判定收敛;权限唯一真源 |
| 1.5.8 | 2026-11-07 | 插件内核性能重构;错误隔离;全局 CSRF 门禁(CsrfGate);楼层号稳定 |
| 1.5.0 | 2026-11-05 | 微内核化:博客剥离为插件;安全加固 |
18. 文档地图
| 文档 | 说明 |
|---|---|
| INSTALL.md | 安装、目录权限、Apache / Nginx / IIS 配置、二级目录、维护 |
| CHANGELOG.md | 完整版本变更记录 |
| docs/插件开发规范.md | 插件开发规范:安全红线、钩子全表、目录结构、语言包、主题适配、核心库边界、常见坑 |
| LICENSE | 开源协议(MIT) |
| release/更新日志_1.3.2至1.5.12.md | 历史版本汇总 |
docs/*插件开发方案*.md | 各插件的设计与验收记录(开发参考,非运行依赖) |
19. 只读发布声明
- 按原样提供:本程序以"现状"形式发布(provided "AS IS"),不含任何明示或暗示的保证,包括但不限于适销性、特定用途适用性与不侵权。
- 只读包:本目录用于部署安装与参考阅读。作者不承诺提供技术支持或接受代码合并请求,完整责任条款见 LICENSE。
- 数据免责:
data/(运行时数据)与protected/(运行产物、会话、限流缓存、日志)应在全新安装时由install.php自动重建;发行包本身不携带任何站点运行时数据。 - 无担保与无附随责任:使用者对其部署、配置、使用及由此产生的任何直接/间接损失自负责任,作者与维护者不承担任何赔偿责任。
- SECURITY / BUG 致谢:欢迎在合规前提下反馈问题,但修复与迭代不构成对本"只读发布声明"的修改。
FlintHub — 用最少的资源,承载最大的社区。 A lightweight PHP community system powered by SplitDB, the sharded SQLite storage engine.