系统介绍

本文面向初次接触 BlogKit 的站长，帮助你快速了解产品定位、功能特性与部署方式。

1. 产品简介

BlogKit 是一款轻量级开源博客系统（当前版本 v1.0.0，2026-10-01 发布），开箱即用、易于二次开发。主要技术特点：

• 原生 PHP，无框架依赖：核心代码全部基于原生 PHP 编写，不依赖任何第三方框架，也无需 Composer，代码结构直观，便于阅读和二次开发；
• GPLv3 开源协议：您可以依据协议自由使用、修改与再分发；
• 插件化架构：核心保持精简，富文本编辑器之外的扩展能力（如开放 API、消息通知、云存储等）均以插件形式提供，通过后台「应用市场」一键安装；
• 自研模板引擎：主题由模板与静态资源组成，支持模板缓存，前台外观与后台逻辑解耦；
• 一键安装向导：环境自检、数据库配置、管理员创建同屏完成，无需命令行操作。

2. 功能特性总览

2.1 插件生态

主系统仅预装 WangEditor 富文本编辑器插件，其余能力按需安装。以下插件均可通过后台「应用市场」一键安装：

插件安装启用后即可被有权限的后台角色访问，停用即拒绝访问；所有插件（含官方插件）的管理页不占用后台侧边栏，统一从「插件管理 → 插件详情 → 配置」进入。

3. 系统架构概览

系统采用「单一入口 + 内核引导」的分层结构：所有请求由入口文件进入，经 core/bootstrap.php 统一引导（安装检查、自动加载、安全初始化）后，由路由分发到业务层处理，插件与主题作为扩展挂载在内核之上。

graph TD
    A["入口层<br/>index.php（前台）· admin.php（后台）· api.php（API）"] --> B["core 内核<br/>bootstrap.php 统一引导"]
    B --> C["core/lib 核心类库<br/>Router 路由 · Database 数据库 · Model 模型基类<br/>Security 安全 · Hook 钩子 · Plugin 插件<br/>Template 模板引擎 · Cache 缓存"]
    C --> D["app 业务层<br/>Controllers（Front / Admin）<br/>Models · Services · Middleware"]
    B --> E["plugins/ 插件扩展<br/>编辑器 · 官方插件 · 云存储等"]
    B --> F["themes/ 主题扩展<br/>模板 + 静态资源"]
    D --> G[("MySQL")]
    D --> H["storage/<br/>缓存 · 日志 · 会话"]
    D --> I["uploads/<br/>上传附件"]

说明：

• api.php 仅是转发壳，API 逻辑由「开放API」插件接管；该插件未安装或未启用时返回 404 JSON 提示；
• install.php 为独立安装器，安装完成后应从服务器删除。

4. 运行环境要求

以上环境在运行安装向导时会自动逐项检测，必需项全部通过后方可继续安装，推荐项缺失仅作警示。

5. 安装部署

5.1 下载与上传

1. 从 GitHub Releases 或 Gitee 下载源码包；
2. 解压后上传全部文件至网站根目录（如 public_html、www 等）。

5.2 配置伪静态

Apache：在站点根目录的 .htaccess 文件中添加以下规则（后台「伪静态设置」页可一键复制）：

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /

    # 已存在的文件或目录直接返回
    RewriteCond %{REQUEST_FILENAME} -f [OR]
    RewriteCond %{REQUEST_FILENAME} -d
    RewriteRule ^ - [L]

    # 其余请求交给 index.php 处理
    RewriteRule ^(.*)$ index.php/$1 [L,QSA]
</IfModule>

若不生效，请确认已启用 mod_rewrite 模块，且 Apache 配置中允许 .htaccess 覆盖（AllowOverride All）。

Nginx：在站点配置的 server 块中添加以下规则（系统根目录的 nginx.htaccess 为参考文件，宝塔面板可粘贴到「网站设置 → 伪静态」）：

location / {
    try_files $uri $uri/ /index.php$uri?$args;
}

5.3 运行安装向导

1. 浏览器访问 http://你的域名/install.php，向导会先进行环境自检；
2. 填写数据库信息（主机、端口、库名、账号、表前缀默认 bk_、字符集推荐 utf8mb4），数据库不存在时安装器会尝试自动创建；
3. 设置管理员账号（用户名 3-32 位，密码至少 8 位，建议使用页面提供的随机强密码）并填写邮箱；
4. 提交后安装器自动建表、生成配置文件 core/config/database.php 并写入安装锁 install.lock；
5. 点击「进入后台登录」，访问 admin.php 登录。

安装器具备防重复安装机制：检测到 install.lock 后将拒绝再次运行。

5.4 安装后安全清单

• 删除服务器上的 install.php（虽然 install.lock 已阻止重复安装，但仍建议删除）；
• 确认 core/config/database.php（含数据库凭据）未对外泄露，保持权限 0644；
• 后台登录后修改为强密码，妥善保管；
• 生产环境将 core/config/system.php 中的调试模式关闭（debug.enabled 设为 false）；
• 配置 HTTPS 后，系统会自动启用更严格的会话 Cookie 与 HSTS 响应头。

6. 五分钟上手

1. 前台浏览：访问站点首页即可浏览文章；伪静态生效后，文章地址形如 /article/1；
2. 后台发文：访问 admin.php 登录后台 → 「文章管理」→ 新建文章，使用 WangEditor 编辑器撰写并发布；
3. 安装插件：进入「应用市场」，按需一键安装官方插件（消息通知、互动增强、图片优化、审计日志、开放API、开发者工具箱等）及云存储类插件；所有插件的配置入口统一位于「插件管理 → 插件详情 → 配置」；
4. 更换主题：后台「外观」中选择或更换主题，前台立即生效；
5. 个人中心：注册用户登录后，可在个人中心管理资料、我的评论、我的收藏等信息。

想开发自己的插件与主题，请参阅 插件开发指南。

7. 常见问题 FAQ

Q：前台除首页外全部 404？ A：伪静态未生效。检查是否已按上文添加规则：Apache 确认 mod_rewrite 已启用且 AllowOverride All；Nginx 确认规则位于正确的 server 块并已重载配置（nginx -s reload）。

Q：图片上传失败或验证码不显示？ A：多为目录权限问题。确认 uploads/ 与 storage/ 对 Web 进程用户可写，Linux 下可执行：

chmod -R 755 uploads storage

Q：提示数据库连接失败？ A：检查主机、端口（默认 3306）、用户名与密码；若数据库不存在且账号无建库权限，请先在主机面板创建数据库再安装。重新安装需先删除站点根目录的 install.lock（会清空现有数据，务必先备份）。

Q：忘记后台密码怎么办？ A：两种处理路径：

1. 若站点邮件服务已配置可用，可在登录页点击「忘记密码」，通过邮箱自助重置；
2. 若邮件不可用，可通过数据库工具将管理员用户对应的 password 字段更新为新的哈希值（使用 PHP password_hash() 生成），例如：

UPDATE bk_users SET password = '新的password_hash哈希值' WHERE username = '你的管理员用户名';

Q：如何配置邮件发送？ A：后台提供「邮件设置」与邮件模板管理，配置好 SMTP 后，「忘记密码」等依赖邮件的功能才能正常使用。

Q：系统如何升级？ A：v1.0.x 阶段不提供在线升级。升级方式为：先备份数据库与 uploads/ 附件 → 下载新版本全新安装 → 通过后台数据迁移工具导入数据 → 到应用市场重新安装所需插件。

8. 目录速览

├── admin/            后台界面（模板与静态资源）
├── app/              业务代码（控制器 / 模型 / 服务 / 中间件）
├── core/             框架内核（路由、模板引擎、数据库、插件与钩子系统）
├── plugins/          插件目录
├── storage/          运行时数据（缓存、日志、会话，需可写）
├── themes/           主题目录
├── uploads/          上传文件（需可写）
├── index.php         前台统一入口
├── admin.php         后台统一入口
├── api.php           API 统一入口
└── install.php       安装器（安装完成后删除）

各目录职责与代码组织方式的详细说明，请参阅 目录与文件说明。

9. 技术支持与参与贡献

• 项目主页：https://www.blogkit.cn
• 文档中心：https://www.blogkit.cn/docs
• 社区反馈：https://www.blogkit.cn/community
• 源码仓库：https://github.com/cnbana/BlogKit（主仓库）、https://gitee.com/slinbo/blogkit（Gitee 镜像）

使用中遇到问题，欢迎通过社区或仓库 Issue 反馈；也欢迎 Fork 后提交 Pull Request 参与共建。

10. 开源许可

本项目基于 GNU General Public License v3.0 (GPLv3) 授权发布：您可以依据协议自由使用、修改与再分发，但分发时须保留版权与许可声明。本程序不提供任何担保。

Copyright (C) 2026 石林波 (Bana)