sunjinglong / sunadmin-server
SunAdmin - 基于 ThinkPHP 8 的通用后台管理系统框架
1.0.1
2025-06-16 03:25 UTC
Requires
- php: >=8.0.0
- ext-swoole: >=4.8.0
- alibabacloud/sdk: ^1.8
- sunjinglong/think-filesystem: >=3.0.21
- topthink/framework: ^8.0
- topthink/think-orm: ^3.0|^4.0
- topthink/think-swoole: ^4.1
Requires (Dev)
- phpunit/phpunit: ^9.0
This package is auto-updated.
Last update: 2025-06-16 14:12:52 UTC
README
一句命令即可安装完整的后台管理系统服务端框架!
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 配置
- 导入数据库脚本:
# 导入 vendor/sunjinglong/sunadmin-server/database/sunadmin.sql
- 配置环境变量(.env):
# SunAdmin 配置
SUNADMIN_TOKEN_SECRET=your-secret-key
SUNADMIN_TOKEN_TTL=3600
SUNADMIN_WEBSOCKET_ENABLE=true
SUNADMIN_WEBSOCKET_PORT=9501
# Redis 必须配置为缓存驱动
CACHE_DRIVER=redis
- 启动项目:
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. 注意事项
- SunAdmin 需要在 Swoole 环境下运行,不支持传统的 PHP-FPM 模式
- 缓存驱动必须设置为 Redis
- 文件上传功能依赖于正确配置的存储驱动
- 前后端需要配套使用,确保API接口匹配
6. 相关链接
7. 许可证
SunAdmin 框架采用 MIT 许可证,详见 LICENSE 文件。