LarAdmin 是一个基于 Laravel 12、Swoole 和 Vue 3 构建的高性能后台管理系统。它采用模块化架构设计，提供了完整的认证授权、系统管理及业务扩展功能。通过集成 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.js: 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 采用了标准的模块化组织方式。
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. 克隆项目
git clone https://gitee.com/ycgpp/laradmin.git laradmin
cd laradmin
2. 自动安装（推荐）
使用一条命令完成所有依赖安装和初始化工作。
# 一键安装所有依赖并初始化
composer run setup
此命令会自动执行：
- 安装后端依赖
- 配置环境文件
- 生成应用密钥
- 执行数据库迁移
- 安装前端依赖
- 构建前端资源
3. 手动安装
如果希望更精细地控制安装过程，也可以选择分步执行。
# 安装后端依赖
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
运行项目
开发模式
为了获得高效的开发体验，项目提供了一键启动命令。
# 一键启动所有服务
composer run dev
此命令会同时启动：
分步启动
你也可以选择在不同的终端分别启动各个服务。
# 终端1: 启动 Laravel 开发服务器
php artisan serve
# 终端2: 启动前端开发服务器
cd resources/admin
npm run dev
# 终端3: 启动队列监听器（可选）
php artisan queue:listen
Swoole 模式（推荐生产环境）
在正式的生产环境中，建议使用 Swoole 模式以获得最佳性能。
# 启动 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
System 模块（系统管理）
提供系统级别的管理功能：
- 系统配置：配置分组管理、多种数据类型支持
- 数据字典：字典分类管理、字典项管理
- 操作日志：日志记录、日志查询、日志统计
- 任务管理：定时任务管理、手动执行、任务监控
- 城市数据：省市区三级联动、城市树
- 文件上传：单文件/多文件上传、Base64上传、图片压缩
详细文档：docs/README_SYSTEM.md
WebSocket 模块
提供实时通信功能支持：
详细文档：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
命名规范
- 控制器：不加 Controller 后缀，如
User.php
- 服务类：以 Service 结尾，如
UserService.php
- 模型：单数形式，如
User.php
- 数据表：
{module}_{names} 格式，如 auth_users
模块开发
# 创建业务模块
php artisan module:make ModuleName
# 创建模块控制器
php artisan module:make-controller Admin/Post Blog
# 创建模块模型
php artisan module:make-model Post Blog
前端开发规范
详细开发规范请参考：.clinerules/admin-rule.md
技术栈
- Vue 3 Composition API
- Ant Design Vue 4
- Pinia 状态管理
- Vue Router 路由
组件开发
<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等连接的创建和销毁开销。
缓存策略
- Redis 缓存权限数据（60分钟）
- Redis 缓存城市数据（永久）
- Redis 缓存配置数据（60分钟）
- 权限数据变更时自动清除缓存
数据库优化
- 使用 Eloquent 关联避免 N+1 查询
- 合理使用索引
- 分页查询避免全表扫描
常用命令
Laravel 命令
# 数据库迁移
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 命令
# 启动服务
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 命令
# 创建模块
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
前端命令
cd resources/admin
# 开发
npm run dev
# 构建
npm run build
# 预览
npm run preview
# 代码检查
npm run lint
# 代码格式化
npm run format
Swoole 开发注意事项
长生命周期注意事项
由于 Swoole 采用长生命周期运行模式，与传统 PHP-FPM 模式有较大差异，开发时需要特别注意以下几点：
-
避免使用静态变量
// ❌ 错误
static $counter = 0;
// ✅ 正确
$counter = 0;
-
避免使用全局变量
- 不要依赖
$_GET, $_POST 等超全局变量。
- 应使用 Laravel 的
Request 对象来获取请求数据。
-
连接池管理
- 数据库、Redis 等连接需要正确管理，避免连接泄漏。
- 可在
config/laravels.php 中配置连接池参数。
-
热重载机制
修改代码后，需要重启或重载服务才能使更改生效。
# 平滑重启（生产环境推荐）
php bin/laravels reload
# 或使用文件监控（开发环境）
bin/fswatch # Linux/Mac
bin/inotify # Linux
特色功能
1. 动态菜单路由
前端支持动态路由加载，用户登录后系统会根据其权限自动生成对应的菜单树，实现权限与菜单的精准绑定。
// 登录后获取菜单
const menus = await authApi.permissions.menu.get()
userStore.setMenu(menus)
2. 权限指令
前端提供了自定义权限指令 v-permission，可以非常方便地控制页面元素的显示与隐藏。
<!-- 只有拥有 user.create 权限时显示 -->
<a-button v-permission="'user.create'">新增</a-button>
<!-- 拥有多个权限之一时显示 -->
<a-button v-permission="['user.create', 'user.update']">编辑</a-button>
3. 数据导入导出
系统内置了 Excel 数据的导入导出功能，封装了常用逻辑，开箱即用。
// 导出用户数据
await userApi.export.post(params)
// 导入用户数据
await userApi.import.post(formData)
4. 富文本编辑器
集成 CKEditor 5 富文本编辑器，通过封装好的组件可以轻松实现复杂的富文本编辑需求。
<sc-editor
v-model="content"
:height="400"
/>
5. 文件上传
上传组件支持多种上传方式和配置，包括图片上传、多文件上传、大小限制等。
<!-- 图片上传 -->
<sc-upload
v-model="imageUrl"
:limit="1"
accept="image/*"
list-type="picture-card"
/>
<!-- 文件上传 -->
<sc-upload
v-model="fileList"
:limit="5"
:max-size="10"
/>
LarAdmin 整合了现代 PHP 与前端技术栈的最佳实践，旨在为开发者提供一个功能完善、性能优异且易于扩展的后台管理脚手架。如果你正在寻找一个可靠的起点来构建你的下一个应用，不妨试试看。更多的技术讨论和资源分享，也欢迎到 云栈社区 与大家交流。
发表于 昨天 07:47
|
查看: 7|
回复: 0
