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);

sunjinglong / sunadmin-server

Maintainers

Details