# qbcms

**Repository Path**: zishi28/qbcms

## Basic Information

- **Project Name**: qbcms
- **Description**: QBCMS 是一款基于原生 PHP 开发的轻量级内容管理系统。零第三方依赖、 无需 Composer，同时支持 SQLite 与 MySQL，内置主题、插件、会员与 RBAC 权限体系，帮助你快速搭建专业站点。
官方网址：https://www.qbcms.com
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QBCMS（启步内容管理系统）

> 轻量级 PHP 内容管理系统，当前版本 **v1.2.0**
>
> 本文档面向 QBCMS 通用源码版本；面向特定站点部署的私有主题模板及官方后台专有模块不包含在本文档说明范围内。

QBCMS（启步内容管理系统）是一款自研的轻量级 PHP 内容管理系统，基于原生 PHP 开发、无第三方框架依赖，采用 PDO 抽象层同时支持 MySQL 与 SQLite。系统开箱即用，适合企业官网、政务站点等内容型网站建设。

作者：金恒（QQ：372324643）  
官网：[www.qbcms.com](http://www.qbcms.com)  
QQ交流群：527445836

## 功能特性

### 前台功能

- **栏目与文章**：多级栏目、栏目别名、文章发布与编辑、浏览量统计、文章点赞与收藏
- **专题与标签**：专题列表/详情页、标签云、标签文章列表
- **单页**：别名 URL 单页（如 `/page/about/`）
- **留言与评论**：留言板（分类、审核）、文章评论（审核）
- **会员系统**：注册/登录/找回密码、个人中心（资料、我的评论、我的留言、收藏、点赞）
- **会员投稿**：创建/编辑/删除投稿，后台审核
- **相册**（内置相册插件）：相册封面墙、相册详情、单图浏览、私密相册（仅会员可见）
- **站内搜索**：支持文章/作者/评论搜索，范围由后台配置控制
- **友情链接**：前台申请、后台审核
- **Sitemap**：动态生成 `sitemap.xml`
- **动态数据 API**：文章正文、浏览量、评论数、点赞/收藏数等接口，供静态 HTML 页面 AJAX 注入实时数据

### 后台功能

- **控制台**：站点概况与快捷入口
- **内容中心**：栏目管理、发表/管理文章、专题管理、单页管理、标签管理、投稿审核、回收站
- **会员互动**：会员管理、会员角色、评论管理、留言管理（含类别与设置）
- **站点展示**：轮播图管理、友情链接、链接分组
- **系统工具**：网站设置、操作日志管理（可按模块配置记录范围）、Hook 调试、数据库备份、静态 HTML 生成、上传管理、应用中心（插件）、系统更新
- **管理权限**：管理员账号、管理角色，内置 RBAC 细粒度权限体系
- **模板标签**：标签手册、标签生成器、自定义标签、模板在线编辑

### 基础能力

- RBAC 权限 + 操作日志 + CSRF 防护 + 登录验证码 + 后台 IP 黑白名单
- 目录/文件安全防护（配置文件、数据库文件、上传目录脚本访问拦截）
- 插件系统（Hook 事件中心、ZIP 包一键安装）
- 在线升级（自动备份 → MD5 校验 → 增量覆盖）
- 静态 HTML 生成与模板/数据缓存
- URL 伪静态（Apache / IIS / Nginx 均支持，未配置重写时也能工作）

## 运行环境

| 项目      | 要求                                                |
| ------- | ------------------------------------------------- |
| PHP     | 7.0 及以上（推荐 7.4+，支持7.0~8.5环境）                      |
| 必需扩展    | PDO（MySQL 或 SQLite 驱动至少其一）                        |
| 可选扩展    | ZipArchive（在线升级）、GD（验证码与图片水印；无 GD 时验证码自动降级为纯文本模式） |
| Web 服务器 | Apache / IIS / Nginx                              |
| 目录权限    | `install/`、`cache/`、`uploads/`、`data/` 需具备写入权限    |
| 依赖      | 零第三方依赖，无需 Composer                                |

## 快速安装

1. 将程序文件上传至站点根目录；
2. 确认 `install/`、`cache/`、`uploads/`、`data/` 目录存在且可写（缺失时安装程序会自动创建）；
3. 浏览器访问 `/install/` 进入安装向导，按 4 步完成：  
   安装须知 → 环境检测 → 配置安装 → 完成；
4. **数据库选择**：默认推荐 SQLite（免配置，自动生成 `data/qbcms+随机或自定义后缀.db`）；如需高性能或已有 MySQL 环境，可切换为 MySQL 并填写连接信息；
5. **表前缀**：默认 `qbcms_`，多站点共用同一数据库时可修改前缀区分；
6. **后台目录**：默认 `admin`，建议安装时修改为自定义名称（如 `manage`、`houtai`）以降低被扫描风险；
7. 安装成功后自动生成 `config.php` 与 `data/`、`uploads/` 目录防护文件；安装完成系统会自动清理 `install` 目录，如清理失败请手动删除，防止他人重入安装向导；
8. 配置伪静态（可选但推荐）：
   - Apache：使用根目录 `.htaccess`（已内置）；
   - IIS：使用根目录 `web.config`（已内置）；
   - Nginx：按 `.htaccess` 规则等价转换——除真实文件外全部转发给 `index.php`，并优先命中 `static/` 目录下生成的静态 HTML；
   - 未配置重写规则时，系统可通过 `index.php?c=Xxx&a=index` 及 Router 的 REQUEST_URI 解析正常访问。

后台默认地址为 `/admin/`，登录后进入控制台。

## 目录结构

```text
web/
├── index.php            前台入口（安装检测、站点开关、验证码拦截、插件启动、路由分发）
├── config.php           主配置文件（安装程序生成，含数据库等敏感信息，禁止外部访问）
├── captcha.php          验证码图片请求
├── .htaccess            Apache：安全加固 + 伪静态规则
├── web.config           IIS：安全过滤 + URL Rewrite（含 static/ 静态命中优先）
├── admin/               后台目录（目录名可通过 ADMIN_DIR 修改）
│   ├── index.php        后台入口（登录校验、IP 网关、路由分发）
│   ├── controllers/     后台控制器（命名空间 adminc\）
│   ├── views/           后台视图
│   └── assets/          后台静态资源（KindEditor / UEditor 编辑器）
├── app/
│   ├── Core/            框架核心（Controller、Database、Model、View、Router、Helper、
│   │                    Plugin、Hook、Log、Mailer、Watermark、StaticHtml、Updater、
│   │                    Captcha、GuestbookTag 等）
│   └── plugins/         插件目录（内置相册插件 album；插件系统基础 SQL）
├── controller/          前台控制器（命名空间 controller\）
├── model/               数据模型（继承 \qbcms\Core\Model）
├── template/            前台主题目录，每套主题一个子目录（默认主题 default，通过
│                        DEFAULT_TEMPLATE 切换，主题可自带 member/ 覆盖会员中心模板）
├── static/              静态资源与静态 HTML 生成目录（common/、member/、vendor/ 及生成页面）
├── cache/               缓存目录（模板编译、轮播、标签等缓存）
├── data/                数据目录（SQLite 数据库等，受防护文件保护，禁止直接 HTTP 访问）
├── uploads/             上传目录（图片、附件、头像等，受防护文件保护，禁止脚本执行）
└── install/             安装向导（安装完成建议删除）
```

## 配置说明

`config.php` 由安装程序生成，常用常量如下：

| 常量                                                                       | 含义             | 说明                                            |
| ------------------------------------------------------------------------ | -------------- | --------------------------------------------- |
| `DB_TYPE`                                                                | 数据库类型          | `sqlite` 或 `mysql`                            |
| `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASS` / `DB_CHARSET` | MySQL 连接配置     | 仅 MySQL 模式使用                                  |
| `DB_SQLITE_PATH`                                                         | SQLite 数据库文件路径 | 默认 `data/qbcms.db`，自定义后缀时为 `data/qbcms_后缀.db` |
| `DB_PREFIX`                                                              | 数据表前缀          | 默认 `qbcms_`                                   |
| `ADMIN_DIR`                                                              | 后台目录名          | 可改为 `manage`、`houtai` 等                       |
| `DEFAULT_TEMPLATE`                                                       | 默认前台主题         | 默认 `default`                                  |
| `DEBUG_MODE`                                                             | 调试模式           | 生产环境建议设为 `false`，避免错误信息外泄                     |
| `SITE_URL`                                                               | 站点地址           | 留空时自动识别                                       |
| `URL_REWRITE`                                                            | 是否开启伪静态        | 开启后 `url()` 等生成伪静态链接，需服务器配置对应重写规则             |
| `QBCMS_VERSION`                                                          | 当前版本号          | `1.2.0`                                       |

其余 `APP_PATH`、`CACHE_PATH`、`UPLOAD_PATH`、`INSTALL_PATH`、`ROOT_PATH`、`STATIC_PATH`、`TEMPLATE_PATH`、`MEMBER_TEMPLATE_PATH` 为路径常量，一般无需修改。

## 前台路由与 URL

系统支持伪静态 URL 与查询字符串两种形式。开启 `URL_REWRITE` 并配置重写规则后，主要 URL 如下：

| URL                                                                                                             | 说明                 | 控制器                                 |
| --------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------- |
| `/`                                                                                                             | 首页                 | `Home@index`                        |
| `/list-1.html`、`/list/1`、`/栏目别名/`                                                                               | 栏目列表               | `List@index`                        |
| `/article-1.html`、`/article/1`                                                                                  | 文章详情               | `Article@index`                     |
| `/page/别名/`                                                                                                     | 单页                 | `Page@show`                         |
| `/topic/`、`/topic/别名/`                                                                                          | 专题列表 / 专题详情        | `Topic@index` / `Topic@show`        |
| `/tag/`、`/tag/标签名/`                                                                                             | 标签云 / 标签文章列表       | `Tag@cloud` / `Tag@lists`           |
| `/album.html`、`/album-1.html`、`/photo-1.html`                                                                   | 相册封面 / 相册详情 / 单图浏览 | `Album@index` / `Photo@index`（相册插件） |
| `/guestbook.html`                                                                                               | 留言板                | `Guestbook@index`                   |
| `/search/关键词/`                                                                                                  | 站内搜索               | `Search@index`                      |
| `/member/login`、`/member/register`、`/member/dashboard`、`/member/profile`、`/member/comments`、`/member/guestbook` | 会员中心               | `Member`                            |
| `/contribution/list`、`/contribution/create`                                                                     | 会员投稿               | `Contribution`                      |
| `?c=Sitemap`                                                                                                    | 生成 `sitemap.xml`   | `Sitemap@index`                     |
| `?c=Api&a=...`                                                                                                  | 动态数据 API           | `Api`                               |
| `/link/apply/`                                                                                                  | 友情链接申请             | `Link@apply`                        |

## 模板引擎与标签

前台使用自研模板引擎（`app/Core/View.php`），支持 `{qbcms:}` 专属标签、`{include:}` 模板包含、`{var:}` / `{raw:}` 变量输出、`{if}` / `{foreach}` 条件与循环语法，以及 `[field:xxx]` 字段占位符。

常用标签示例：

| 标签                                       | 用途             | 常用参数                                      | 示例                                   |
| ---------------------------------------- | -------------- | ----------------------------------------- | ------------------------------------ |
| `{qbcms:arclist}`                        | 文章列表，最常用内容标签   | `cid`、`tid`、`num`、`by`、`order`、`page`     | `{qbcms:arclist cid="1" num="10"}`   |
| `{qbcms:article}`                        | 单篇文章           | `id`                                      | `{qbcms:article id="1"}`             |
| `{qbcms:catlist}`                        | 栏目列表           | `pid`、`num`                               | `{qbcms:catlist pid="0" num="10"}`   |
| `{qbcms:category}`                       | 单个栏目           | `id`                                      | `{qbcms:category id="1"}`            |
| `{qbcms:slider}`                         | 轮播图            | `name`、`id`                               | `{qbcms:slider name="首页Banner"}`     |
| `{qbcms:linklist}`                       | 友情链接           | `gid`、`num`                               | `{qbcms:linklist gid="0"}`           |
| `{qbcms:tagcloud}`                       | 标签云            | `num`                                     | `{qbcms:tagcloud num="30"}`          |
| `{qbcms:topiclist}`                      | 专题列表           | `num`                                     | `{qbcms:topiclist num="10"}`         |
| `{qbcms:topic}`                          | 单个专题           | `id`                                      | `{qbcms:topic id="1"}`               |
| `{qbcms:page}`                           | 单页内容           | `id`、`alias`                              | `{qbcms:page alias="about"}`         |
| `{qbcms:guestbook}`                      | 留言列表           | `num`                                     | `{qbcms:guestbook num="10"}`         |
| `{qbcms:guestbook_form}`                 | 留言表单           | `class`                                   | `{qbcms:guestbook_form}`             |
| `{qbcms:custom}`                         | 自定义标签（后台配置）    | `name`                                    | `{qbcms:custom name="hot_articles"}` |
| `{include:header.html}`                  | 包含模板（最多 3 层嵌套） | `file`                                    | `{include:header.html}`              |
| `{qbcms:site_name}` 等                    | 站点变量           | `site_name`、`site_logo`、`site_keywords` 等 | `{qbcms:site_name}`                  |
| `{var:xxx}` / `{raw:xxx}`                | 输出控制器变量        | `page_title`、`pagination`、`breadcrumb` 等  | `{var:page_title}`                   |
| `{if $var}` / `{foreach $list as $item}` | 条件分支 / 循环      | —                                         | `{if $is_top}...{else}...{/if}`      |
| `[field:xxx length=N]`                   | 字段占位符（可截字）     | `length`                                  | `[field:title length=20]`            |
| `{var:pagination}`                       | 分页栏            | —                                         | `{var:pagination}`                   |

后台「模板标签 → 标签手册」内置全部标签参数与示例的可视化文档；「标签生成器」可交互式生成标签代码；「自定义标签」支持在后台配置数据源、条件与模板，并支持标签级缓存。

## 插件系统

- 插件存放于 `app/plugins/`，每个插件一个子目录，包含 `plugin.json`（名称、标题、版本、依赖、权限声明、后台菜单、hooks）与 `Plugin.php`（继承 `\qbcms\Core\Plugin`）；
- `PluginManager` 负责扫描插件、安装（执行 SQL）、启用/停用（`enabled.flag`）、卸载（执行 uninstall SQL）以及 ZIP 包上传安装，支持依赖检测与版本兼容检查；
- 提供 Hook 事件中心（Action / Filter，类似 WordPress），核心在关键点触发事件，插件注册回调实现扩展；插件也可通过 hooks 注册自定义模板标签；


- 内置「相册」插件示例：提供相册/相册照片数据表、相册与图片管理、私密相册（仅会员可见）、前台 `{qbcms:album}` 挂件、后台菜单与 `plugin.album.*` 权限点。

## 后台管理

后台按业务分组的两级菜单（以通用版本为准）：

- **控制台**：仪表盘
- **内容中心**：栏目管理、发表文章、文章管理、专题管理、单页管理、标签管理、投稿审核、回收站
- **会员互动**：会员管理、会员角色、评论管理、留言管理、留言设置、留言类别
- **站点展示**：轮播图管理、友情链接、链接分组
- **系统工具**：网站设置、日志管理、Hook 调试、数据库备份、静态 HTML、上传管理、应用中心、系统更新
- **管理权限**：管理员账号、管理角色
- **模板标签**：标签手册、标签生成器、自定义标签、模板编辑

权限体系为「管理员账号 — 管理角色 — 权限点」三级 RBAC，后台控制器通过 `hasPermission('perm_key')` 控制操作权限，菜单按权限自动隐藏。

## 安全机制

- **目录防护**：根目录 `.htaccess` / `web.config` 禁止访问 `config.php`、敏感扩展名（`sql/db/sqlite/log/md/lock/bak/env/ini/yml/yaml` 等）与目录列表；`data/`、`uploads/` 目录另有防护文件（安装时自动生成/补齐），阻止数据库文件与上传目录脚本被直接 HTTP 访问；
- **认证安全**：管理员与会员密码均使用 `password_hash` 存储、`password_verify` 校验；后台登录默认开启验证码；支持后台 IP 黑白名单；后台目录名可自定义防扫描；
- **请求安全**：会话统一安全参数并生成 CSRF Token，写操作校验；前后台控制器/方法名均做白名单校验，防止类名注入；输入统一过滤、输出统一转义，模板 `{raw:}` 输出限制为控制器预渲染的安全 HTML；
- **权限安全**：RBAC 权限点控制前后台操作；支持文章会员阅读权限、私密相册等前台权限；
- **运维安全**：安装锁 `install/.installed` 阻止重复安装；安装完成自动清理 `install` 目录；`config.php` 含数据库密码等敏感信息，禁止提交到公开仓库或暴露给第三方。

## 在线升级、备份与静态化

- **系统更新**：后台「系统更新」可配置更新服务器地址，自动检测新版本（默认 24 小时降频缓存）；升级前自动备份数据库与文件，下载升级包后校验 MD5 与 manifest，覆盖时排除 `config.php`、`uploads/`、`data/`、`static/`、`cache/`、`install/` 等关键目录，并执行增量 SQL；
- **数据库备份**：后台一键备份、下载与恢复（`DatabaseBackup`）；
- **静态 HTML**：文章/栏目等变更时触发静态页面生成，输出至 `static/` 目录，Web 服务器优先命中静态文件以减少动态请求；配合前台动态数据 API 注入评论区、浏览量等实时数据。

## 二次开发

- **命名空间与自动加载**：
  | 命名空间          | 目录                   |
  | ------------- | -------------------- |
  | `qbcms\Core\` | `app/Core/`          |
  | `controller\` | `controller/`        |
  | `adminc\`     | `admin/controllers/` |
  | `model\`      | `model/`             |
  | `plugin\`     | `app/plugins/`       |
- **前台控制器**：新建 `controller\XxxController` 继承 `\qbcms\Core\Controller`，类方法即 action，通过 URL `index.php?c=Xxx&a=index&id=1` 或伪静态 `/xxx-1.html` 访问；
- **后台控制器**：新建 `adminc\XxxController`，可使用 `hasPermission()` 做权限控制，并在后台菜单中挂载；
- **模型**：继承 `\qbcms\Core\Model` 并声明 `protected $table`，即可获得常用 CRUD 能力；
- **模板标签**：可在模板引擎标签注册表扩展，或由插件通过 hooks 注册 `template_tags`；标签级缓存可通过后台自定义标签配置；
- **Hook**：使用 `\qbcms\Core\Hook` 的 Action / Filter 机制在关键点插入自定义逻辑（如通知、日志、内容过滤）；
- **数据库**：统一通过 `Database::getInstance()` 取得 PDO 单例，SQL 兼容 MySQL 与 SQLite，多库 SQL 注意使用 `{PREFIX}` 风格或按数据库类型分支。

## 许可与声明

本项目开源协议：MIT，详见仓库根目录 LICENSE 文件。
QBCMS 永久免费、开源，可免授权用于商业项目。

本软件仅供合法用途使用，按“原样”提供，不提供任何明示或默示的担保。使用者应自行承担因使用本软件产生的全部风险与后果；确保使用行为符合所在地法律法规，禁止利用本系统从事违法违规活动。安装即视为同意上述条款（详见安装程序「安装须知」）。