[程序发布] FlintHub 1.5.16 · 技术手册(README)

2026-11-20 13:28:57

燧石论坛(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 与代码版本一一对应:

  1. 版本号只允许在 version.php 中修改,README / CHANGELOG / 安装器全部读取同一常量;
  2. 每次发版必须同步更新本文档的以下位置:
    • 文件头"当前版本 / 对应代码日期";
    • 第 17 章"版本记录摘要"新增一条;
    • 若新增/删除核心路由、钩子、数据表、CLI 工具,必须同步更新对应附录;
  3. 文档中涉及行号的位置一律只作参考,以文件 + 锚点描述为准(代码会漂移,锚点不会);
  4. 本 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
PDOpdo + 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 全新安装

  1. 上传核心包到站点根目录(或子目录);
  2. 配置伪静态:
    • Apache:使用随包 .htaccess,确保 AllowOverride FileInfo;
    • Nginx:使用 nginx-server.conf / nginx-baota.conf;
    • IIS:使用 web.config;
  3. 浏览器访问 install.php:
    • 第 1 步:环境检测(PHP / PDO SQLite / SQLite 版本 / 扩展 / 目录可写 / zip / dom);
    • 第 2 步:Schema::bootstrap() 初始化 SplitDB(建目录树、建库建表、写防护文件);
    • 第 3 步:创建管理员;
  4. 完成后生成 protected/.install_done,再次访问安装器会被拒绝;
  5. 登录 /admin 配置站点。

详细步骤见 INSTALL.md。

3.2 升级

两种方式:

  • 后台在线升级:/admin/update,流程为"检查 → 预检 → 取包 → 校验 → 备份 → 应用 → 回滚";
  • 完整包覆盖:解压覆盖程序目录,保留 data/、protected/、assets/uploads/、plugins/,随后清理前台页面缓存。

在线升级的纳管范围有硬黑名单:config.php、data/、protected/、plugins/、assets/uploads/、assets/themes/、release/ 等永不覆盖、永不删除。

3.3 二级目录部署

  1. 安装器会按实际子目录写入 BASE_PATH 与 UPLOAD_URL;
  2. 手工部署时在 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(Header X-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 为例:

  1. Web 服务器:真实文件直接返回;动态路径按伪静态规则转发到 index.php;
  2. 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 到干净地址;
  3. 前置缓存判定:纯游客或"有会话但未登录"的游客,且路径属于首页/论坛/版块 → 读取 data/runtime/pages/*.html,命中直接输出并退出(跳过 Session / DB / 插件);
  4. app/init.php:
    • 注册自动加载;
    • 加载 config.php(常量、Session 参数、SITE_URL);
    • 使用 SessionHandler(sessions.sqlite)启动 Session;
    • 处理 ?lang= 切换(PRG 回跳);
    • RememberMe::check() 自动登录;
    • 更新在线状态;
    • 创建 TemplateCompiler 全局实例;
    • Plugin::init() 加载插件清单;
    • 触发 init_after(有 60 秒聚合戳门控);
    • 维护模式检查;
  5. 路由注册:前台路由 → /admin 分组 → /api 分组 → route_register → /u/{id} 兜底 → route_before_dispatch;
  6. Router::dispatch():
    • 归一化 URI(剥离 BASE_PATH 与 /index.php,支持 ?r=);
    • 触发一次无参 route_before_dispatch(封禁拦截);
    • 按注册顺序匹配方法与正则;
    • 命中后先过 CsrfGate::guard(),再实例化控制器并调用动作;
    • 未命中输出 404(Cache-Control: no-store);
  7. 控制器:
    • requireLogin() / requireAdmin() 等门禁;
    • 调用 Model / SplitDB 读取数据;
    • Controller::view() 合并默认数据(当前用户、未读数、主题、CSRF、渲染耗时)→ 触发 controller_view_before → 渲染模板;
  8. 模板:
    • TemplateCompiler 先查 assets/themes/<当前主题>/ 覆盖层,再查 app/Views/;
    • 编译为 PHP 并缓存到 protected/cache/templates/;
    • 布局 main 通过 {section} / {yield} 组合页面;
  9. 输出:安全头(SecurityHeaders)+ 分级缓存头;请求结束回调批量刷计数器与浏览量;
  10. 收尾: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

顺序固定,不可随意调整:

  1. 自动加载;
  2. 加载配置;
  3. Session 存储(sessions.sqlite,失败回退文件);
  4. session_start();
  5. i18n 初始化(?lang= 切换 + 预热);
  6. 自动登录 + 在线状态;
  7. 模板引擎实例;
  8. Plugin::init();
  9. init_after 钩子(聚合戳门控);
  10. BASE_PATH 兜底(仅当未定义);
  11. 维护模式拦截(管理员 / 登录 / 注册 / 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.sqliteusers、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.sqlitethreads、posts过渡期兼容表,分片后退役,新数据写桶
main_index.sqlitetopic_index主题主索引:列表排序字段、统计、bucket_path、摘要
main_index.sqlitereply_index回复定位索引:pid、uid、bucket_path
sessions.sqlitesessions会话,独立写锁
global_id.sqliteid_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_timeout10000ms
journal_modeWAL(强制校验,非 WAL 拒绝使用)
synchronousNORMAL
cache_size-20000(约 20MB)
temp_storeMEMORY
foreign_keysOFF(分片架构下跨库外键不成立,删除由业务层显式清理)
事务保护淘汰前检测 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 模板查找顺序

  1. assets/themes/<当前主题>/<template>.php;
  2. assets/themes/<当前主题>/<template>.html;
  3. 插件模板:plugins/<id>/views/<rest>.php|.html(当模板名以 plugins/ 开头);
  4. app/Views/<template>.php;
  5. 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 加载与生命周期

  1. Plugin::init() 读取 plugins/plugins_cache.json;
  2. 缓存失效时扫描各插件 plugin.json 重建;
  3. 按 sort_order + 目录名稳定排序;
  4. hook() 首次调用时构建"钩子 → 文件"索引;
  5. 启用插件后可在后台执行"刷新插件"重新载入。

生命周期约定(详见插件规范第 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. 应用与路由生命周期

#钩子时机
1init_after应用初始化完成(惰性建表兜底,60s 聚合戳)
2route_register注册前台路由
3route_before_dispatch分发前全局拦截(一次请求触发两次)
4route_after_dispatch分发完成、响应输出后(异步收尾)
5admin_route_register注册后台路由(需 route:admin)

B. 视图渲染与布局

#钩子时机
6controller_view_before视图渲染前(可改 $data)
7layout_head_end</head> 前
8nav_main_links主导航
9nav_plugin_links左栏"应用"面板 + 顶部"应用"下拉(双触发)
10nav_user_menu_items用户下拉(PC / 移动)
11nav_drawer_links移动端抽屉
12footer_links页脚链接区
13admin_sidebar_links后台侧边栏(新插件不推荐)
14right_sidebar_after列表页右栏用户面板之后
15sidebar_above_friend_links友链上方(PC 右栏 + 移动侧栏)
16home_sidebar_bottom侧栏底部
42right_sidebar_user_actions_above右栏用户面板内部(登录态)
43layout_body_end</body> 前(全站,含后台)
51right_sidebar_detail_after详情页右栏专用
52rewrite_rules_collect后台伪静态规则扩展
53left_sidebar_modulesPC 左栏"应用"面板之前
54sidebar_stats_extra站点统计面板追加行
57admin_dashboard_cards后台仪表盘统计卡片

C. 内容展示

#钩子时机
17announcements_display列表页公告区
18thread_redpacket_area主帖内嵌区
19thread_operation_after帖子详情操作区
20post_operation_after每层回复操作区
21post_report_button回复举报按钮区
22post_create_extra发帖表单附加区
23blog_detail_operation_after博客详情操作区(插件视图)
24blog_comment_operation_after博客评论操作区(插件视图)
25profile_user_card_after他人主页用户卡之后(插件视图)
41thread_show_top详情页顶部提示区
55profile_sections个人中心页尾
58user_profile_header核心兜底版个人主页资料区

D. 写操作后置事件

#钩子时机
26auth_login_check密码通过、写 Session 前
27auth_login_after登录成功
28auth_register_before注册提交前
29auth_register_after注册成功
30avatar_upload_after头像上传后
31thread_create_after发帖成功(事务已提交)
32post_create_after回帖成功(事务外)
33thread_edit_after主题编辑后
34post_edit_after回复编辑后
35vote_after投票 / 点赞后
36attachment_download_before附件下载前
37points_award_after积分增加后
38points_deduct_after积分扣除后
56user_delete_before后台删除用户前

E. 插件自定义扩展点

全表 58 行中,有 5 个触发点在插件侧:#23 / #24 / #25(插件视图内触发)与本组的 #39 / #40。

#钩子触发方
39points_mall_medal_redeempoints_mall 插件
40ai_assistant_content_filterai_assistant 插件

F. 其他

#钩子时机
44mail_send_before发信驱动前(可接管)
45upload_url每个上传 URL(高频,禁止查库)
46upload_thumb_url缩略图 URL 改写
47upload_after文件落盘后
48auth_register_form_extra注册表单内
49auth_login_form_extra登录表单内
50thread_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,构造函数执行:

  1. 管理员身份校验,未登录跳 /login;
  2. 二次验证校验(admin_verified_at,超时 60s ~ 7 天),未验证跳 /admin/verify。

10.1 模块清单

模块路由职责
仪表盘/admin统计、环境信息、密钥加固告警、插件卡片
数据库/admin/database、/engine、/overview、/settingsSplitDB 概览、引擎设置、维护
站点设置/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 白名单清洗
CSRFCsrf::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_KEY
    • FLINTHUB_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.jsonDDL 变化/清缓存/启停插件避免每请求建表
钩子符号缓存data/runtime/hook_symbols.json插件变化/清缓存避免每请求读文件正则
init_after 聚合戳data/runtime/init_after.<fp>.okTTL 60s;插件启停/升级/清缓存立即作废把 41 次 include 压成 1 次 filemtime
伪静态探针data/runtime/rewrite_probe.jsonTTL 120s只在后台直连形态实测
版块统计文件缓存发帖/回帖/移动版块主动失效避免大表 COUNT
浏览量APCu请求结束批量落库避免每请求写库
正文读缓存APCuTTL 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 / turndownMarkdown 渲染与 HTML→Markdown
lightbox.js图片查看
pow.js登录/注册工作量证明
layout.js布局偏好、侧栏开关
pwa.jsService 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.phpMarkdown 缩略图回填
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.162026-11-18单一等级体系仲裁(provides / level_priority);新增 user_profile_header 钩子;头像角标插槽;插件规范扩容;缺 ext-dom / ext-zip 时 fail-closed 降级
1.5.152026-11-13密码策略统一;首装日志清理;data/ 防护校验加强;{php} 整段抹除;二级目录修复
1.5.142026-11-11PWA manifest scope 修复
1.5.132026-11-09插件市场 TLS 传输回退
1.5.122026-11-08init_after 聚合戳门控(45.3% 提速);插件周期任务节流约束
1.5.112026-11-08伪静态判定改服务端实测;开关回显修复;插件静态资源 404 修复
1.5.102026-11-08无伪静态站点可用性修复;授权回跳;伪静态安全阀
1.5.92026-11-08安全自查收口;登录锁定重构;HTTPS 判定收敛;权限唯一真源
1.5.82026-11-07插件内核性能重构;错误隔离;全局 CSRF 门禁(CsrfGate);楼层号稳定
1.5.02026-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. 只读发布声明

  1. 按原样提供:本程序以"现状"形式发布(provided "AS IS"),不含任何明示或暗示的保证,包括但不限于适销性、特定用途适用性与不侵权。
  2. 只读包:本目录用于部署安装与参考阅读。作者不承诺提供技术支持或接受代码合并请求,完整责任条款见 LICENSE。
  3. 数据免责:data/(运行时数据)与 protected/(运行产物、会话、限流缓存、日志)应在全新安装时由 install.php 自动重建;发行包本身不携带任何站点运行时数据。
  4. 无担保与无附随责任:使用者对其部署、配置、使用及由此产生的任何直接/间接损失自负责任,作者与维护者不承担任何赔偿责任。
  5. SECURITY / BUG 致谢:欢迎在合规前提下反馈问题,但修复与迭代不构成对本"只读发布声明"的修改。

FlintHub — 用最少的资源,承载最大的社区。 A lightweight PHP community system powered by SplitDB, the sharded SQLite storage engine.

轻量级、高性能、零 MySQL 依赖的PHP社区系统。
| 瀏覽 16 次 | 回覆 1 次

全部回覆 (1)

2026-11-20 19:33:47
版本单一源那条建议再加一道自动校验:发版脚本读 version.php 后,顺手核对 README 头部、第 17 章条目与附录里的路由/钩子/表清单是否都改过,缺一项就让构建失败,靠人记同步点最容易在第五次发版后失效。另外分片扩容从 32 到 64 时,建议把「旧桶只会拆成原桶与 +32 兄弟」这条映射写进文档,历史文件零迁移的前提才成立,查询路由也知道先定旧桶再找子桶。
#1 樓

請 登入