molong/sentcms
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

更新文档

Browse Source
This commit is contained in:
龙渊
2026-04-22 19:31:54 +08:00
parent fe524c3871
commit b5304c67b9
2 changed files with 289 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+126
View File
@@ -0,0 +1,126 @@
# AGENTS.md — SentCMS
## 项目概述
SentCMS 是基于 **ThinkPHP 6.x** 的 PHP CMS 系统。采用**单应用**架构（非 ThinkPHP 多应用模式），4 个"模块"（`admin`、`front`、`user`、`api`）是控制器命名空间，不是独立的 ThinkPHP 应用。
- **PHP** >= 7.1，**MySQL**，网站根目录 = `public/`
- 许可证：Apache-2.0
## 环境搭建
```bash
composer install # 安装依赖
cp .example.env .env # 然后编辑数据库配置、JWT 密钥、rootuid
```
- 网站文档根目录**必须**指向 `public/`。
- **必须**开启 URL 伪静态（`public/` 下已包含 Apache `.htaccess`）。
- 首次安装：访问 `http://域名/install.php`，自动建表并写入 `install.lock`。
- `index.php` 在缺少 `.env` 或 `install.lock` 时会重定向到 `install.php`。
## 架构说明
```
app/controller/{admin,front,user,api}/ ← 4 个控制器分组，各有独立 Base
app/http/middleware/ ← Admin, Api, ApiAuth, Validate
app/http/validate/{admin,api}/ ← 按控制器自动加载的验证器
app/http/form/ ← 自定义表单引擎
app/model/{addons,ads,auth,client,form,link,module,system,wechat}/
app/services/{module/,system/} ← 业务逻辑服务
app/common.php ← 全局辅助函数（is_login, is_administrator 等）
config/ ← ThinkPHP 配置（database, auth, view, addons, jwt 等）
extend/com/ ← 自定义类库（Database, Datatable, Sent 标签库, Version）
extend/doc/ ← 文档注释解析器（用于后台页面标题）
addons/{devteam,sitestat,syslogin,systeminfo}/ ← 插件系统
view/admin/ ← 后台管理模板
public/template/ ← 前台主题模板
public/static/ ← 静态资源
route/app.php ← 所有路由定义
```
### 路由系统
路由定义在 `route/app.php`，分两层：
1. **静态路由** — `Route::group('admin', ...)`、`Route::group('user', ...)`、`Route::group('api', ...)` 及前台路由。
2. **动态模型路由** — `ModuleService::registerRoute()` 从数据库读取内容模型，动态注册路由，如 `/admin/{模型名}/:function` → `admin.Content/:function`，`/{模型名}/detail-:id` → `front.Content/detail` 等。
重要：内容模型**没有**独立的控制器文件，全部映射到 `admin.Content`、`front.Content`、`user.Content`、`api.Content`，并附加 `name` 和 `model_id` 参数。
### 中间件链
| 模块 | 中间件 | 认证机制 |
|------|--------|---------|
| admin | `Validate` → `Admin` | Session（`adminInfo`），RBAC 权限通过 `sent\auth\Auth` 校验 |
| api | `Validate` → `ApiAuth` → `Api` | JWT（`sent\jwt\JWTAuth`） |
| user | 控制器层无中间件 | `user\Base::initialize()` 中 Session 检查 |
| front | 无 | 公开访问 |
- `Admin` 中间件对 AJAX 请求自动将响应转为 JSON。
- `Validate` 中间件在 **POST 请求**时自动加载 `app\http\validate\{控制器}` 对应的验证器，且仅在对应场景（scene）存在时才执行校验。
### 模板系统
- 后台视图：`view/admin/{控制器}/{操作}.html`
- 前台视图：`public/template/{主题名}/` — 主题通过系统配置（`pc_themes`、`mobile_themes`）切换
- 前台控制器模板名使用 `_` 作为分隔符：如 `front.content` → 模板 `front_content/action.html`
- 自定义 ThinkPHP 标签库 `com\Sent` 已预加载（定义在 `extend/com/Sent.php`）
- 模板路径常量：`__static__`、`__img__`、`__css__`、`__js__`、`__plugins__`、`__public__`
## 关键约定
- **超级管理员**：由环境变量 `rootuid` 决定（默认 `1`），通过 `app/common.php` 中的 `is_administrator()` 检查。
- **权限表**：`auth_group`、`auth_group_access`、`auth_rule`（可在 `config/auth.php` 中配置表名）。
- **钩子/事件**：插件钩子使用缓存（`sentcms_hooks` 缓存键），在基础控制器构造函数中通过 `Event::listenEvents()` 注册。
- **数据库表前缀**：通过 `.env` 中的 `DATABASE.PREFIX` 设置。
- 本项目**无测试、无 CI、无 Lint 工具**配置。
- **无构建步骤** — 传统 PHP 应用，静态资源直接对外服务。
## 常见任务
### 新增后台控制器
1. 创建 `app/controller/admin/{Name}.php`，继承 `app\controller\admin\Base`。
2. 创建视图目录 `view/admin/{name}/`。
3. 路由自动匹配：`admin/{name}/{action}`。
4. 在 `auth_menu` 表中添加菜单项以显示在后台侧边栏。
### 新增 API 接口
1. 在 `app/controller/api/{Name}.php` 中添加方法，继承 `app\controller\api\Base`。
2. 路由自动匹配：`api/{name}/{action}`。
3. 默认启用 JWT 认证（`login`/`register` 除外）。
### 新增内容模型
1. 通过后台管理界面创建模型 → 自动注册动态路由。
2. 内容路由映射到 `admin.Content`、`front.Content`、`user.Content`、`api.Content`。
3. 模型属性定义存储在数据库（`model_attribute` 表）中。
### 新增插件
1. 创建 `addons/{name}/` 目录，包含 `controller/Admin.php`、可选的 `controller/Index.php` 和 `view/` 模板。
2. 在 `addons` 配置和数据库表中注册。
## 环境变量（.env）
关键变量（参见 `.example.env`）：
- `APP_DEBUG` — 调试模式
- `VERSION` — 后台显示的版本号
- `rootuid` — 超级管理员用户 ID
- `DATABASE.*` — MySQL 连接（type, hostname, database, username, password, hostport, charset, prefix）
- `JWT.SECRET` — JWT 签名密钥
## 注意事项
- **勿删** `install.lock` — 它阻止安装程序被重复访问。
- **勿提交** `.env` — 已在 `.gitignore` 中忽略。
- `composer.lock` 同样已忽略 — 每次 `composer install` 重新生成。
- `runtime/` 目录需要对 Web 服务器可写（缓存、日志、会话、备份）。
- `public/uploads/` 目录需可写以支持文件上传。
- 前台主题模板在 `public/template/`，**不在** `view/` — 这点容易搞混。
- 项目根目录的 `view/` 仅存放后台模板和插件视图。
- 内容模型控制器是虚拟的（全部路由到 `Content` 控制器）——不要去找按模型名命名的控制器文件。
- 后台 `Base` 控制器在 `initialize()` 中定义了 `IS_ROOT` 常量 — 在所有后台控制器中可用。
README.md
+163 -90
View File
@@ -1,100 +1,173 @@
## SentCMS介绍 # SentCMS
> SentCMS网站管理系统是南昌腾速科技有限公司倾力打造的一款简单易用的网站管理系统，SentCMS网站管理系统（下文简称SentCMS）继承了thinkphp的优秀品质，秉承“大道至简”的设计理念。SnetCMS为网站建设而生，为网站建设减少90%的代码编写，只需前端设计师就可以设计出完美的网站，而如此完美的系统还是完全开源的。
SentCMS 是基于 **ThinkPHP 6.x** 的内容管理系统，采用单应用架构，通过控制器命名空间划分四个模块：后台管理（admin）、前台展示（front）、用户中心（user）、API接口（api）。
> 由南昌腾速科技有限公司开发维护，遵循 Apache-2.0 开源协议。
## 环境要求 ## 环境要求
生产环境建议Linux+Nginx+php+mysql | 依赖 | 版本 |
建议PHP7+ |------|------|
| PHP | >= 7.1 |
| MySQL | 5.5+ |
| 扩展 | pdo_mysql, mbstring, json, openssl, tokenizer |
生产环境推荐：Linux + Nginx + PHP-FPM + MySQL。
## 快速安装
```bash
# 克隆项目
git clone https://gitee.com/sentcms/sentcms.git sentcms
cd sentcms
# 安装依赖
composer install
# 配置环境变量
cp .example.env .env
# 编辑 .env 文件，填写数据库连接信息
```
将网站根目录指向 `public/`，然后访问 `http://你的域名/install.php` 完成安装。
> **URL 伪静态必须开启**，否则路由无法正常工作。Apache 用户使用 `public/.htaccess`，Nginx 用户需自行配置 rewrite 规则。
## 目录结构
```
├─ addons/ 扩展插件目录
├─ app/ 应用核心代码
│ ├─ controller/ 控制器
│ │ ├─ admin/ 后台管理控制器（权限控制、RBAC）
│ │ ├─ api/ API 接口控制器（JWT 认证）
│ │ ├─ front/ 前台展示控制器（公开访问）
│ │ └─ user/ 用户中心控制器（Session 认证）
│ ├─ http/ HTTP 服务层
│ │ ├─ form/ 自定义表单引擎
│ │ ├─ middleware/ 中间件（Admin, Api, ApiAuth, Validate）
│ │ └─ validate/ 自动验证器
│ ├─ model/ 数据模型（按业务域分目录）
│ ├─ services/ 业务逻辑服务层
│ └─ common.php 全局辅助函数
├─ config/ 应用配置文件
├─ extend/ 自定义类库
│ ├─ com/ Database, Datatable, Sent 标签库, Version
│ └─ doc/ 文档注释解析器
├─ public/ 网站根目录（对外访问）
│ ├─ static/ 静态资源（CSS/JS/图片/插件）
│ ├─ template/ 前台主题模板目录
│ ├─ uploads/ 上传文件目录
│ ├─ index.php 入口文件
│ └─ install.php 安装向导
├─ route/
│ └─ app.php 路由定义（含动态内容模型路由）
├─ view/ 后台视图模板
│ └─ admin/ 后台管理界面模板
├─ runtime/ 运行时目录（缓存/日志/会话/备份）
├─ .example.env 环境配置模板
└─ composer.json Composer 依赖配置
```
## 核心特性
- **单应用架构** — 四个模块通过控制器命名空间 `app\controller\{admin,front,user,api}` 划分，非 ThinkPHP 多应用模式
- **动态内容模型** — 通过后台创建内容模型，自动注册路由，所有内容类型共用 `Content` 控制器
- **RBAC 权限系统** — 基于节点的权限控制，权限细化到按钮级别，支持超级管理员（`rootuid` 配置）
- **JWT API 认证** — API 模块使用 JWT Token 认证，支持跨域访问
- **插件系统** — 通过 `addons/` 目录扩展功能，支持钩子事件机制
- **自定义表单引擎** — `app/http/form/` 提供灵活的表单构建能力
- **多主题支持** — 前台模板位于 `public/template/`，支持 PC/移动端主题自动切换
- **自定义标签库** — `com\Sent` ThinkPHP 标签库，预加载到模板引擎
## 认证机制
| 模块 | 认证方式 | 说明 |
|------|---------|------|
| admin | Session + RBAC | `Admin` 中间件，Session 存储于 `adminInfo`，权限通过 `sent\auth\Auth` 校验 |
| api | JWT Token | `ApiAuth` 中间件，Token 过期返回 code 2001，无效返回 code 2000 |
| user | Session | `user\Base::initialize()` 中检查登录状态，未登录重定向至登录页 |
| front | 无 | 公开访问 |
## 环境变量说明
编辑 `.env` 文件（从 `.example.env` 复制）：
```ini
APP_DEBUG = false # 调试模式
VERSION = 4.0.5 # 版本号（后台展示）
rootuid = 1 # 超级管理员用户 ID
[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = your_database
USERNAME = root
PASSWORD = your_password
HOSTPORT = 3306
CHARSET = utf8
PREFIX = sent_ # 表前缀
[JWT]
SECRET = your_jwt_secret # JWT 签名密钥
```
## 主要依赖
| 包名 | 用途 |
|------|------|
| topthink/framework ^6.0 | ThinkPHP 核心框架 |
| sent/think-auth ^1.2 | RBAC 权限管理 |
| sent/think-jwt ^1.0 | JWT 认证 |
| sent/think-addons ^1.0 | 插件系统 |
| overtrue/wechat ^4.2 | 微信 SDK |
| topthink/think-captcha ^3.0 | 验证码 |
| liliuwei/thinkphp-jump ^1.4 | 控制器跳转 trait |
## 开发指南
### 新增后台控制器
1. 创建 `app/controller/admin/{Name}.php`，继承 `app\controller\admin\Base`
2. 创建对应视图目录 `view/admin/{name}/`
3. 路由自动匹配：`admin/{name}/{action}`
4. 在 `auth_menu` 数据表中添加菜单项
### 新增 API 接口
1. 在 `app/controller/api/{Name}.php` 中添加方法，继承 `app\controller\api\Base`
2. 路由自动匹配：`api/{name}/{action}`
3. 默认启用 JWT 认证（`login`/`register` 除外）
### 新增内容模型
通过后台管理界面创建 → 系统自动注册动态路由。内容模型统一映射到 `Content` 控制器处理。
### 新增插件
1. 创建 `addons/{name}/` 目录，包含 `controller/Admin.php` 和 `view/` 模板
2. 在 `addons` 配置和数据库表中注册
## 注意事项
- **勿删** `install.lock` — 它是安装锁文件，防止重复安装
- **勿提交** `.env` — 已在 `.gitignore` 中忽略
- `composer.lock` 已忽略 — 每次需 `composer install` 重新生成
- `runtime/` 和 `public/uploads/` 目录需可写权限
- 前台模板在 `public/template/` 而非 `view/`（`view/` 仅存放后台模板）
- 内容模型控制器是虚拟的，所有路由映射到 `Content` 控制器
## 在线预览 ## 在线预览
demo： http://www.sentcms.com/ - 演示地址：http://www.sentcms.com/
- 账号：admin / admin888（请勿修改密码或删除数据）
- 交流社区：http://bbs.sentcms.com
账号：admin ## 版本历史
密码：admin888 (大家手下留情，不要去改密码和删除数据！！！！！)
## 安装 - **4.x**（当前）：https://gitee.com/sentcms/sentcms — 基于 ThinkPHP 6.x
- **3.x**：历史版本，基于 ThinkPHP 3.x/5.x
为了保证系统的安全性，系统根目录移至public目录下，把程序和逻辑代码放到根目录以外。在配置网站时，把网站根目录指向web目录下，然后通过composer把所需的扩展类库更新，包括thinkphp框架同样通过composer进行更新。 ## 许可证
> 最好是使用云主机进行安装，虚拟主机有很多局限性 [Apache-2.0](LICENSE.txt)
```
git clone https://gitee.com/sentcms/sentcms.git sentcms
cd sentcms
```
> 如果是直接下载压缩包则直接进入解压文件夹，然后执行下面的代码
```
composer install
```
访问网址：http://网址/install.php
> 系统必须开启伪静态、
> 系统必须开启伪静态、
> 系统必须开启伪静态、
>（重要的事情说三篇）
## 交流讨论
> * 点击链接加入圈子：http://bbs.sentcms.com
[![](qrcode.png)](http://bbs.sentcms.com)
## SentCMS特性包括：
* 全新的路由体系，完美的路由解决方案
* 全新的系统架构，采用thinkphp6.0.* 内核框架
* 完善而健全的会员体系
* 健全的权限系统，权限细化到界面上的按钮和链接
* 漂亮的后台界面，后台界面采用世界领先的前端框架bootstrap，自适应的体验
* 简单易用的标签体系
* 便捷的文档系统，无需程序即可设计出完美的模型，做出完美的网站，传送门：http://www.kancloud.cn/tensent/sentcms4（未完成）
下载最新版框架后，解压缩到sentcms目录下面，可以看到初始的目录结构如下：
## 目录结构
~~~
├─addons 扩展插件目录
├─app 项目目录文件
│ ├─controller 控制器文件
│ │ ├─admin 网站后台控制器文件夹
│ │ ├─api 网站API控制器文件夹
│ │ ├─user 网站用户中心控制器文件夹
│ │ ├─front 网站前台控制器文件夹
│ │ ├─Base.php 网站控制器基类
│ │ ├─Upload.php 网站文件上传控制器
│ ├─http HTTP服务
│ │ ├─form 表单控件文件夹
│ │ ├─middleware 中间件文件夹
│ │ ├─validate 验证类文件夹
│ ├─model 模型文件
│ │ ├─Member.php 用户模型
│ │ ├─ …………
│ ├─common.php 公共函数库文件
│ │ ├─ …………
├─runtime 缓存以及备份目录
├─extend 自定义类库扩展目录
├─vendor 网站扩展类库目录，通过composer更新下载的类库扩展在此目录
├─public 网站根目录
│ ├─static 静态文件文件夹
│ ├─uploads 上传文件目录
│ ├─template 网站主题模板目录
│ ├─.htaccess Apache下伪静态文件
│ ├─favicon.ico ico图标
│ ├─index.php 入口文件
├─.example.env 系统配置模板
├─composer.json composer配置文件
├─README.md 系统介绍文件
~~~
## 版本列表
> 4.0 https://gitee.com/sentcms/sentcms
> 3.2： https://git.oschina.net/sentcms/sentcms/repository/archive/3.2
> 3.0.1804： https://git.oschina.net/sentcms/sentcms/repository/archive/3.0.1804
> 3.0.1707： https://git.oschina.net/sentcms/sentcms/repository/archive/3.0.1707
> 3.0.161201：https://git.oschina.net/sentcms/sentcms/repository/archive/3.0.161201