# candy cms

**Repository Path**: candy_7/candy-cms

## Basic Information

- **Project Name**: candy cms
- **Description**: candy cms 通用框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Candy CMS

<p align="center">
  <strong>轻量、现代、开箱即用的后台管理 CMS</strong><br>
  ThinkPHP 6.1 · Vue 3 · Vite · Element Plus · MySQL 8 · PHP 7.4+
</p>

<p align="center">
  <img src="https://img.shields.io/badge/PHP-%E2%89%A5%207.2.5-777bb4?logo=php&logoColor=white" alt="php" />
  <img src="https://img.shields.io/badge/ThinkPHP-6.1-3fa7dc" alt="thinkphp" />
  <img src="https://img.shields.io/badge/Vue-3.5-42b883?logo=vue.js&logoColor=white" alt="vue" />
  <img src="https://img.shields.io/badge/Vite-6.x-646cff?logo=vite&logoColor=white" alt="vite" />
  <img src="https://img.shields.io/badge/MySQL-8.0-4479a1?logo=mysql&logoColor=white" alt="mysql" />
  <img src="https://img.shields.io/badge/License-MIT-green" alt="license" />
</p>

---

## 目录

- [项目简介](#项目简介)
- [核心特性](#核心特性)
- [技术栈](#技术栈)
- [环境要求](#环境要求)
- [目录结构](#目录结构)
- [安装向导（推荐）](#安装向导推荐)
- [手动安装](#手动安装)
- [开发指南](#开发指南)
- [权限体系](#权限体系)
- [文件上传](#文件上传)
- [邮件与验证码](#邮件与验证码)
- [数据库维护中心](#数据库维护中心)
- [部署](#部署)
- [常见问题](#常见问题)
- [重装 / 卸载](#重装--卸载)
- [License](#license)

---

## 项目简介

**Candy CMS** 是一个前后端分离的通用后台管理系统骨架，聚焦"最少配置、最短上手时间"。核心工作流：

1. 浏览器打开 `install.php` → 走 5 步图形化向导（自检、连库、导入、建管理员、写入）
2. `.env` 与 `config/database.php` 自动填充
3. Vue 3 后台管理界面登录后即用

它遵循**分层清晰、约定优于配置**的思路：后端用 ThinkPHP 6.1，前端 Vue 3 + Vite 独立打包为 SPA，通过 `/api/*` 走后端。

---

## 核心特性

- 🧙 **图形化安装向导** — 5 步走完 PHP 自检、连库、建库、导表、建管理员、写 `.env`，全程无需命令行
- 🔐 **RBAC 权限 + 按钮级授权** — 参照 candy_bbs 权限模型：菜单 → 功能按钮 → 角色分配，接口自带 `checkAuth()` 拦截
- 🎨 **多主题 + 多布局** — Admin / Top / Mix 三种布局在线切换，主题色一键换肤
- 📧 **登录验证码** — 支持关闭 / 图片验证码 / 邮箱验证码三种模式，后台可视化切换
- 🔑 **用户名 或 邮箱登录** — 同一个入口两种账号策略，密码采用 `md5(md5(pwd)+salt)` 加盐
- ☁️ **多云存储** — 上传目标可切换 本地 / 阿里云 OSS / 又拍云 / 七牛云，所有 `upload()` 走同一入口，配置驱动
- 🧰 **数据库维护中心** — 备份、导出、优化、修复、清缓存、清日志、孤儿文件清理、维护模式、定时任务、审计日志
- 🖼️ **黑客终端风格安装页** — 深黑 + 霓虹绿 + CRT 扫描线，单屏无滚动
- 🍭 **糖果 Logo 组件** — 自适应站点名与站点 Logo，无 Logo 时降级为渐变糖果 SVG
- 🚀 **前后端分离** — Vue 3 SPA + ThinkPHP API，可独立部署到 CDN + 反代

---

## 技术栈

| 层 | 选型 | 说明 |
|---|---|---|
| 后端框架 | ThinkPHP 6.1 | PSR-4 命名空间，路由/门面/ORM 齐全 |
| PHP | 7.4+ (≥7.2.5) | 需要 `pdo_mysql / mbstring / openssl / fileinfo / gd / curl / json` |
| 数据库 | MySQL 8.0 (5.7+) | 表前缀 `ca_`，字符集 `utf8mb4_unicode_ci` |
| 前端框架 | Vue 3.5 + Composition API | `<script setup>` 语法 |
| 构建 | Vite 6 | 生产打包 `web/dist` → `public/` |
| UI 库 | Element Plus 2.10 | 深色主题 & 主题变量注入 |
| 状态管理 | Pinia 2.3 | `stores/user` + `stores/layout` + `stores/tabs` |
| 路由 | Vue Router 4.5 | 动态路由（登录后按 `menu_list` 注入） |
| 富文本 | @wangeditor/editor | 公告、内容编辑 |
| 云存储 SDK | aliyuncs/oss-sdk-php | 又拍 / 七牛通过 HTTP 直传，无额外 SDK |

---

## 环境要求

| 组件 | 最低 | 推荐 | 说明 |
|---|---|---|---|
| PHP | 7.2.5 | 7.4 / 8.0 | 需开启 `pdo_mysql mbstring openssl fileinfo gd curl json` |
| MySQL | 5.7 | 8.0 | 字符集必须支持 `utf8mb4_unicode_ci` |
| Node.js | 16 | 18 / 20 | 仅前端开发需要，生产部署可不装 |
| Composer | 2.x | 2.x | 用来管理后端依赖 |
| Web Server | 内置 / Apache / Nginx | Nginx 1.18+ | 生产建议 Nginx |

**目录权限**：`runtime/`、`public/storage/`、项目根 `.env` 位置需可写。

---

## 目录结构

```
candy-cms/
├── app/                              # 后端应用代码
│   ├── BaseController.php            # 后台控制器基类（登录 + RBAC）
│   ├── controller/admin/             # 后台控制器
│   │   ├── IndexController.php       # 登录 / 初始化 / 用户切换
│   │   ├── EmployeeController.php    # 用户管理
│   │   ├── RoleController.php        # 角色 + 分配权限
│   │   ├── MenuController.php        # 菜单 + 功能按钮
│   │   ├── ConfigController.php      # 系统设置（站点、上传、邮件）
│   │   ├── DatabaseController.php    # 数据库维护中心
│   │   ├── FileController.php        # 文件库
│   │   ├── NoticeController.php      # 公告
│   │   ├── LoginLogController.php    # 登录日志
│   │   ├── OperationLogController.php# 操作日志
│   │   ├── CommonController.php      # 上传入口 / 通用接口
│   │   └── CaptchaController.php     # 图片验证码
│   ├── model/                        # ORM 模型
│   ├── service/                      # 业务服务
│   │   ├── AuthService.php           # 登录、验证码校验
│   │   ├── TokenService.php          # Token 缓存
│   │   ├── UploadService.php         # 本地/OSS/又拍/七牛统一上传
│   │   └── MailService.php           # 邮件发送
│   └── middleware/
│       └── CorsMiddleware.php        # 跨域
├── config/                           # ThinkPHP 配置
│   └── database.php                  # 数据库配置（安装后自动填充）
├── install/                          # 安装向导（安装完成后可删除）
│   ├── Installer.php                 # 安装器：连库/建表/建管理员/写 .env
│   ├── env.tpl                       # .env 模板
│   ├── version.php                   # 版本号
│   └── sql/
│       ├── schema.sql                # 表结构（12 张核心表）
│       └── seed.sql                  # 种子数据（菜单/权限/默认部门）
├── public/                           # Web 根
│   ├── index.php                     # ThinkPHP 入口
│   ├── install.php                   # 安装向导入口（GET/POST 双职能）
│   ├── install/assets/style.css      # 安装页样式（黑客终端风）
│   ├── storage/                      # 本地上传目录（可写）
│   ├── .htaccess                     # Apache 伪静态
│   └── nginx.htaccess                # Nginx 参考规则
├── route/
│   ├── app.php                       # 应用级路由（跨域预检等）
│   └── admin.php                     # 后台 API 路由
├── runtime/                          # 缓存/日志/session/备份/install.lock
├── vendor/                           # Composer 依赖（已入库，无需 install）
├── web/                              # 前端源码（独立 npm 项目）
│   ├── package.json
│   ├── vite.config.js
│   └── src/
│       ├── views/                    # 页面
│       │   ├── Login.vue             # 登录页（用户名/邮箱 + 验证码）
│       │   ├── Home.vue              # 首页
│       │   ├── sys/                  # 用户/角色/菜单/设置/数据库
│       │   ├── content/              # 文件/公告
│       │   ├── logs/                 # 登录日志/操作日志
│       │   ├── NotFound.vue
│       │   └── UnderDevelopment.vue
│       ├── components/
│       │   ├── common/SiteLogo.vue   # 统一 Logo 组件
│       │   ├── common/ThemeSwitch.vue
│       │   ├── common/LayoutSwitch.vue
│       │   └── Layout/               # AdminLayout / TopLayout / MixLayout
│       ├── stores/                   # Pinia 状态（user / layout / tabs）
│       ├── router/
│       ├── utils/                    # 请求封装 / 动态路由 / 主题
│       └── styles/                   # 全局样式 & 主题变量
├── composer.json
├── think                             # ThinkPHP 命令行入口
├── .env                              # 环境变量（未安装时为空）
└── .gitignore
```

---

## 安装向导（推荐）

> 全程图形化，无需命令行。适合 99% 场景。

### 1. 准备环境

- 确认 PHP、MySQL 已安装，PHP 扩展齐全（缺什么向导会自检提示）
- 把项目放到 Web 根（如 phpStudy → `WWW/candy-cms` 或 Nginx `root`）
- 目录 `runtime/`、`public/storage/` 需可写

### 2. 打开向导

浏览器访问：

```
http://your-host/install.php
```

> 若使用 PHP 内置服务器，先在项目目录执行：
> ```powershell
> php -S 127.0.0.1:8782 -t public
> ```
> 然后访问 <http://127.0.0.1:8782/install.php>

### 3. 5 步向导

| 步骤 | 页面 | 操作 |
|---|---|---|
| ① 环境自检 | `?step=welcome` | 显示 PHP 版本、扩展、目录权限、Composer 状态。全部 ✅ 才能继续。|
| ② 数据库配置 | `?step=db` | 填 `host / port / database / username / password / prefix`，点【测试连接】→【下一步】。若库不存在，自动 `CREATE DATABASE`（`utf8mb4_unicode_ci`）。|
| ③ 导入 SQL | `?step=sql` | 执行 `schema.sql` + `seed.sql`。勾选"清空重装"可先 `DROP` 所有 `ca_*` 表。|
| ④ 管理员账号 | `?step=admin` | 填 邮箱 / 用户名 / 密码（≥6 位）+ 站点名称/版权/备案号。密码算法：`md5(md5(pwd)+salt)`。|
| ⑤ 完成 | `?step=done` | 写入 `.env` + 同步 `config/database.php` + 生成 `runtime/install.lock`。选择"重命名保留"或"彻底删除"向导文件。|

### 4. 登录

安装完成后向导页面会出现"进入后台"入口，或直接访问：

```
http://your-host/
```

使用刚才设置的 **邮箱** 或 **用户名** + 密码登录。

### 5. 安装锁

安装完成后 `runtime/install.lock` 存在，`install.php` 会返回 **403 + 黄色警告页**，防止误触重装。

---

## 手动安装

如果偏好命令行或 CI 场景：

```powershell
# 1. 创建库
mysql -uroot -proot -e "CREATE DATABASE cms_com CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"

# 2. 导入表结构与种子
mysql -uroot -proot cms_com < install/sql/schema.sql
mysql -uroot -proot cms_com < install/sql/seed.sql

# 3. 写 .env（可从 install/env.tpl 复制修改）
notepad .env

# 4. 手动 INSERT 管理员账号（示例）
# 生成 salt = 6 位随机字符串
# 密码字段 = md5(md5(密码明文) + salt)
mysql -uroot -proot cms_com -e "INSERT INTO ca_employee (username,email,pwd,salt,did,role_id,is_login,status,addtime,create_time,update_time) VALUES ('admin','admin@example.com','xxx','xxx',1,1,1,1,NOW(),NOW(),NOW())"

# 5. 生成安装锁
echo '{"installed_at":"手动安装"}' > runtime/install.lock
```

---

## 开发指南

### 后端开发

```powershell
# 启动内置服务器（不需要 apache/nginx）
cd D:\Application\candy\candy-cms
php -S 127.0.0.1:8782 -t public

# 访问
# 后台 API: http://127.0.0.1:8782/api/*
# 安装向导: http://127.0.0.1:8782/install.php
```

后端约定：

- **控制器**：`app/controller/admin/*Controller.php`，继承 `\app\BaseController`
- **免登录**：在控制器里覆盖 `$noLoginAction = ['methodA']`
- **免鉴权**：`$noAuthAction = ['methodB']`
- **接口路径**：全部走 `route/admin.php` 显式声明，`/api/xxx/yyy` 会自动匹配 `xxxController@yyy`
- **响应**：统一 `$this->success($data)` / `$this->error($msg)`

### 前端开发

```powershell
cd web
npm install                # 首次
npm run dev                # 开发模式 (Vite 默认端口 5173，自动代理 /api → 后端 8782)
npm run build              # 生产构建 → dist/
```

前端约定：

- **视图**：`web/src/views/**/*.vue`，路径与后端菜单 `menu_url` 一一对应
- **API 封装**：`web/src/api/*.js`，统一走 `web/src/utils/request.js`
- **动态路由**：登录后拿到 `menu_list` → `web/src/utils/dynamicRoutes.js` 自动注入
- **权限指令**：`v-permission="'/sys/user/edit'"` 按 `func_list` 判断按钮是否显示

### 部署到生产

前端构建后把 `web/dist/*` 拷贝到 `public/`，`index.php` 已配置 SPA 兜底路由：

```powershell
cd web
npm run build
Copy-Item -Recurse -Force dist\* ..\public\
```

---

## 权限体系

Candy CMS 采用 **员工 → 角色 → 功能** 三段式 RBAC：

```
员工 (ca_employee)  ─┐
                    │  role_id
                    ▼
角色 (ca_role) ──┬─ is_admin=1 (超管，跳过检查)
                │
                ├─ role_func (角色-功能 多对多)
                │
                ▼
功能 (ca_func) ─── menu_url  (如 /sys/user/edit)
```

**判定流程**（`BaseController::checkCurrentAdminPermission`）：

1. 超管直接放行
2. 请求 URL → 生成候选权限键（`/api/employee/edit` → `/sys/user/edit`）
3. 拿当前角色的 `func_id` 列表 → 查 `ca_func.menu_url` 交集
4. 交集非空 = 有权限；空 = 拒绝
5. 未在权限表登记的接口默认策略：**读放行 / 写拒绝**（避免手抖漏配）

**前端按钮级授权**：

```vue
<el-button v-permission="'/sys/user/delete'" @click="handleDelete">删除</el-button>
```

指令读 `userStore.func_list` 判断是否渲染。

---

## 文件上传

**统一入口**：所有页面上传都走 `POST /api/common/upload`。

**存储驱动**：由后台【系统设置 → 上传配置】的 `upload_type` 决定，改配置立即生效，无需改代码。

| upload_type | 存储 | 需配置字段 |
|---|---|---|
| `local` | 本地 `public/storage/images/YYYY/MM/DD/` | 无 |
| `oss` | 阿里云 OSS | `bucket / accesskeyid / accesskeysecret / endpoint / oss_domain` |
| `upyun` | 又拍云 | `upyun_bucket / upyun_operator / upyun_password / upyun_domain` |
| `qiniu` | 七牛云 | `qiniu_bucket / qiniu_access_key / qiniu_secret_key / qiniu_domain` |

`UploadService::upload($file)` 内部按 `upload_type` 分派，返回统一格式 `{url, path, size}`。

---

## 邮件与验证码

**登录验证码模式**（后台【系统设置 → 安全】切换）：

| `admin_login_verify_mode` | 效果 |
|---|---|
| `none` | 关闭验证码 |
| `image` | 登录页显示图片算术验证码 |
| `email` | 登录页显示"获取邮箱验证码"按钮，60 秒频控，10 分钟有效 |

**邮件配置**（`ca_config` 表）：

- `mail_host / mail_port / mail_username / mail_password / mail_from / mail_from_name / mail_secure`
- 后台可点【测试邮件】按钮验证 SMTP 通不通

---

## 数据库维护中心

后台 **系统管理 → 数据库维护** 提供 15+ 项运维能力：

- 📦 **数据备份** — 生成 SQL 快照到 `runtime/database_backup/`
- 📤 **导出下载** — 打包 SQL 直接下载
- 🗑️ **删除备份** — 单个 / 批量清理
- 🧹 **清理日志** — 登录日志 / 操作日志 / 全部一键清；也支持按时间范围
- 🔧 **优化 & 修复表** — `OPTIMIZE TABLE` / `REPAIR TABLE`
- 💾 **清理缓存** — `runtime/cache` 全清
- 🖇️ **孤儿文件清理** — 扫描 `ca_file` 未引用的物理文件并删除
- ⚙️ **维护模式** — 开启后前台返回维护中，仅超管可访问
- 👥 **一键下线用户** — 清 Token 缓存，强制所有员工重新登录
- ⏰ **定时任务配置** — 自动备份、自动清日志的 cron 规则
- 🩺 **健康检查** — 表健康度、连接数、磁盘、慢查询
- 🔐 **权限体检 / 安全体检** — 检查僵尸账号、超管数量、弱密码等

---

## 部署

### Nginx 参考配置

```nginx
server {
    listen 80;
    server_name cms.example.com;
    root /var/www/candy-cms/public;
    index index.php index.html;

    # 上传大文件
    client_max_body_size 50m;

    # SPA 前端兜底
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 后端 API
    location /api/ {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # ThinkPHP 入口
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # 禁止访问敏感目录
    location ~ ^/(app|config|route|runtime|install|vendor)/ {
        deny all;
        return 404;
    }

    # 禁止访问 .env
    location ~ /\.env {
        deny all;
    }
}
```

### 阿里云 / phpStudy 部署清单

1. 上传整个项目到 Web 根
2. 确认 `runtime/` `public/storage/` 权限 755，属主为 www-data / iis
3. 打开 `install.php`，按向导安装
4. 安装完成后**务必勾选"删除或重命名向导"**，防止二次安装

---

## 常见问题

### Q1. 前端 SPA 刷新 404？
Nginx 里加上 `try_files $uri $uri/ /index.html;` 兜底。Apache 已在 `public/.htaccess` 配好。

### Q2. 安装向导报 "vendor/autoload.php 缺失"？
项目已带 `vendor/`，无需 `composer install`。如误删，执行：
```powershell
composer install --no-dev --optimize-autoloader
```

### Q3. 忘记管理员密码？
两种恢复方式：
```powershell
# 方式1：删掉 install.lock 重装（会清库）
Remove-Item runtime\install.lock

# 方式2：直接改数据库（推荐）
# salt = 现有 salt，pwd_new = md5(md5('新密码') + salt)
mysql -uroot -proot cms_com -e "UPDATE ca_employee SET pwd='xxxx' WHERE username='admin'"
```

### Q4. Windows 中文乱码 / `.env` 被写成 UTF-8 with BOM？
Installer 已用 `\System.Text.UTF8Encoding($false)` 强制无 BOM。若手工编辑请用 VSCode 保存为 **UTF-8 (无 BOM)**。

### Q5. 表前缀能改吗？
可以，安装向导第 2 步 `prefix` 字段填自定义（如 `xy_`），后端 `.env` 与 `config/database.php` 会同步。**注意 SQL 里 `schema.sql` 和 `seed.sql` 用的是硬编码 `ca_`**，如需彻底改前缀，请用编辑器全局替换后再安装。

### Q6. 上传 OSS / 七牛后前台不显示？
检查后台【系统设置 → 上传配置】里的 `oss_domain / qiniu_domain / upyun_domain` 是否填写了带协议的完整域名（如 `https://cdn.example.com`），且已在云服务商开启公开读。

### Q7. 生产环境要不要开 Debug？
**必须关闭**。`.env` 里设置：
```ini
APP_DEBUG = false
```

---

## 重装 / 卸载

### 完全重装

```powershell
# 1. 删除锁文件
Remove-Item D:\Application\candy\candy-cms\runtime\install.lock

# 2. 若向导已删/重命名，恢复
Rename-Item D:\Application\candy\candy-cms\install.done.xxxx D:\Application\candy\candy-cms\install
Rename-Item D:\Application\candy\candy-cms\public\install.php.done.xxxx D:\Application\candy\candy-cms\public\install.php

# 3. Drop 库（可选，向导第 3 步也能"清空重装"）
mysql -uroot -proot -e "DROP DATABASE IF EXISTS cms_com"

# 4. 打开浏览器重走向导
```

### 卸载

```powershell
# 1. Drop 库
mysql -uroot -proot -e "DROP DATABASE IF EXISTS cms_com"

# 2. 删除项目目录
Remove-Item D:\Application\candy\candy-cms -Recurse -Force
```

---

## License

MIT © Candy CMS Contributors

---

## 致谢

- [ThinkPHP](https://www.thinkphp.cn/) — 优雅的 PHP 框架
- [Vue.js](https://vuejs.org/) — 渐进式 JavaScript 框架
- [Element Plus](https://element-plus.org/) — Vue 3 组件库
- [Vite](https://vitejs.dev/) — 极速的前端构建工具
- 灵感参考项目：`candy_bbs` — 权限模型 / 数据库维护中心 / 上传抽象

> 有 bug 请开 issue，欢迎 PR ✨