# LarAdmin
基于 Laravel + Swoole + Vue3 的高性能后台管理系统
[](https://laravel.com)
[](https://php.net)
[](https://vuejs.org)
[](https://www.swoole.com)
[](LICENSE)
## 📖 项目简介
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
```
## 🔐 权限系统
### 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
新增
编辑
```
### 3. 数据导入导出
支持 Excel 数据导入导出：
```javascript
// 导出用户数据
await userApi.export.post(params)
// 导入用户数据
await userApi.import.post(formData)
```
### 4. 富文本编辑器
集成 CKEditor 5 富文本编辑器：
```vue
```
### 5. 文件上传
支持多种上传方式：
```vue
```
## 🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
### Git 提交规范
```
():