707 lines
16 KiB
Markdown
707 lines
16 KiB
Markdown
<div align="center">
|
||
|
||
# LarAdmin
|
||
|
||
基于 Laravel + Swoole + Vue3 的高性能后台管理系统
|
||
|
||
[](https://laravel.com)
|
||
[](https://php.net)
|
||
[](https://vuejs.org)
|
||
[](https://www.swoole.com)
|
||
[](LICENSE)
|
||
|
||
</div>
|
||
|
||
## 📖 项目简介
|
||
|
||
LarAdmin 是一个基于 Laravel 12 + Swoole + Vue3 的高性能后台管理系统，采用模块化架构设计，提供完整的认证授权、系统管理、业务扩展等功能。项目集成了 `hhxsv5/laravel-s` 实现 Swoole 长生命周期服务，大幅提升系统并发性能和响应速度。
|
||
|
||
### ✨ 核心特性
|
||
|
||
- 🚀 **高性能**：基于 Swoole 协程，支持高并发、低延迟
|
||
- 📦 **模块化**：采用 `nwidart/laravel-modules` 实现业务模块化管理
|
||
- 🔐 **完整权限**：基于 RBAC 的权限控制系统，支持用户、角色、权限、部门管理
|
||
- 🎨 **现代前端**：Vue 3 + Ant Design Vue + Vite 构建的现代化管理界面
|
||
- 📊 **数据管理**：支持数据导入导出、在线编辑、批量操作
|
||
- 🌐 **WebSocket**：内置 WebSocket 支持，实现实时通信
|
||
- 📝 **操作日志**：完整的操作日志记录和审计功能
|
||
- 🏙️ **城市数据**：内置全国省市区三级联动数据
|
||
- ⚙️ **系统配置**：灵活的系统配置管理，支持多种数据类型
|
||
- 🔄 **任务调度**：可视化的定时任务管理界面
|
||
|
||
## 🛠 技术栈
|
||
|
||
### 后端
|
||
|
||
- **PHP**: 8.2+
|
||
- **Laravel**: 12.0
|
||
- **Laravel-S**: 3.8+ (Swoole 集成)
|
||
- **Swoole**: 最新稳定版
|
||
- **JWT-Auth**: 2.2+ (用户认证)
|
||
- **Laravel Modules**: 12.0+ (模块化开发)
|
||
|
||
### 前端
|
||
|
||
- **Vue**: 3.5+
|
||
- **Vite**: 7.2+
|
||
- **Ant Design Vue**: 4.2+
|
||
- **Vue Router**: 5.0+
|
||
- **Pinia**: 3.0+ (状态管理)
|
||
- **Axios**: HTTP 客户端
|
||
- **Vue I18n**: 国际化支持
|
||
- **CKEditor 5**: 富文本编辑器
|
||
- **ECharts**: 数据可视化
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
laradmin/
|
||
├── app/ # 基础模块目录
|
||
│ ├── Http/Controllers/ # 控制器
|
||
│ │ ├── Auth/ # 认证模块控制器
|
||
│ │ │ └── Admin/
|
||
│ │ │ ├── Auth.php
|
||
│ │ │ ├── User.php
|
||
│ │ │ ├── Role.php
|
||
│ │ │ ├── Permission.php
|
||
│ │ │ └── Department.php
|
||
│ │ └── System/ # 系统模块控制器
|
||
│ │ ├── Admin/
|
||
│ │ │ ├── Config.php
|
||
│ │ │ ├── Log.php
|
||
│ │ │ ├── Dictionary.php
|
||
│ │ │ ├── Task.php
|
||
│ │ │ ├── City.php
|
||
│ │ │ └── Upload.php
|
||
│ │ ├── Api/
|
||
│ │ └── WebSocket.php
|
||
│ ├── Models/ # 模型
|
||
│ │ ├── Auth/
|
||
│ │ │ ├── User.php
|
||
│ │ │ ├── Role.php
|
||
│ │ │ ├── Permission.php
|
||
│ │ │ └── Department.php
|
||
│ │ └── System/
|
||
│ ├── Services/ # 服务层
|
||
│ │ ├── Auth/
|
||
│ │ ├── System/
|
||
│ │ └── WebSocket/
|
||
│ ├── Exports/ # 导出类
|
||
│ ├── Imports/ # 导入类
|
||
│ └── Middleware/ # 中间件
|
||
├── Modules/ # 业务模块目录
|
||
│ └── ModuleName/ # 业务模块示例
|
||
│ ├── App/
|
||
│ │ ├── Http/Controllers/
|
||
│ │ │ ├── Admin/ # 后台管理控制器
|
||
│ │ │ └── Api/ # 用户端API控制器
|
||
│ │ ├── Models/
|
||
│ │ ├── Services/
|
||
│ │ └── Providers/
|
||
│ ├── Database/
|
||
│ │ ├── migrations/
|
||
│ │ └── seeders/
|
||
│ ├── Resources/
|
||
│ └── Routes/
|
||
│ ├── admin.php
|
||
│ └── api.php
|
||
├── resources/
|
||
│ ├── admin/ # 前端管理界面
|
||
│ │ ├── src/
|
||
│ │ │ ├── api/ # API 接口
|
||
│ │ │ ├── components/ # 公共组件
|
||
│ │ │ │ ├── scForm/ # 表单组件
|
||
│ │ │ │ ├── scTable/ # 表格组件
|
||
│ │ │ │ ├── scUpload/ # 上传组件
|
||
│ │ │ │ ├── scEditor/ # 富文本编辑器
|
||
│ │ │ │ ├── scImport/ # 导入组件
|
||
│ │ │ │ └── scExport/ # 导出组件
|
||
│ │ │ ├── layouts/ # 布局组件
|
||
│ │ │ ├── pages/ # 页面组件
|
||
│ │ │ ├── router/ # 路由配置
|
||
│ │ │ ├── stores/ # 状态管理
|
||
│ │ │ ├── utils/ # 工具函数
|
||
│ │ │ ├── hooks/ # 组合式 API
|
||
│ │ │ └── i18n/ # 国际化
|
||
│ │ └── package.json
|
||
│ └── views/
|
||
├── routes/ # 路由定义
|
||
│ ├── admin.php # 后台管理路由
|
||
│ ├── api.php # 公共API路由
|
||
│ └── web.php # Web路由
|
||
├── config/ # 配置文件
|
||
│ ├── laravels.php # Laravel-S配置
|
||
│ ├── jwt.php # JWT配置
|
||
│ └── modules.php # 模块配置
|
||
├── database/ # 数据库
|
||
│ ├── migrations/
|
||
│ └── seeders/
|
||
├── docs/ # 文档目录
|
||
│ ├── README_AUTH.md # Auth模块文档
|
||
│ ├── README_SYSTEM.md # System模块文档
|
||
│ └── README_WEBSOCKET.md # WebSocket文档
|
||
└── storage/ # 存储目录
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- PHP >= 8.2
|
||
- Composer >= 2.0
|
||
- Node.js >= 18.0
|
||
- npm >= 9.0
|
||
- Redis >= 6.0
|
||
- MySQL >= 8.0
|
||
- Swoole 扩展 (>= 4.8)
|
||
|
||
### 安装步骤
|
||
|
||
#### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone http://git.tensent.cn/molong/laravel_swoole.git laradmin
|
||
cd laradmin
|
||
```
|
||
|
||
#### 2. 自动安装（推荐）
|
||
|
||
```bash
|
||
# 一键安装所有依赖并初始化
|
||
composer run setup
|
||
```
|
||
|
||
此命令会自动执行：
|
||
- 安装后端依赖
|
||
- 配置环境文件
|
||
- 生成应用密钥
|
||
- 执行数据库迁移
|
||
- 安装前端依赖
|
||
- 构建前端资源
|
||
|
||
#### 3. 手动安装
|
||
|
||
```bash
|
||
# 安装后端依赖
|
||
composer install
|
||
|
||
# 复制环境配置文件
|
||
cp .env.example .env
|
||
|
||
# 生成应用密钥
|
||
php artisan key:generate
|
||
|
||
# 配置数据库、Redis等参数
|
||
# 编辑 .env 文件
|
||
|
||
# 执行数据库迁移
|
||
php artisan migrate
|
||
|
||
# 填充初始数据
|
||
php artisan db:seed
|
||
|
||
# 生成 JWT 密钥
|
||
php artisan jwt:secret
|
||
|
||
# 安装前端依赖
|
||
cd resources/admin
|
||
npm install
|
||
|
||
# 构建前端
|
||
npm run build
|
||
```
|
||
|
||
### 运行项目
|
||
|
||
#### 开发模式
|
||
|
||
```bash
|
||
# 一键启动所有服务
|
||
composer run dev
|
||
```
|
||
|
||
此命令会启动：
|
||
- Laravel 开发服务器 (http://localhost:8000)
|
||
- 队列监听器
|
||
- 日志监控
|
||
- Vite 前端开发服务器
|
||
|
||
#### 分步启动
|
||
|
||
```bash
|
||
# 终端1: 启动 Laravel 开发服务器
|
||
php artisan serve
|
||
|
||
# 终端2: 启动前端开发服务器
|
||
cd resources/admin
|
||
npm run dev
|
||
|
||
# 终端3: 启动队列监听器（可选）
|
||
php artisan queue:listen
|
||
```
|
||
|
||
#### Swoole 模式（推荐生产环境）
|
||
|
||
```bash
|
||
# 启动 Laravel-S 服务
|
||
php bin/laravels start
|
||
|
||
# 停止服务
|
||
php bin/laravels stop
|
||
|
||
# 重启服务
|
||
php bin/laravels restart
|
||
|
||
# 重载服务（平滑重启）
|
||
php bin/laravels reload
|
||
|
||
# 查看状态
|
||
php bin/laravels status
|
||
```
|
||
|
||
访问地址：http://localhost:5200 (默认)
|
||
|
||
### 默认账号
|
||
|
||
```
|
||
用户名: admin
|
||
密码: 123456
|
||
```
|
||
|
||
## 📚 核心模块
|
||
|
||
### Auth 模块（认证授权）
|
||
|
||
提供完整的用户认证和权限管理功能：
|
||
|
||
- **用户管理**：用户增删改查、批量操作、导入导出
|
||
- **角色管理**：角色管理、权限分配、角色复制
|
||
- **权限管理**：权限树管理、菜单配置、按钮权限
|
||
- **部门管理**：部门树管理、组织架构
|
||
- **在线用户**：在线用户监控、强制下线
|
||
|
||
详细文档：[docs/README_AUTH.md](docs/README_AUTH.md)
|
||
|
||
### System 模块（系统管理）
|
||
|
||
提供系统级别的管理功能：
|
||
|
||
- **系统配置**：配置分组管理、多种数据类型支持
|
||
- **数据字典**：字典分类管理、字典项管理
|
||
- **操作日志**：日志记录、日志查询、日志统计
|
||
- **任务管理**：定时任务管理、手动执行、任务监控
|
||
- **城市数据**：省市区三级联动、城市树
|
||
- **文件上传**：单文件/多文件上传、Base64上传、图片压缩
|
||
|
||
详细文档：[docs/README_SYSTEM.md](docs/README_SYSTEM.md)
|
||
|
||
### WebSocket 模块
|
||
|
||
实时通信功能支持：
|
||
|
||
- 实时消息推送
|
||
- 在线状态同步
|
||
- 系统通知广播
|
||
|
||
详细文档：[docs/README_WEBSOCKET.md](docs/README_WEBSOCKET.md)
|
||
|
||
## 📖 API 文档
|
||
|
||
### 后台管理 API
|
||
|
||
基础路径：`/admin`
|
||
|
||
主要接口：
|
||
|
||
- `POST /admin/auth/login` - 用户登录
|
||
- `POST /admin/auth/logout` - 用户登出
|
||
- `GET /admin/users` - 获取用户列表
|
||
- `GET /admin/roles` - 获取角色列表
|
||
- `GET /admin/permissions` - 获取权限列表
|
||
- `GET /admin/configs` - 获取系统配置
|
||
- `GET /admin/logs` - 获取操作日志
|
||
|
||
详细接口文档请参考各模块文档。
|
||
|
||
### 公共 API
|
||
|
||
基础路径：`/api`
|
||
|
||
主要接口：
|
||
|
||
- `GET /api/system/configs` - 获取系统配置（公开）
|
||
- `GET /api/system/dictionaries` - 获取数据字典（公开）
|
||
- `GET /api/system/cities/tree` - 获取城市树（公开）
|
||
|
||
## 🔧 开发规范
|
||
|
||
### 后端开发规范
|
||
|
||
详细开发规范请参考：[.clinerules/rule.md](.clinerules/rule.md)
|
||
|
||
#### 命名规范
|
||
|
||
- **控制器**：不加 Controller 后缀，如 `User.php`
|
||
- **服务类**：以 Service 结尾，如 `UserService.php`
|
||
- **模型**：单数形式，如 `User.php`
|
||
- **数据表**：`{module}_{names}` 格式，如 `auth_users`
|
||
|
||
#### 模块开发
|
||
|
||
```bash
|
||
# 创建业务模块
|
||
php artisan module:make ModuleName
|
||
|
||
# 创建模块控制器
|
||
php artisan module:make-controller Admin/Post Blog
|
||
|
||
# 创建模块模型
|
||
php artisan module:make-model Post Blog
|
||
```
|
||
|
||
### 前端开发规范
|
||
|
||
详细开发规范请参考：[.clinerules/admin-rule.md](.clinerules/admin-rule.md)
|
||
|
||
#### 技术栈
|
||
|
||
- Vue 3 Composition API
|
||
- Ant Design Vue 4
|
||
- Pinia 状态管理
|
||
- Vue Router 路由
|
||
|
||
#### 组件开发
|
||
|
||
```vue
|
||
<script setup>
|
||
import { ref, onMounted } from 'vue'
|
||
|
||
const state = ref({})
|
||
|
||
onMounted(() => {
|
||
// 组件挂载
|
||
})
|
||
</script>
|
||
```
|
||
|
||
## 🔐 权限系统
|
||
|
||
### RBAC 模型
|
||
|
||
项目采用基于角色的访问控制（RBAC）：
|
||
|
||
```
|
||
User (用户)
|
||
↓ N:N
|
||
Role (角色)
|
||
↓ N:N
|
||
Permission (权限)
|
||
```
|
||
|
||
### 权限编码规则
|
||
|
||
采用 `模块.功能.操作` 格式：
|
||
|
||
- `system.user.list` - 系统管理-用户-列表
|
||
- `system.user.create` - 系统管理-用户-创建
|
||
- `system.user.update` - 系统管理-用户-更新
|
||
- `system.user.delete` - 系统管理-用户-删除
|
||
|
||
### 权限类型
|
||
|
||
- **menu**: 菜单类型，用于前端路由配置
|
||
- **api**: API接口类型，用于后端权限验证
|
||
- **button**: 按钮类型，用于前端按钮权限控制
|
||
|
||
## ⚡ 性能优化
|
||
|
||
### Swoole 优化
|
||
|
||
- 长生命周期，减少框架启动开销
|
||
- 协程支持，提高并发处理能力
|
||
- 连接池管理，减少连接创建开销
|
||
|
||
### 缓存策略
|
||
|
||
- Redis 缓存权限数据（60分钟）
|
||
- Redis 缓存城市数据（永久）
|
||
- Redis 缓存配置数据（60分钟）
|
||
- 权限数据变更时自动清除缓存
|
||
|
||
### 数据库优化
|
||
|
||
- 使用 Eloquent 关联避免 N+1 查询
|
||
- 合理使用索引
|
||
- 分页查询避免全表扫描
|
||
|
||
## 📦 常用命令
|
||
|
||
### Laravel 命令
|
||
|
||
```bash
|
||
# 数据库迁移
|
||
php artisan migrate
|
||
php artisan migrate:rollback
|
||
php artisan migrate:refresh
|
||
|
||
# 数据填充
|
||
php artisan db:seed
|
||
|
||
# 清除缓存
|
||
php artisan cache:clear
|
||
php artisan config:clear
|
||
php artisan route:clear
|
||
php artisan view:clear
|
||
|
||
# 队列处理
|
||
php artisan queue:work
|
||
php artisan queue:listen
|
||
|
||
# 测试
|
||
php artisan test
|
||
```
|
||
|
||
### Laravel-S 命令
|
||
|
||
```bash
|
||
# 启动服务
|
||
php bin/laravels start
|
||
|
||
# 停止服务
|
||
php bin/laravels stop
|
||
|
||
# 重启服务
|
||
php bin/laravels restart
|
||
|
||
# 重载服务（平滑重启）
|
||
php bin/laravels reload
|
||
|
||
# 查看状态
|
||
php bin/laravels status
|
||
|
||
# 查看帮助
|
||
php bin/laravels help
|
||
```
|
||
|
||
### Laravel Modules 命令
|
||
|
||
```bash
|
||
# 创建模块
|
||
php artisan module:make ModuleName
|
||
|
||
# 列出所有模块
|
||
php artisan module:list
|
||
|
||
# 启用/禁用模块
|
||
php artisan module:enable ModuleName
|
||
php artisan module:disable ModuleName
|
||
|
||
# 模块迁移
|
||
php artisan module:migrate ModuleName
|
||
php artisan module:migrate-rollback ModuleName
|
||
|
||
# 模块数据填充
|
||
php artisan module:seed ModuleName
|
||
```
|
||
|
||
### 前端命令
|
||
|
||
```bash
|
||
cd resources/admin
|
||
|
||
# 开发
|
||
npm run dev
|
||
|
||
# 构建
|
||
npm run build
|
||
|
||
# 预览
|
||
npm run preview
|
||
|
||
# 代码检查
|
||
npm run lint
|
||
|
||
# 代码格式化
|
||
npm run format
|
||
```
|
||
|
||
## 🔍 Swoole 开发注意事项
|
||
|
||
### 长生命周期注意事项
|
||
|
||
由于 Swoole 是长生命周期运行，需要注意：
|
||
|
||
1. **避免使用静态变量**
|
||
```php
|
||
// ❌ 错误
|
||
static $counter = 0;
|
||
|
||
// ✅ 正确
|
||
$counter = 0;
|
||
```
|
||
|
||
2. **避免使用全局变量**
|
||
- 不要依赖 `$_GET`, `$_POST` 等超全局变量
|
||
- 使用 Laravel 的 `Request` 对象获取请求数据
|
||
|
||
3. **连接池管理**
|
||
- 数据库、Redis 等连接需要正确管理
|
||
- 在 `config/laravels.php` 中配置连接池
|
||
|
||
4. **热重载机制**
|
||
```bash
|
||
# 平滑重启
|
||
php bin/laravels reload
|
||
|
||
# 或使用文件监控（开发环境）
|
||
bin/fswatch # Linux/Mac
|
||
bin/inotify # Linux
|
||
```
|
||
|
||
## 🌟 特色功能
|
||
|
||
### 1. 动态菜单路由
|
||
|
||
前端支持动态路由加载，登录后自动根据权限生成菜单树：
|
||
|
||
```javascript
|
||
// 登录后获取菜单
|
||
const menus = await authApi.permissions.menu.get()
|
||
userStore.setMenu(menus)
|
||
```
|
||
|
||
### 2. 权限指令
|
||
|
||
前端提供权限指令，方便控制元素显示：
|
||
|
||
```vue
|
||
<!-- 只有拥有 user.create 权限时显示 -->
|
||
<a-button v-permission="'user.create'">新增</a-button>
|
||
|
||
<!-- 拥有多个权限之一时显示 -->
|
||
<a-button v-permission="['user.create', 'user.update']">编辑</a-button>
|
||
```
|
||
|
||
### 3. 数据导入导出
|
||
|
||
支持 Excel 数据导入导出：
|
||
|
||
```javascript
|
||
// 导出用户数据
|
||
await userApi.export.post(params)
|
||
|
||
// 导入用户数据
|
||
await userApi.import.post(formData)
|
||
```
|
||
|
||
### 4. 富文本编辑器
|
||
|
||
集成 CKEditor 5 富文本编辑器：
|
||
|
||
```vue
|
||
<sc-editor
|
||
v-model="content"
|
||
:height="400"
|
||
/>
|
||
```
|
||
|
||
### 5. 文件上传
|
||
|
||
支持多种上传方式：
|
||
|
||
```vue
|
||
<!-- 图片上传 -->
|
||
<sc-upload
|
||
v-model="imageUrl"
|
||
:limit="1"
|
||
accept="image/*"
|
||
list-type="picture-card"
|
||
/>
|
||
|
||
<!-- 文件上传 -->
|
||
<sc-upload
|
||
v-model="fileList"
|
||
:limit="5"
|
||
:max-size="10"
|
||
/>
|
||
```
|
||
|
||
## 🤝 贡献指南
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
### Git 提交规范
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
**Type 类型：**
|
||
- `feat`: 新功能
|
||
- `fix`: 修复
|
||
- `docs`: 文档
|
||
- `style`: 格式
|
||
- `refactor`: 重构
|
||
- `test`: 测试
|
||
- `chore`: 构建/工具
|
||
|
||
**示例：**
|
||
```
|
||
feat(auth): 添加用户登录功能
|
||
|
||
- 实现 JWT 认证
|
||
- 添加登录接口
|
||
- 完善权限验证
|
||
|
||
Closes #123
|
||
```
|
||
|
||
## 📄 开源协议
|
||
|
||
本项目采用 MIT 协议开源。
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题或建议，欢迎联系：
|
||
|
||
- 项目地址：http://git.tensent.cn/molong/laravel_swoole
|
||
- Issue 提交：http://git.tensent.cn/molong/laravel_swoole/issues
|
||
|
||
## 🙏 致谢
|
||
|
||
感谢以下开源项目：
|
||
|
||
- [Laravel](https://laravel.com)
|
||
- [Swoole](https://www.swoole.com)
|
||
- [Laravel-S](https://github.com/hhxsv5/laravel-s)
|
||
- [Vue.js](https://vuejs.org)
|
||
- [Ant Design Vue](https://antdv.com)
|
||
- [Laravel Modules](https://nwidart.com/laravel-modules)
|
||
- [CKEditor 5](https://ckeditor.com)
|
||
- [ECharts](https://echarts.apache.org)
|
||
|
||
## 📝 更新日志
|
||
|
||
### v1.0.0 (2024-01-01)
|
||
|
||
- 🎉 初始版本发布
|
||
- ✅ 完成 Auth 模块（用户、角色、权限、部门）
|
||
- ✅ 完成 System 模块（配置、日志、字典、任务、城市、上传）
|
||
- ✅ 集成 Swoole 高性能服务
|
||
- ✅ 完成前端 Vue3 管理界面
|
||
- ✅ 实现 WebSocket 实时通信
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**LarAdmin** - 高性能后台管理系统
|
||
|
||
Made with ❤️ by [Tensent](http://git.tensent.cn)
|
||
|
||
</div>
|