本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：备忘md/_SOSITE_DOCUMENTATION.md。

SoSite V3.5 — 完整文档归档

生成日期：2026-06-26

说明：将根目录下 7 个 MD 文件合并整理而成，消除重复，保留所有有效信息。

目录

1. 项目概览
2. 核心架构
3. 已实现功能清单
4. 安装与部署
5. 安全状况
6. 代码审查待办
7. XenForo 分析借鉴
8. 功能开发计划（未实现）
9. 附录：关键文件路径速查

一、项目概览

SoSite — 自研轻量 PHP 社区系统（类似简化版 Discuz!），支持 SQLite/MySQL。

• 版本：V3.5.0（常量 SOSITE_VERSION 仍为 V3.0.0，未同步）
• 根目录：D:\phpstudy_pro\WWW\
• 架构：自制轻量 MVC 框架（非 Composer，纯手写 Autoloader）
• 索引页：index.php → app/init.php → Router 分发
• 启动文件：config.php（Session 配置、数据库路径、常量）
• 数据库文件：protected/forum.db（SQLite，另含备份）

核心开发记录

• 对话轮次：700+ 轮
• 开发周期：从零构建，非现有框架改造
• 第三方安全审计已执行两轮

二、核心架构

目录结构

WWW/
├── index.php                    # 前端控制器（路由分发）
├── config.php                   # 全局配置（Session/DB/常量）
├── .htaccess / web.config       # URL 重写
├── app/
│   ├── init.php                 # 应用初始化（autoloader→config→session→view→plugin）
│   ├── Core/
│   │   ├── Autoloader.php       # PSR-4 风格自动加载
│   │   ├── Router.php           # 路由引擎（支持 {param} 占位符）
│   │   ├── Controller.php       # 基础控制器
│   │   ├── Model.php            # 基础模型
│   │   ├── Database.php         # PDO 封装（SQLite/MySQL）
│   │   └── View.php / TemplateCompiler.php  # 模板引擎（双模共存）
│   ├── Controllers/             # 控制器
│   │   ├── Admin/               # 后台控制器（~15个）
│   │   └── *Controller.php      # 前台控制器（~13个）
│   ├── Helpers/                 # 辅助类（~13个）
│   ├── Models/                  # 模型（~17个）
│   └── Views/                   # 视图（~45个）
├── assets/                      # 静态资源（CSS/JS/图片/上传）
├── plugins/                     # 插件目录
├── protected/                   # 保护目录（DB/缓存/Session）
├── plug/                        # 插件在线生成器（独立子程序）
├── docs/                        # 离线文档（17个HTML页面）
├── database/                    # 数据库初始化脚本
├── sositeV3.5/                  # 发布包目录
└── *_*.md                       # 根目录下 8 个 MD 文档

关键表结构

users:     id, username, password, email, avatar, signature, role, post_count, points, level, theme, created_at, last_login
threads:   id, category_id, user_id, title, content, view_count, reply_count, is_pinned, is_highlighted, color, reply_to_view, deleted_at, last_reply_at, created_at
posts:     id, thread_id, user_id, content, deleted_at, created_at
categories: id, name, description, sort_order, created_at
online_users: user_id, last_activity

插件系统

• 设计："钩子即文件"（借鉴 XiunoBBS）
• 核心文件：app/Helpers/Plugin.php
• 共 17 个钩子点：init_after, route_register, admin_route_register, route_before_dispatch, route_after_dispatch, auth_login_after, auth_register_after, thread_create_after, post_create_after, controller_view_before, layout_head_end, nav_main_links, nav_plugin_links, nav_user_menu_items, admin_sidebar_links, home_sidebar_bottom, layout_footer
• 缓存机制：plugins/plugins_cache.php

模板引擎（TemplateCompiler）

语法类 Blade，支持：

• {$var} 转义输出 / {$var:raw} 原始输出
• {if}/{elseif}/{else}/{/if} 条件
• {loop $arr $val} / {loop $arr $key $val} 循环
• {include} / {extend} / {section} / {yield} 布局系统
• {php}...{/php} 嵌入 PHP
• 模板内可用方法：$this->e(), $this->timeAgo(), $this->asset(), $this->icon() 等

CSS 加载顺序

1. style.css        → 基础核心（变量、重置、工具类、公共组件）
2. layout.css       → 布局（导航栏、侧边栏、页脚、响应式）
3. forum.css        → 论坛专有样式
4. pages.css        → 其他页面样式
5. components.css   → 通用组件
6. themes/common.css→ 主题公共装饰
7. themes/<主题>.css→ 当前主题配色
8. admin.css        → 后台管理样式
9. editor.css       → 编辑器样式

三、已实现功能清单

论坛系统

• [x] 板块分类（支持无限层级）
• [x] 发帖/回帖/编辑/删除
• [x] 帖子置顶/精华/高亮
• [x] 赞踩投票
• [x] 帖子附件上传
• [x] 帖子浏览量统计
• [x] 快速回复（主题底部回复框）

博客系统

• [x] 博客文章 CRUD
• [x] 博客分类
• [x] 博客封面图
• [x] 博客浏览量统计

用户系统

• [x] 注册/登录/退出
• [x] 记住登录（RememberMe — SHA256 Token + DB 比对）
• [x] 个人资料
• [x] 头像（Gravatar URL 方式）
• [x] 短消息系统
• [x] 积分/等级系统
• [x] 验证码（登录/注册）

搜索系统

• [x] SQLite FTS5 全文搜索
• [x] MySQL FULLTEXT 搜索
• [x] LIKE 降级搜索
• [x] 标签搜索（标签云）

后台管理

• [x] 控制台 — 统计卡片 + 最新用户/帖子
• [x] 站点设置 — 名称/描述/公告/分页/注册开关/附件开关
• [x] 分类管理
• [x] 用户管理
• [x] 短消息管理
• [x] 主题管理（含 CSS 编辑）
• [x] 标签管理
• [x] 积分规则管理
• [x] 附件管理
• [x] 数据库维护（备份/恢复/优化）
• [x] 回收站
• [x] 数据维护（重建索引）

前端特性

• [x] 响应式布局（PC + 移动端 @media max-width: 768px）
• [x] 多主题系统（30+ 主题，含 Discuz5/phpBB/IPB 等经典风格）
• [x] 主题预览切换
• [x] 用户自定义主题设置
• [x] 公告栏
• [x] 标签云
• [x] 在线用户统计

插件生成器（独立程序 plug/）

• [x] 注册/登录（BCrypt + Session）
• [x] 表单编辑 + 预览（语法高亮编辑器）
• [x] 模板预设（每日签到、友情链接、帖子收藏、SEO 优化、统计看板）
• [x] 生成历史管理（编辑/删除/搜索）
• [x] ZIP 打包下载
• [x] ZIP 导入解析
• [x] 安全加固两轮（RCE 路径穿越、IDOR 越权、Zip Slip 等修复）

安全特性

• [x] 全部参数化 SQL 查询（:param 绑定）
• [x] 模板自动 htmlspecialchars(ENT_QUOTES|UTF-8) 转义
• [x] CSRF Token 验证
• [x] 密码 password_hash(PASSWORD_DEFAULT) + password_verify()
• [x] Cookie httponly/SameSite=Lax/secure 自动检测
• [x] 文件上传 MIME 校验 + 扩展名白名单 + 危险扩展拦截
• [x] 速率限制：登录（5 次/120s）、注册（3 次/h）、投票（30 次/min）、上传（5 次/min）
• [x] 管理员半小时二次验证
• [x] 登录后 session_regenerate_id(true)
• [x] 内容 HTML 白名单过滤（Content::sanitizeHtml()）

离线文档

• [x] docs/ 下 17 个 HTML 文件，全部更新至 V3.5.0
• [x] 页脚抽取为独立文件 _footer.html + footer.js

安装与发布

• [x] sositeV3.5/install.php 安装向导（含安全锁、WAL 清理）
• [x] 发布包 sositeV3.5/（294 文件 59 目录）
• [x] sositeV3.5.zip

四、安装与部署

环境要求

• PHP 7.4+（推荐 8.0+）
• 扩展：PDO、SQLite3、curl、mbstring、gd、json、zip
• MySQL（可选）：5.7+

快速安装

1. 上传到网站根目录
2. 访问 http://你的域名/install.php
3. 跟随安装向导
4. 安装完成后建议删除 install.php

数据库支持

生产部署注意事项

1. 禁止 .db 文件直接访问 — 在 web.config 或 .htaccess 中添加 *.db 拦截规则
2. 关闭 display_errors — php.ini 中 display_errors = Off, log_errors = On
3. 配置 HTTPS — 否则 Session Cookie 明文传输
4. 安装后删除 install.php

五、安全状况

总体评分：良好 ✅

安全评分：82-85 / 100（两次审查取综合）

直接可利用漏洞：0 个

安全亮点

发现的问题（按当前代码核实状态标注）

✅ = 已修复 ❌ = 尚未修复 🔲 = 无需处理

安全审计完整记录

已执行两轮加固：

• 第一轮：修复 RCE 路径穿越、IDOR 越权、Zip Slip/Bomb、Session 固定、命名空间硬编码、Session 大数组残留（共 7 项）
• 第二轮：修复 ZIP 导入污染 POST、钩子白名单缺失、下载后 unset 导致重定向、initDB 刷日志、mkdir 权限、Session 安全配置（共 6 项）

六、代码审查待办

以下为第三方 Code Review 建议，按优先级排列：

待处理

已验证无需处理

七、XenForo 分析借鉴

来源：XenForo v2.2.9 完整源码分析

第一梯队（简单高效，可快速移植）

第二梯队（中等投入，价值高）

第三梯队（高投入，按需）

可直接复用的 XenForo 资源

八、功能开发计划（未实现）

P0 — 生产部署必需

1. 禁止 .db 文件直接访问 — web.config / .htaccess
2. 关闭 display_errors — display_errors = Off
3. 配置 HTTPS

P1 — 建议近期实现

1. 通知系统（插件） — post_create_after 钩子 + route_register + nav_user_menu_items。纯插件，零改核心
2. 密码找回（插件 + 改一行 core） — 需在 app/Views/auth/login.php 加 Plugin::hook('auth_login_form_end')
3. SOSITE_VERSION 常量更新 — 'V3.0.0' → 'V3.5.0'

P2 — 中长期

各类功能通过插件实现的可能性

九、附录：关键文件路径速查

本文件由 7 个独立文档合并整理而成：SOSITE_V3_功能开发计划.md、SOSITE_开发全记录.md、README.md、security_review_report.md、xenforo-analysis.md、code_review_report_20260621.md、code-review-todo.md。