# sunadmin-core--composer

**Repository Path**: sunjinglong/sunadmin-core--composer

## Basic Information

- **Project Name**: sunadmin-core--composer
- **Description**: sunadmin服务端php核心依赖库，一般无需独立安装，若要使用sunadmin完整版服务端，请使用composer create-project sunadmin命令创建完整服务端项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-18
- **Last Updated**: 2025-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 安装：

```bash
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. 导入数据库脚本：

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

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

3. 启动项目：

```bash
php think swoole
```

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

### 2.4 集成前端

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

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

[请跳转阅读后台界面文档](https://gitee.com/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 响应处理

```php
use SunAdmin\Common\ResponseJson;

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

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

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

### 4.2 Token 处理

```php
use SunAdmin\Common\TokenHelper;

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

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

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

### 4.3 文件上传

```php
use SunAdmin\Service\AttachmentService;

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

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

### 4.4 数据字典操作

```php
use SunAdmin\Service\DataDictionaryService;

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

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

### 4.5 定时任务

```php
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 服务端仓库](https://gitee.com/sunjinglong/sunadmin-server)
-   [SunAdmin 后台 UI 仓库](https://gitee.com/sunjinglong/sunadmin-admin-ui)
-   [ThinkPHP 8 官方文档](https://doc.thinkphp.cn/v8_0)
-   [Swoole 文档](https://wiki.swoole.com/)

## 7. 许可证

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