目录与文件说明

更新于 2026-11-08 15:34:00 29 次浏览

本文档面向二次开发者，完整说明 BlogKit v1.0.0 的目录结构与各文件职责。系统整体介绍参见系统介绍，日常使用参见使用手册；模板语法与主题开发详见主题开发指南，插件开发详见插件开发指南。

一、完整目录树

BlogKit/
├── index.php                  # 前台统一入口
├── admin.php                  # 后台统一入口
├── api.php                    # API 统一入口（由「开放API」插件接管）
├── install.php                # 安装器（安装完成后可删除）
├── install.lock               # 安装锁（安装器自动生成）
├── LICENSE                    # GPLv3 协议全文
├── README.md                  # 项目简介
├── robots.txt                 # 搜索引擎爬取规则
├── favicon.ico                # 站点图标
├── .htaccess                  # Apache 伪静态规则
├── nginx.htaccess             # Nginx 伪静态参考规则
├── admin/                     # 后台界面（模板与静态资源）
│   ├── assets/
│   │   ├── css/               # auth / common / components / forms / sidebar / tables
│   │   └── js/                # common / sidebar / header / article-editor 等，含 jQuery
│   └── templates/             # 后台页面模板（文件名与后台 action 对应）
│       ├── components/        # header / footer / sidebar / pagination 等公共组件
│       └── config/            # 系统设置各分页（config_basic.html 等）
├── app/                       # 业务代码（控制器 / 模型 / 服务 / 中间件）
│   ├── Controllers/
│   │   ├── Admin/             # 后台控制器（34 个）
│   │   └── Front/             # 前台控制器（6 个）
│   ├── Models/                # 数据模型（12 个）
│   ├── Services/              # 业务服务层（6 个）
│   ├── Middleware/            # 中间件（后台登录校验）
│   ├── Components/            # 可复用 UI 组件
│   └── Config/                # 业务配置默认值
├── core/                      # 系统内核
│   ├── bootstrap.php          # 统一引导文件（所有入口共用）
│   ├── constants.php          # 全局常量定义
│   ├── config/                # 内核配置（system / version / database / install.sql）
│   ├── lib/                   # 核心类库（26 个类）
│   │   └── exceptions/        # 统一异常体系（1 基类 + 5 业务异常）
│   └── template/              # 模板引擎（9 个类文件）
├── plugins/                   # 插件目录（每插件一个 slug 子目录）
│   └── wangeditor/            # 内置富文本编辑器插件（发行包自带）
├── themes/                    # 前台主题目录
│   └── default/               # 默认主题
├── storage/                   # 运行时数据（需可写权限）
│   ├── cache/                 # 数据缓存 + 模板编译缓存（运行时自动生成）
│   ├── logs/                  # 系统日志
│   └── sessions/              # PHP 会话文件
├── uploads/                   # 上传文件目录（需可写权限）
├── update/                    # 升级系统目录（需可写权限）
│   ├── full/                  # 完整版升级包
│   ├── upgrade/               # 增量升级包
│   └── market/                # 应用市场下载缓存
└── docs/                      # 开发文档（本文档所在目录）

说明：storage/cache/、storage/logs/、storage/sessions/、uploads/、update/ 的内容均由系统在运行时自动创建；plugins/ 下除自带的 wangeditor 外，其余插件通过后台「应用市场」安装后生成。

二、根目录文件说明

文件	说明	是否可删
index.php	前台统一入口：加载 bootstrap 后定义 `THEMES_PATH`、`PLUGINS_PATH` 等常量，交由 `Router::dispatch()` 按配置驱动的路由表分发	不可删
admin.php	后台统一入口：定义 `ADMIN_PATH` 等常量，按 `$_GET['action']` 分发到后台控制器（默认 `dashboard`，内置 `SUB_ROUTE_MAP` 子路由映射）	不可删
api.php	API 统一入口（转发壳）：系统本身不含 API 逻辑，触发 `api_dispatch` 钩子后由「开放API」插件接管请求	不建议删除
install.php	安装器：检测环境、建库建表、写入配置	安装完成并确认正常后可删除
install.lock	安装锁：标记系统已安装；删除后任何访问都会被重定向到 install.php	不可删
LICENSE	GPLv3 协议全文，分发程序时必须保留	不可删
README.md	项目简介	可按需修改
robots.txt	爬虫规则，可按站点需求调整	可按需修改
favicon.ico	站点图标	可替换
.htaccess	Apache 伪静态规则（前台 URL 重写依赖）	Apache 环境不可删
nginx.htaccess	Nginx 伪静态参考规则，需手工合入 Nginx 配置	可保留作参考

三、core/ 内核详解

3.1 引导流程（bootstrap.php）

index.php、admin.php、api.php 三个入口第一步都执行 require core/bootstrap.php，按以下顺序完成公共初始化：

开启输出缓冲（避免 headers already sent）；
定义系统常量（ROOT_PATH、CORE_PATH、APP_PATH、STORAGE_PATH、LOG_PATH、UPLOADS_PATH、INSTALL_LOCK）；
检查 install.lock，未安装则跳转 install.php；
加载自动加载器（core/lib/autoload.php）与核心类（Config / Database / Model / Router / Security / ExceptionHandler / functions.php / Template.php）；
Config::init() 初始化配置，注册统一异常处理器，按站点配置设置时区；
配置并启动 Session：保存路径固定为 storage/sessions，独立 Cookie 名 BKSID，HttpOnly + SameSite=Strict，30 分钟无操作滑动过期；
维护模式与站点运行状态（open / closed / private）检查；
生成 CSRF Token，输出安全 HTTP 响应头（X-Frame-Options、CSP 等）。

3.2 core/config/ 配置文件

文件	说明	注意事项
system.php	系统默认配置（站点信息、安全、缓存等分组，返回数组）	可修改默认值，运行时以数据库配置优先
version.php	版本号唯一真相来源（version / version_code / release_date）	升级与更新检测依赖此文件
database.php	数据库连接配置，安装器生成	含账号密码，严禁公开、严禁提交到版本库
install.sql	建表与初始数据 SQL，安装器执行	修改表结构时须同步维护迁移逻辑

3.3 core/lib/ 核心类库

自动加载器 autoload.php 采用 PSR-4 风格路径映射，覆盖 core/lib、core/lib/exceptions、core/template、app/Models 等；functions.php 提供跨控制器复用的全局辅助函数（如 respondWithToast() 统一 Toast 提示跳转）。其余按一个文件一个类组织：

类（文件）	职责	关键公开方法
Database	PDO 数据库封装（单例），支持查询日志与查询缓存	`getInstance()`、`table()`、`query()` / `fetch()` / `fetchAll()`、`beginTransaction()`
Model	模型基类，封装单表 CRUD	`find()`、`get()`、`insert()`、`update()`、`delete()`、`count()`
Config	配置管理：文件配置 + 数据库配置合并，含敏感值加解密	`init()`、`get()` / `set()`、`loadFromDatabase()`、`getPublicConfig()`
Cache	缓存管理（单例，文件缓存 / Redis），支持标签失效与批量操作	`get()` / `set()` / `delete()`、`invalidateTags()`、`getStats()`
Router	前台路由（配置驱动的路由表，替代正则分支堆叠）	`dispatch()`、`getInstance()`
Security	安全工具：XSS 过滤、CSRF 生成校验、输入校验	`filterXss()`、`generateCsrfToken()`、`validateCsrfToken()`、`getCsrfField()`
Validator	表单验证器，支持规则数组与自定义错误消息	`make()`、`validate()`、`getErrors()`、`getFirstError()`
Captcha	图形验证码：生成、绘图、会话存储与统一校验	`create()`、`generate()`、`check()`、`verify()`
Upload	统一文件上传（头像 / 文章图片 / 评论图片 / 附件）	`upload()`、`uploadAvatar()`、`uploadArticleImage()`
Mail	邮件发送：SMTP 发送、按模板发送、队列发送	`send()`、`sendWithTemplate()`、`batchSendWithTemplate()`
EmailTemplate	邮件模板渲染与变量替换	`render()`、`loadTemplate()`、`previewTemplate()`
Log	统一日志门面：分级写入 + 委托 LogManager 读取清理	`info()` / `error()` / `security()`、`getLogs()`、`cleanExpiredLogs()`
LogManager	日志管理器：读取、统计、清理、报告生成	`getLogs()`、`getStats()`、`generateReport()`
Hook	钩子系统：触发动作钩子与过滤器钩子	`trigger()`、`triggerWithReturn()`、`filter()`、`hasCallback()`
HookTrigger	业务钩子便捷触发器（用户 / 文章 / 评论 / 插件 / 主题 / API 等百余个静态方法）	`userLoginAfter()`、`articleCreateAfter()`、`pluginActivateAfter()`
Plugin	插件管理器（单例）：扫描 / 安装 / 卸载 / 钩子注册 / 后台与前台路由接管	`getInstance()`、`scanPlugins()`、`installPlugin()`、`dispatchAdminRoute()`、`slot()`
PluginBase	插件基类，所有插件类继承此类	`init()`、`install()`、`activate()`、`uninstall()`、`getManifest()`
PluginValidator	插件打包结构校验，发布前检查是否符合规范	`validate()`、`getSummary()`
Migrate	数据库迁移引擎：建表 / 加列 / 索引 / 外键 / 种子数据同步	`run()`、`preview()`、`repairPermissions()`
Pagination	分页计算与分页链接渲染	`createLinks()`、`getOffset()`、`getTotalPages()`
Response	统一响应：JSON / 跳转 / 下载 / CORS 等	`success()`、`error()`、`redirect()`、`allowCors()`
ExceptionHandler	统一异常处理器，注册后接管未捕获异常	`register()`、`handle()`、`handle404()`
IpWhitelist	IP 白名单与 CIDR 校验、真实 IP 获取	`validate()`、`getRealIp()`、`ipInCidr()`
UserAgent	User-Agent 解析与客户端信息获取	`parse()`、`getIP()`、`getReferer()`
Search	站内搜索（单例）：搜索、热搜词、搜索建议	`search()`、`getHotSearches()`、`getSuggestions()`
ListQuery	后台列表查询参数助手：分页条数与表头排序白名单校验	`pageSize()`、`pageSizes()`、`sort()`

core/lib/exceptions/ 为统一异常体系：基类 AppException（统一错误码与 HTTP 状态码映射），子类 AuthException（401）、ForbiddenException（403）、NotFoundException（404）、ValidationException（422）、SystemException（500，自动记录日志）。

3.4 core/template/ 模板引擎

模板引擎由 Template.php 担任核心协调器（变量管理、站点与主题配置加载、组件编排），具体解析工作委托给下列组件。标签语法详见主题开发指南。

组件（文件）	职责
TemplateParser.php	核心标签解析引擎：`{cache}` 区块缓存、`{macro}` 宏定义与调用等全部模板标签
TemplateCompiler.php	模板编译与缓存系统：缓存目录初始化、编译产物判断与读写
TemplateInheritance.php	模板继承：`{extend}` 父模板继承、`{block}` 块定义与嵌套替换
TemplateCondition.php	条件表达式评估：深层嵌套变量替换、`{field}` 字段标签替换
TemplateUrl.php	URL 生成：文章 / 分类 / 标签 / 页面及登录注册等链接
TemplateOutput.php	输出辅助：面包屑导航、分页信息与导航渲染
TemplateFilter.php	过滤器系统：upper / lower / truncate / date / escape 等内置过滤器与自定义注册
TemplateExtension.php	扩展变量与标签：`{user_ip}`、`{user_agent}`、`{server_time}` 等额外变量

四、app/ 业务代码详解

4.1 控制器（Controllers）

命名规则：一个控制器一个文件，XxxController.php 内定义 XxxController 类，全部以静态方法组织动作。

后台控制器（app/Controllers/Admin/，34 个）：通过 admin.php?action=xxx 访问，action 名与控制器、模板名对应（如 action=article 调用 ArticleController，渲染 admin/templates/article.html）。

控制器	职责	控制器	职责
DashboardController	后台仪表盘	RoleController	角色管理
ArticleController	文章管理（含回收站）	PermissionController	权限节点管理
CategoryController	分类管理	UserController	用户管理（含回收站）
TagController	标签管理	UserSettingsController	用户相关设置
CommentController	评论管理（含回收站）	LoginController	后台登录 / 退出 / 忘记密码
PageController	页面管理	CaptchaController	后台验证码图片输出
FriendlinkController	友情链接管理	PluginController	插件管理
MediaController	媒体库管理	MarketController	应用市场
UploadController	后台上传接口	ThemeController	主题管理
EmailTemplateController	邮件模板管理	UpdateController	系统更新
BackupController	数据备份 / 恢复	MigrateController	数据迁移
ConfigController	系统配置总控	CacheController	缓存管理
BasicSettingsController	基础设置	SearchController	站内搜索管理
SeoSettingsController	SEO 设置	SearchSettingsController	搜索设置
RewriteSettingsController	伪静态设置	SecurityController	安全设置
EmailSettingsController	邮件设置	CaptchaSettingsController	验证码设置
CommentSettingsController	评论设置	SitemapController	站点地图（sitemap.xml）

前台控制器（app/Controllers/Front/，6 个）：由 Router::dispatch() 按路由表调用。

控制器	职责
HomeController	首页 / 文章 / 分类 / 标签 / 搜索 / 页面等前台展示
AuthController	前台注册 / 登录 / 找回密码
ProfileController	用户中心（资料 / 消息 / 收藏 / 关注等）
CommentController	前台评论提交与互动
CaptchaController	前台验证码图片输出
RSSController	RSS 订阅输出

4.2 模型（Models）

命名规则：XxxModel.php + XxxModel 类，与数据表一一对应，封装该表的查询与读写。共 12 个：ArticleModel（文章）、CategoryModel（分类）、TagModel（标签）、CommentModel（评论）、PageModel（页面）、UserModel（用户）、RoleModel（角色）、PermissionModel（权限节点）、ConfigModel（系统配置）、EmailTemplateModel（邮件模板）、FriendlinkModel（友情链接）、LoginTokenModel（登录保持令牌）。

4.3 服务层（Services）

命名规则：XxxService.php + XxxService 类，位于控制器与模型之间，承载跨模型业务编排与复杂校验，共 6 个：ArticleService（文章业务）、CommentService（评论业务）、UserService（用户业务）、MediaService（媒体文件业务）、ConfigService（配置读写业务）、DashboardService（仪表盘数据聚合）。

4.4 中间件（Middleware）

文件	职责
AuthMiddleware.php	后台认证中间件：校验登录态与权限，未登录跳转登录页

4.5 组件（Components）

文件	职责
Icon.php	统一图标组件，集中管理后台图标输出
UIComponents.php	后台通用 UI 组件渲染（表格工具条、状态标签等）

4.6 业务配置（Config）

文件	职责
default.php	系统配置默认值的唯一权威来源，安装与运行时缺失配置均以此为准

五、admin/ 后台界面详解

admin/
├── assets/                    # 后台静态资源
│   ├── css/                   # auth / common / components / forms / sidebar / tables
│   └── js/                    # common / sidebar / header / article-editor /
│                              # article-description-helper / jquery-4.0.0.min
└── templates/                 # 后台模板（与 action 同名）
    ├── components/            # 公共组件（被各模板 include）
    └── config/                # 系统设置分页

模板组织规则：后台控制器通过 include ADMIN_PATH . '/templates/xxx.html' 渲染页面，模板文件名与 action 名一致，遵循统一命名模式：

列表页：article.html、user.html、comment.html 等；
新增 / 编辑页：article_add.html、article_edit.html（成对出现）；
回收站页：article_recycle.html、comment_recycle.html、user_recycle.html；
配置页：骨架为 config.html，各设置分页在 config/ 下按 config_basic.html、config_seo.html、config_email.html 等命名，由 admin.php 的 SUB_ROUTE_MAP 将 action=config&sub=xxx 映射到对应分页；
登录相关：login.html、forgot-password.html、reset-password.html。

公共组件（templates/components/）：header.html / footer.html（页面骨架）、sidebar.html / sidebar_logic.html（侧边菜单及显隐逻辑）、admin_nav.html、config_nav.html（设置页导航）、pagination.html（分页）、flash_messages.html（提示消息）、notification_center.html、col_filter.html（列筛选）、sort_link.html（表头排序）、empty_state.html（空状态）、page_wrapper.html / footer_wrapper.html（页面包装）、svg_icons.php（SVG 图标库，PHP 组件）。

六、plugins/ 插件目录

每个插件占用一个以 slug 命名的独立子目录，发行包自带 wangeditor（富文本编辑器），其余官方插件通过后台「应用市场」安装后同样落在此目录。

plugins/wangeditor/           # 以内置插件为例
├── plugin.json               # 插件清单：名称、slug、版本、依赖、配置表单等
├── plugin.php                # 插件入口文件
├── WangEditorPlugin.php      # 插件主类（继承 core/lib/PluginBase.php）
├── install.php               # 可选：安装脚本
├── icon.png / thumbnail.png  # 图标与市场缩略图
├── wangEditor.js             # 插件前端资源
└── css/style.css             # 插件样式

约定要点：插件主类继承 PluginBase，通过 Plugin::getInstance()->addHook() 注册钩子；插件可声明后台路由（Plugin::dispatchAdminRoute() 接管）与前台路由（Plugin::matchFrontRoute() 接管）；插件私有模板放在插件目录内，由 Plugin::view() 渲染。目录规范、清单字段与钩子列表详见插件开发指南。

七、themes/ 主题目录

themes/default/               # 默认主题
├── theme.json                # 主题清单：名称、版本、作者、配置项等
├── screenshot.png            # 主题预览图
├── assets/
│   ├── css/                  # style.css、prism.css（代码高亮）等
│   ├── images/               # 主题图片
│   └── js/                   # main.js、article.js、captcha.js 等
└── templates/                # 前台模板
    ├── index.html            # 首页（命名与前台路由对应）
    ├── article.html          # 文章页
    ├── category.html / tag.html / tags.html / search.html / archives.html
    ├── page.html / 404.html
    ├── login.html / register.html / forgot-password.html / reset-password.html
    ├── profile_*.html        # 用户中心各页（资料 / 消息 / 收藏 / 关注等）
    ├── user_profile.html     # 他人主页
    └── common/               # 公共片段：header / footer / navbar / sidebar /
                              # pagination / article_comments 等

主题模板由 core/template 引擎解析，{extend} / {block} 继承与标签语法详见主题开发指南。

八、storage/、uploads/、update/ 运行时目录

目录	用途	权限要求
storage/cache/	数据缓存文件与模板编译缓存（`cache/templates/`）	可写
storage/logs/	系统运行日志（Log 类按级别、分类写入）	可写
storage/sessions/	PHP 会话文件（bootstrap 固定保存路径）	可写
uploads/	用户上传文件：头像、文章图片、评论图片、附件	可写
update/full/	系统更新下载的完整版升级包	可写
update/upgrade/	系统更新下载的增量升级包	可写
update/market/	应用市场插件 / 主题的下载缓存	可写

以上目录及其子目录均需 Web 服务器进程可写，否则安装、缓存、上传、更新功能会失败。

九、常见问题

9.1 哪些目录需要可写权限

必须可写：storage/（含 cache / logs / sessions 子目录）、uploads/、update/；
仅安装时需要：站点根目录（安装器写入 core/config/database.php 与 install.lock），安装完成后可收回根目录写权限。

9.2 哪些文件绝对不能公开

core/config/database.php：含数据库账号与密码，安装时生成。严禁提交到公开版本库、严禁放入可下载目录；生产环境建议在 Web 服务器上屏蔽对 core/、app/、storage/ 的直接 HTTP 访问（Apache 环境可参考各目录的访问限制规则）。
install.lock 虽不含敏感信息，但删除会导致系统重新进入安装流程，同样请勿对外提供写操作。

9.3 缓存清理对应关系

操作	影响位置
后台「清除缓存」	清空 `storage/cache/`（数据缓存 + `cache/templates/` 模板编译缓存）
修改模板文件后页面未更新	手动删除 `storage/cache/templates/`（或执行一次清除缓存）
修改插件 / 主题配置后异常	清除缓存即可，配置本体存于数据库
日志清理	后台日志管理（对应 `Log::cleanExpiredLogs()`），物理文件在 `storage/logs/`
会话文件	`storage/sessions/` 不建议手动清空，会使所有在线用户掉线