本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：8月13日备份/说明.md。
SoSite 程序介绍
轻量级 PHP 社区系统（论坛 + 博客 + 站内信 + 私信 + 插件生态）
版本：V5.0.0 ｜ 架构：自研 MVC + 单模板体系（Modern） ｜ 语言：PHP 8.2 / MySQL 5.7.26 / SQLite
运行环境：phpstudy（Nginx + PHP 8.2.9 + MySQL 5.7.26）｜ 零 Composer 依赖，开箱即用
一、目录结构图（V5.0.0 最新）
D:/phpstudy_pro/WWW # 站点根目录
├── index.php # 前端控制器（路由分发入口，兼容旧 .php 直访）
├── install.php # 安装向导（全新环境自动建库/建表/建管理员；config.php 缺失自动生成）
├── config.php # 全局配置（数据库/邮件/主题/安全/Session/版本号）
├── favicon.ico / favicon.svg / logo.svg # 站点图标
│
├── sosite-plugin-dev/ # ★ 插件开发 Skill/Rule 包（SKILL.md + references/ + plugin-system.md）
├── SoSite-插件仓库开发计划.md # 插件仓库功能开发计划（P0~P4 分期）
│
├── app/ # ★ 应用核心（自研框架）
│ ├── init.php # 应用初始化（自动加载/配置/Session/插件/维护模式）
│ ├── Core/ # ── 自研 MVC 框架内核（6 个文件）──
│ │ ├── Autoloader.php # PSR-4 风格自动加载
│ │ ├── Router.php # 路由引擎（GET/POST/ANY/分组/参数正则提取）
│ │ ├── Controller.php # 控制器基类（视图渲染/重定向/JSON/权限助手）
│ │ ├── Model.php # 模型基类（CRUD/分页/排序白名单/动态 Where）
│ │ ├── Database.php # PDO 封装（预处理/事务/独立 Session 连接）
│ │ └── TemplateCompiler.php # 模板引擎（编译/缓存/安全转义 e()/区块 section）
│ ├── Controllers/ # ── 前台控制器（12 个）──
│ │ ├── HomeController.php # 首页聚合（社区+博客+在线+标签）
│ │ ├── ForumController.php # 论坛版块（分类/权限过滤/置顶高亮）
│ │ ├── ThreadController.php # 帖子（浏览/回复/编辑/删除/附件/置顶高亮）
│ │ ├── PostController.php # 回复/新帖（含限流）
│ │ ├── AuthController.php # 登录/注册/找回密码/邮箱验证
│ │ ├── ProfileController.php # 个人中心（资料/头像/改密）
│ │ ├── MessageController.php # 站内私信（收/发/详情/删除）
│ │ ├── BlogController.php # 博客（列表/详情/分类/评论）
│ │ ├── SearchController.php # 全文搜索（倒排索引）
│ │ ├── TagsController.php # 标签（列表/聚合页）
│ │ ├── ThemeController.php # 主题切换
│ │ ├── ApiController.php # API（投票/上传/远程拉图/验证码）
│ │ └── Admin/ # ── 后台控制器（16 个）──
│ │ ├── BaseController.php # 后台基类（isAdmin + 二次验证强制）
│ │ ├── DashboardController.php # 控制台
│ │ ├── UserController.php # 用户管理
│ │ ├── ThreadController.php # 帖子管理
│ │ ├── CategoryController.php # 版块管理
│ │ ├── BlogController.php # 博客管理
│ │ ├── TagController.php # 标签管理
│ │ ├── LevelController.php # 等级管理
│ │ ├── GroupController.php # 用户组管理
│ │ ├── ThemeController.php # 主题管理
│ │ ├── SettingsController.php # 站点/显示/邮件/搜索设置
│ │ ├── DatabaseController.php # 数据库备份/优化/导入
│ │ ├── MaintenanceController.php # 维护工具（缓存/计数器重建/清理）
│ │ ├── TrashedController.php # 回收站
│ │ ├── PluginController.php # 插件管理
│ │ └── VerifyController.php # 二次验证页
│ ├── Helpers/ # ── 自研工具库（19 个）──
│ │ ├── Auth.php # 登录态/管理员判定/当前用户缓存
│ │ ├── Permission.php # 版块权限体系（组×版块矩阵）
│ │ ├── Csrf.php # CSRF Token 生成/校验
│ │ ├── Captcha.php # 自研图片验证码（弧线+噪点）
│ │ ├── RateLimiter.php # 文件/IP 级限流器（登录/发帖/评论全覆盖）
│ │ ├── RememberMe.php # 记住登录（Token 轮换 + SHA-256 哈希）
│ │ ├── Content.php # 富文本 base64 解码 + HTML 净化白名单
│ │ ├── Emoji.php # QQ 表情解析
│ │ ├── Segmenter.php # 中文二元分词器（bigram，纯 PHP）
│ │ ├── Search.php # 倒排索引全文检索（自研）
│ │ ├── Settings.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 # 单模板主布局（三栏骨架，前台/后台共用）
│ ├── _components/ # 侧边栏组件（left/middle/right 三栏）
│ ├── errors/404.php # 通用 404 页面
│ ├── home/ forum/ thread/ post/ blog/ tags/ search/
│ ├── auth/ # 登录/注册/找回密码/邮箱验证
│ ├── message/ # 私信收/发/详情（4 视图）
│ ├── profile/ theme/ # 个人中心/主题设置
│ └── admin/ # 后台 23 个视图
│
├── assets/ # 静态资源
│ ├── css/
│ │ ├── modern.css # ★ 主题基座（唯一基座，含 --mn-* 变量体系）
│ │ ├── components.css # 通用组件+工具类（灯箱/分页/按钮/工具类）
│ │ ├── admin.css # 后台独立样式（--c-* 变量 + 作用域前缀）
│ │ ├── editor.css # 编辑器样式
│ │ ├── style.css # 基础核心（重置/通用工具类）
│ │ ├── fontawesome.css # 图标字体
│ │ └── themes/ # 5 个配色变体（azure/crimson/jade/night/purple）
│ ├── js/
│ │ ├── editor.js # ★ 自研富文本编辑器（contenteditable v3.0）
│ │ ├── thread.js # 帖子页脚本（灯箱滚轮/手势缩放）
│ │ ├── auth.js / script.js
│ │ └── marked.min.js / turndown.js # Markdown 转换（第三方）
│ ├── lib/
│ │ ├── sostate.js # SoState 状态管理（Alpine.js 定制，原名 alpine.min.js）
│ │ ├── soajax.js # SoAjax AJAX（htmx 定制，原名 htmx.min.js）
│ │ └── qrcode.min.js # 二维码（第三方）
│ ├── img/emoji/qq/ fonts/ plugins/ themes/ uploads/
│
├── plugins/ # ★ 插件目录（14 个插件，目录即插件）
│ ├── announcements/ # 公告
│ ├── content_review/ # 内容审核（多钩子深度集成）
│ ├── daily_checkin/ # 每日签到
│ ├── dice/ # 掷骰子
│ ├── edit_info/ # 编辑信息辅助
│ ├── friend_links/ # 友链
│ ├── icon_generator/ # 图标生成器
│ ├── invite/ # 邀请码注册
│ ├── post_favorite/ # 帖子收藏
│ ├── qa/ # 问答
│ ├── quiz_duel/ # 答题对战（积分对赌）
│ ├── red_packet/ # 红包
│ ├── seo/ # SEO 优化
│ ├── user_profile/ # 用户主页
│ └── plugins_cache.php # 插件扫描缓存（var_export 生成，json_decode 读取）
│
│ # 每个插件目录内部结构（A+ 规则：视图/资源全部在插件目录内，app/Views/plugins 已移除）：
│ # plugins/{id}/plugin.json 插件清单（name/version/activated/hooks）
│ # plugins/{id}/Plugin.php 生命周期（activate/deactivate/uninstall，可选）
│ # plugins/{id}/hook/*.php 钩子文件（plugin.json hooks 映射）
│ # plugins/{id}/views/*.php 视图模板（view('plugins/xxx/yyy') 解析到此处）
│ # plugins/{id}/assets/* 静态资源（页面直接 /plugins/{id}/assets/... 引用）
│
└── protected/ # 受保护数据（不可直接访问）
├── database/schema.sql # 建库脚本（现行唯一）
├── sessions/ # Session 存储（文件模式回退）
├── cache/ # 模板编译缓存/计数缓存
├── rate_cache/ # 限流器 IP 记录
├── backups/ # 数据库备份
├── error.log # 错误日志
└── settings_cache.php # 站点设置缓存V5.0.0 结构精简说明：旧模板 CSS（forum/pages/layout/blog.css）已全部下线，CSS 收敛为
modern.css（唯一基座）+components.css（组件工具类）+admin.css（后台作用域）三件套；孤儿视图/脚本（admin/settings.php、rebuild_runtime.php 等）已清理；新增errors/404.php通用错误页。
二、程序特点
2.1 整体定位
- 极致轻量：核心 PHP 代码约 9500 行，零 Composer 依赖（Alpine/htmx/marked 为静态文件引入），单文件部署即可运行
- 单模板体系：前台/后台共用
layouts/main.php三栏骨架，Modern 主题 +--mn-*CSS 变量 + 5 个配色变体热切换 - 全栈自研：路由、模板编译、ORM、Session、中文分词、倒排索引、富文本编辑器、验证码、限流器、插件系统全部自研，不依赖任何重量级框架
- 插件化：14 个功能插件通过钩子机制注入，可独立启停，互不干扰
2.2 安全特性（自研安全体系）
- SQL 注入：全库 PDO 预处理 +
ATTR_EMULATE_PREPARES=false，IN/LIMIT 均显式强转，排序白名单 - XSS：模板引擎
e()全量转义 + 富文本 HTML 净化白名单（标签/属性双重校验） - CSRF：全局 Token 生成/校验，所有写操作（含后台 15 个控制器）全覆盖
- 上传安全：扩展名 + finfo MIME 双白名单、16 字节随机文件名、Imagick/GD 缩略图、5000px 像素炸弹拒绝
- SSRF 防护：远程拉图协议校验 + 内网段封禁 + DNS 解析后真实 IP 校验 + IP 直连防重绑定
- 会话加固：HttpOnly / SameSite=Lax / Strict Mode / 数据库化 Session / 独立连接 / 定期 GC
- 认证加固：
Auth::isAdmin数据库双重确认（role=admin 且 group_id=4）、后台敏感操作 30 分钟二次验证、审计日志全记录 - 暴力破解防护：登录用户名级锁定（5 次/15 分钟）+ 验证码 + 注册/找回限流
2.3 功能矩阵
| 模块 | 能力 |
|---|---|
| 论坛 | 版块分类、帖子置顶/高亮、回复可见、回收站、点赞点踩、附件 |
| 博客 | 分类、封面图、评论分页、倒排索引收录 |
| 会员 | 注册登录（邮箱验证）、积分等级徽章、用户组权限矩阵、邀请码 |
| 私信 | 收/发/详情/删除、未读数、防越权校验 |
| 搜索 | 自研倒排索引全文检索（中文 bigram 分词，帖子/博客/用户） |
| 社区 | 标签云、QQ 表情、灯箱（滚轮/手势缩放）、主题切换 |
| 插件 | 公告/签到/骰子/友链/问答/答题对战/红包/收藏/审核/SEO/主页 等 14 个 |
| 后台 | 用户/帖子/博客/分类/等级/用户组/主题/插件/数据库/维护 全管理 |
三、自研模块详解（重点）
3.1 自研 MVC 框架内核（app/Core）
| 模块 | 文件 | 说明 |
|---|---|---|
| 路由引擎 | Router.php | {param} 正则提取、GET/POST/ANY、分组前缀、钩子可扩展 |
| 模板引擎 | TemplateCompiler.php | 编译+缓存视图；e() 自动转义、section/yield 区块、icon/url/asset 视图助手 |
| 数据库层 | Database.php | PDO 预处理封装；业务/会话双连接隔离；事务便捷方法；查询计数 |
| 模型基类 | Model.php | 通用 CRUD、分页、sanitizeOrderBy 排序白名单、动态条件构建 |
3.2 自研中文全文检索（Segmenter + Search）🔍
Segmenter.php：中文二元切词（bigram），纯 PHP 实现、零扩展依赖，兼容中文语境Search.php：自建倒排索引（search_index表），标题/正文按权重分词收录- 支持分页重建（后台可视化进度）、FTS 同步、清理正文索引（weight=1）
- 覆盖帖子/博客/用户三类对象，SQL 层版块权限过滤保证越权零泄露
- 对比 LIKE：索引命中毫秒级返回，长文搜索不卡顿
3.3 自研富文本编辑器（assets/js/editor.js）✍️
- v3.0，基于 contenteditable + 原生 Selection/Range（替代 execCommand）
- 支持：加粗/斜体/下划线/删除线/标题/列表/对齐/字体颜色/背景色/字号/分割线/引用/链接/图片粘贴上传/QQ 表情/全屏/撤销重做/字数统计
- 可视化 + Markdown 双模式互转（marked + turndown）
- 安全：内容 base64 提交 +
sanitizeHTML沙箱净化（白名单标签/属性）
3.4 自研插件系统（Plugin + plugin.json）🧩
- 目录即插件：
plugins/{id}/一个目录包含全部（plugin.json声明 +Plugin.php生命周期 +hook/钩子 +views/视图 +assets/资源），插件自包含 - A+ 模板解析：
view('plugins/xxx/yyy')由TemplateCompiler::resolveTemplate插件目录优先解析到plugins/xxx/views/yyy.php（回落 app/Views）；app/Views/plugins/已整体移除，插件模板不再放核心目录 - 资源引用：页面直接
/plugins/{id}/assets/...（勿用asset()，其解析到assets/plugins/发布目录会造成双份漂移——历史坑已统一消除） - 钩子机制：核心共 21 个 hook 触发点（
init_after/route_register/admin_route_register/admin_sidebar_links/nav_main_links/nav_plugin_links/nav_user_menu_items/layout_head_end/home_sidebar_bottom/announcements_display/controller_view_before/route_before_dispatch/route_after_dispatch/auth_login_after/auth_register_before/auth_register_after/avatar_upload_after/thread_create_after/post_create_after/thread_edit_after/post_edit_after），在生命周期各节点广播（详见sosite-plugin-dev/plugin-system.md） - 后台可激活/禁用/卸载；扫描结果缓存到
plugins_cache.php（var_export生成 +json_decode读取 + 原子写入） - 现有 14 个插件（11 启用 / 3 停用：content_review、invite、qa）：公告、内容审核（多钩子深度集成）、签到、骰子、编辑辅助、友链、图标生成、邀请码、收藏、问答、答题对战、红包、SEO、用户主页
- 配套：
sosite-plugin-dev/插件开发 Skill/Rule 包（SKILL.md 规范 + 7 份 references 手册 + plugin-system.md 架构说明 + 插件仓库开发计划）
3.5 自研权限体系（Permission.php）🔐
- 用户组 × 版块权限矩阵（查看/发帖/回复/管理）
Auth::isAdmin双重确认（role=admin + group_id=4）- 后台基类强制
isAdmin + admin_verified_at二次验证 - 帖子列表/搜索/标签聚合 SQL 层权限过滤，分页准确不泄露
3.6 自研基础设施
| 模块 | 说明 |
|---|---|
RateLimiter | 文件型 IP 限流（登录/发帖/评论/私信/上传/搜索全覆盖），防刷防爆 |
RememberMe | 记住登录：Token 仅存 SHA-256、恒定比较、每次自动登录轮换 |
Content | 编辑器 base64 内容解码（严格校验防误判）+ HTML 净化 |
Settings | 站点配置读写缓存 + 统计计数器批量落库（shutdown flush） |
Upload | 扩展名+MIME 双白名单、随机名、Imagick/GD 缩略图、像素炸弹防护 |
Captcha | 自研图片验证码（弧线+噪点干扰，刷新即换） |
Mailer | SMTP 发送 + AES-256 加密 SMTP 密码（密钥常量管理） |
Points | 积分等级体系（发帖/回复/签到等行为加分，等级徽章） |
Vote | 点赞/点踩（线程/回复，htmx 局部刷新） |
AuditLog | 管理员操作审计（注册/登录/发帖/后台动作全记录） |
Theme | 主题/配色变体管理与用户级主题记忆 |
Tag | 标签云统计（SQL 实时计数）、热门标签缓存 |
3.7 前端交互体系
- SoState（Alpine.js）+ SoAjax（htmx）双引擎：投票、分页、表单提交局部刷新，无需整页跳转
- 图片灯箱：PC 滚轮缩放（0.4x~6x）+ 移动端双指捏合，点击关闭，跨端友好
- 移动端优先：底部导航、侧栏折叠、响应式三档断点
四、技术栈一览
| 层 | 技术 |
|---|---|
| 后端 | PHP 8.2（原生 + PDO），自研 MVC，约 9500 行 |
| 数据库 | MySQL 5.7.26（主）/ SQLite（兼容），双会话连接 |
| 前端 | Alpine.js + htmx + 原生 JS，自研编辑器与灯箱 |
| 样式 | 自研 Modern 主题（CSS 变量体系，唯一基座 modern.css），FontAwesome 图标 |
| 存储 | 文件上传（随机名+缩略图）、Session 数据库化、配置缓存 |
| 第三方 | 仅 marked / turndown（MD 转换）、qrcode（二维码）、FontAwesome |
五、V5.0.0 主要更新（相对 V4.2.0）
- 样式体系收敛：删除旧模板 CSS（forum/pages/layout/blog），收敛为 modern.css 唯一基座，同名类互覆问题清零，换肤成本大幅下降
- 后台样式作用域化：admin.css 全面使用
.admin-content/.admin-container前缀，与前台彻底隔离 - 内联样式收敛：前台/后台视图静态内联样式全部抽为工具类（新增 35+ mn-*/admin 工具类），动态色值保留内联
- 健壮性修复：新增通用 404 页（修复 user_profile 悬空引用）、标签页数量字段修复、标签聚合页头像/级别字段修复
- 交互优化：图片灯箱改为滚轮/手势缩放；回复区附件按钮独立一行；导航 logo 统一 hover 效果
- 代码卫生：清理 9 个孤儿/死文件（含 3 个旧 CSS），27 个零调用方法标注 @deprecated
六、2026-08-09 增量更新（架构演进）
- 插件模板统一到插件目录（A+ 规则）：
TemplateCompiler::resolveTemplate增加插件目录优先分支——view('plugins/xxx/yyy')直接解析到plugins/xxx/views/yyy.php；12 个插件模板从app/Views/plugins/迁入插件目录，app/Views/plugins/与 require 入口全部移除；插件完全自包含，为插件仓库铺路 - 插件资源引用统一：icon_generator 从
asset()（解析到assets/plugins/发布目录）改为直接/plugins/{id}/assets/...，删除assets/plugins/发布副本，消除双份漂移（14 插件资源引用方式全部一致） nav_user_menu_itemshook 补触发点：该 hook 曾因核心无调用点而不生效（post_favorite"我的收藏"、content_review"审核通知"入口不显示），已在layouts/main.php用户下拉菜单处补Plugin::hook('nav_user_menu_items')，核心 hook 总数达 21 个- 回复楼层显示：帖子详情页回复列表新增楼层号（引用行右侧、右对齐），跨分页连续（
($page-1)*perPage+$i+1），回复从 1 楼起算 - 软删回复计数修复：
Thread::decrementReplyCount（GREATEST 防负）+ 软删回复时同步递减reply_count；根目录fix_reply_count.php脚本可校正存量虚高（dry-run/apply 双模式 + 自动备份） - 插件开发 Skill/Rule 包：新增
sosite-plugin-dev/（SKILL.md 主入口 + 7 份 references 手册 + plugin-system.md 架构文档 + 插件仓库开发计划），覆盖插件结构/Hooks 目录/API 速查/安全规范/UI 模板/排错/典型模式 - 插件仓库开发计划：
SoSite-插件仓库开发计划.md定稿（feed.json 协议 + PluginMarket 安装器 + 安全解压/备份回滚 + P0~P4 分期）
文档生成于 2026-08-07，基于 V5.0.0 代码实际结构盘点；2026-08-09 更新（A+ 模板统一、hook 修复、楼层、计数修复、Skill 包与插件仓库计划）。
