sunjinglong/sunadmin-server

SunAdmin - 基于 ThinkPHP 8 的通用后台管理系统框架

1.0.1 2025-06-16 03:25 UTC

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 配置

  1. 导入数据库脚本:
# 导入 vendor/sunjinglong/sunadmin-server/database/sunadmin.sql
  1. 配置环境变量(.env):
# SunAdmin 配置
SUNADMIN_TOKEN_SECRET=your-secret-key
SUNADMIN_TOKEN_TTL=3600
SUNADMIN_WEBSOCKET_ENABLE=true
SUNADMIN_WEBSOCKET_PORT=9501

# Redis 必须配置为缓存驱动
CACHE_DRIVER=redis
  1. 启动项目:
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. 相关链接

7. 许可证

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