SunAdmin 通用后台管理系统框架

一句命令即可安装完整的后台管理系统服务端框架！

1. 介绍

SunAdmin 是一个基于 ThinkPHP 8 开发的通用后台管理系统框架，旨在帮助开发者快速构建管理后台，避免重复开发基础功能，专注于业务逻辑的实现。

1.1 开发目的

• 一句命令安装：通过简单的 composer 命令即可获得完整后台框架
• 零侵入性：作为独立的 composer 包，对宿主项目无任何侵入性
• 便捷更新：版本更新只需更改依赖版本号，无需修改现有代码
• 提供完整的后台管理基础功能
• 简化管理系统的开发流程
• 统一管理后台的界面风格与体验
• 提高开发效率，降低维护成本

1.2 为什么开发成独立的包？

• 便于安装：一句命令即可完成安装，无需复杂配置
• 无侵入性：作为独立包引入，不会污染宿主项目的代码结构
• 便捷更新：只需修改版本号即可获取最新功能和安全修复
• 跨项目复用：可在多个项目中使用相同的管理系统
• 统一维护：集中维护一套代码，确保各项目使用相同标准

1.3 技术栈

后端技术栈：

• PHP 8.0+
• ThinkPHP 8.0
• Swoole 4.8+
• Redis

前端技术栈：

• Vue 3
• Element Plus
• @sunjinglong/sunadmin-admin-ui (配套的前端 UI 组件库)

2. 使用方式

2.1 安装

只需一句命令，即可拥有完整的后台管理系统服务端框架！

通过 Composer 安装：

composer require sunjinglong/sunadmin-server

注意：tp8 某些版本所以来的"topthink/think-filesystem"版本太低，需要 3.0 以上，如果小于 3.0 请改为"topthink/think-filesystem": "^3.0"

2.2 环境要求

• PHP >= 8.0
• Swoole >= 4.8.0
• Redis 服务
• MySQL/MariaDB 数据库

2.3 配置

1. 导入数据库脚本：

# 导入 vendor/sunjinglong/sunadmin-server/database/sunadmin.sql

2. 配置环境变量（.env）：

3. 启动项目：

php think swoole

⚠️ 重要提示: SunAdmin 强烈依赖 Swoole 环境，必须使用 php think swoole 命令启动项目！

2.4 集成前端

SunAdmin 提供配套的前端 UI 框架，同样只需一句命令即可安装：

npm install @sunjinglong/sunadmin-admin-ui
# 或
pnpm add @sunjinglong/sunadmin-admin-ui

请跳转阅读后台界面文档

3. 封装功能

SunAdmin 框架封装了以下核心功能，全部开箱即用，无需额外开发：

3.1 管理员账号体系

• 完整的管理员账号管理
• 基于角色的权限控制
• 菜单权限动态分配
• 管理员在线状态监控
• 安全的登录验证与 Token 管理

3.2 菜单权限管理

• 多级菜单结构
• 权限与菜单绑定
• 动态菜单配置
• 菜单排序与显示控制

3.3 数据字典管理

• 系统配置集中管理
• 分组管理配置项
• 支持多种数据类型
• 层级结构组织配置

3.4 附件上传与管理

• 多存储驱动支持（本地、阿里云 OSS、七牛云等）
• 文件类型限制与安全检查
• 附件分类管理
• 完整的上传进度与错误处理

3.5 定时任务管理

• 可视化任务配置
• 定时任务执行日志
• 手动触发任务
• 任务执行状态监控

3.6 WebSocket 实时通信

• 基于 Swoole 的 WebSocket 服务
• 实时系统通知
• 在线用户状态同步
• 服务端推送消息

3.7 系统监控

• 服务器资源监控
• 系统运行状态
• 性能指标采集
• 异常事件记录

4. 公用方法

SunAdmin 提供了一系列公用方法，用于快速开发：

4.1 响应处理

use SunAdmin\Common\ResponseJson;

// 成功响应
ResponseJson::success($data, '操作成功');

// 错误响应
ResponseJson::error('操作失败', 400);

// 未授权响应
ResponseJson::unauthorized('登录已过期');

4.2 Token 处理

use SunAdmin\Common\TokenHelper;

// 生成Token
$token = TokenHelper::generateToken($accountInfo);

// 验证Token
$isValid = TokenHelper::verifyToken($token);

// 获取Token信息
$tokenData = TokenHelper::getTokenInfo($token);

4.3 文件上传

use SunAdmin\Service\AttachmentService;

// 上传文件
$fileInfo = AttachmentService::upload($file, 'aliyun');

// 获取文件URL
$url = AttachmentService::getFileUrl($path, 'aliyun');

4.4 数据字典操作

use SunAdmin\Service\DataDictionaryService;

// 获取配置
$value = DataDictionaryService::getValue('system_name');

// 设置配置
DataDictionaryService::setValue('system_name', 'My System');

4.5 定时任务

use SunAdmin\Service\TimerTaskService;

// 注册任务
TimerTaskService::registerTask('daily_backup', '0 0 * * *', 'App\Tasks\BackupTask');

// 执行任务
TimerTaskService::executeTask($taskId);

5. 注意事项

1. SunAdmin 需要在 Swoole 环境下运行，不支持传统的 PHP-FPM 模式
2. 缓存驱动必须设置为 Redis
3. 文件上传功能依赖于正确配置的存储驱动
4. 前后端需要配套使用，确保 API 接口匹配

6. 相关链接

• SunAdmin 服务端仓库
• SunAdmin 后台 UI 仓库
• ThinkPHP 8 官方文档
• Swoole 文档

7. 许可证

SunAdmin 框架采用 MIT 许可证，详见 LICENSE 文件。