系统介绍

深入了解 XPCMS（小彭CMS）的系统架构、核心特性与技术选型

一、什么是 XPCMS

XPCMS（小彭CMS）是一款自主研发、完全开源的轻量级多应用内容管理系统，由彭浩独立开发。系统基于 ThinkPHP 8 框架构建，采用多应用架构设计，内置自研 XPUI 前端组件库，支持多主题切换、RBAC 权限管理、RESTful API 接口、插件扩展等企业级功能。

系统核心设计理念：

轻量高效：核心代码精简，运行速度快，适合中小型项目快速落地
自研可控：XPUI 自研前端框架，不依赖任何第三方 UI 库
双端架构：tp 控制端完整版 + tp-pure 客户纯净版，满足不同场景需求
开箱即用：内置文章/产品/视频/素材/社区/文档/广告/友链等丰富内容模块
规范驱动：严格的代码规范体系，AI 辅助开发零学习成本

二、核心特性

📝 内容管理

文章/产品/视频/素材/单页/文档六大内容模块，完整 CRUD + 状态流转，支持多分类、标签关联、封面图、附件下载

👥 RBAC 权限

公司→部门→角色→权限四级层级，超管角色自动放行，权限码格式统一为 {module}_{action}，中间件全拦截

🎨 多主题

前后台独立主题切换，在线安装/卸载 ZIP 主题包，ThemeService 动态加载，默认主题自动回退保护

🔌 RESTful API

xpapi 独立应用，66 条标准 RESTful 路由，JWT HS256 双 Token 认证，access 2h + refresh 7d

🧩 自研 XPUI

11 CSS + 22 JS 纯原生组件库，XpCore/XpToast/XpModal/XpForm/XpTable/XpUpload 完整前端体系

🔄 系统更新

在线 ZIP 更新包上传→解析→确认→安装四步流程，自动备份原文件，路径白名单+黑名单双重保护

💬 社区论坛

多板块帖子+评论+点赞+收藏，Markdown 编辑器，帖子状态审核流程，会员积分体系

🛡️ 安全防护

CSRF 双验证（Header+POST）、XSS 过滤、SQL 注入防御、密码 Bcrypt 加密、登录 5 次失败锁定 30 分钟

🌐 多语言

内置多语言支持，LanguageService 统一管理，前后台独立切换，模板变量自动注入

📊 操作日志

所有 CUD 操作自动记录，变更前后数据 JSON 对比，日志只读不删，异常不影响主业务

三、技术架构

层级	技术栈	说明
后端框架	ThinkPHP 8	PSR-4 自动加载，多应用模式（admin/index/xpapi/install）
数据库	MySQL 5.7+	InnoDB 引擎，utf8mb4 字符集，表前缀 xp_
前端样式	Tailwind CSS	优先使用原子化 CSS，减少自定义样式
UI 框架	XPUI 自研	唯一 UI 框架，禁止引入任何第三方 UI
模板引擎	ThinkPHP 模板	原生标签 + 自定义扩展（volist/if/php）
接口规范	RESTful JSON	统一返回 `{code:200, msg:"成功", data:{}}`
缓存驱动	File / Redis	CacheService 统一封装，支持分布式锁、标签分组、预热
认证方式	Session + JWT	后台 Session + Remember Token，API 端 JWT HS256
图标库	Font Awesome 5	免费版图标，CSS 引入
PHP 版本	PHP 8.0+	强类型声明 declare(strict_types=1)

四、应用体系

应用	入口路径	功能说明
admin	/admin	后台管理系统：iframe 框架布局，RBAC 权限管控，系统设置，内容管理，主题/插件/更新推送，操作日志
index	/	前台官网：主题渲染引擎，公开访问，文章/产品/视频/素材/文档展示，社区论坛，会员中心，搜索
xpapi	/api	RESTful API 接口：JWT 无状态认证，66 条标准路由，支持第三方客户端接入、小程序对接、前后端分离
install	/install	安装向导：首次部署时自动检测，引导配置数据库连接和管理员账号

五、双端架构

项目采用双目录独立维护架构，两套代码共享数据库：

对比维度	tp（控制端完整版）	tp-pure（客户纯净版）
定位	开发/管理/测试用	客户交付/生产环境
后台控制器	53 个	43 个
公用 Model	46 个	32 个（移除社区/会员/推送 13 个）
Service 层	17 个	17 个（完全一致）
中间件	4 个	4 个（完全一致）
静态资源	一致	一致
独有模块	社区论坛、会员等级积分、推送管控、开发文档展示	—
基础建站	✅ 完整	✅ 完整（与 tp 一致）

六、项目目录结构

{项目}/
├── tp/                         # 控制端完整版
│   ├── app/
│   │   ├── admin/              # 后台应用（控制器+验证器+中间件）
│   │   │   ├── controller/     # 53 个控制器
│   │   │   ├── middleware/     # AuthCheck / LicenseCheck / PermissionCheck / ConfigCache
│   │   │   ├── validate/       # 26 个验证器
│   │   │   ├── trait/          # CurdTrait 通用 CRUD 复用
│   │   │   └── route/app.php
│   │   ├── index/              # 前台应用
│   │   │   ├── controller/     # 15 个控制器（含 FrontendConfig Trait）
│   │   │   └── middleware/     # ConfigCache / MemberAuth
│   │   ├── xpapi/              # API 应用
│   │   │   ├── controller/     # 13 个控制器（双端一致）
│   │   │   ├── middleware/     # JwtAuth
│   │   │   └── route/app.php   # 66 条 RESTful 路由
│   │   ├── common/             # 公共层（双端共享）
│   │   │   ├── model/          # 46 个数据模型
│   │   │   └── service/        # 17 个业务服务
│   │   └── middleware.php      # 全局中间件注册
│   ├── config/                 # 配置文件（18 个）
│   ├── public/
│   │   ├── static/
│   │   │   ├── xpui/           # XPUI 自研框架（11 CSS + 22 JS）
│   │   │   ├── admin/          # 后台业务静态资源
│   │   │   └── portal/         # 前台业务静态资源
│   │   └── index.php           # 入口文件
│   ├── themes/
│   │   ├── frontend/           # 前台主题
│   │   │   └── xpui-portal/    # 当前激活主题
│   │   │       ├── view/       # 视图模板
│   │   │       └── static/     # 主题静态资源
│   │   └── backend/            # 后台主题
│   └── runtime/                # 运行时目录（缓存/日志/临时文件）
├── tp-pure/                    # 客户纯净版（目录结构同 tp，基础功能一致）
└── 文档/
    ├── XPCMS（小彭CMS）系统项目开发规范 V1.0.md
    └── XPCMS项目架构熟悉文档.md