laravel_swoole/README.md

LarAdmin

基于 Laravel + Swoole + Vue3 的高性能后台管理系统

📖 项目简介

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. 克隆项目

git clone http://git.tensent.cn/molong/laravel_swoole.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

此命令会启动：

• Laravel 开发服务器 (http://localhost:8000)
• 队列监听器
• 日志监控
• Vite 前端开发服务器

分步启动

# 终端1: 启动 Laravel 开发服务器
php artisan serve

# 终端2: 启动前端开发服务器
cd resources/admin
npm run dev

# 终端3: 启动队列监听器（可选）
php artisan queue:listen

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 缓存权限数据（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 是长生命周期运行，需要注意：

1. 避免使用静态变量

   // ❌ 错误
   static $counter = 0;
   
   // ✅ 正确
   $counter = 0;
   

2. 避免使用全局变量

   • 不要依赖 $_GET, $_POST 等超全局变量
   • 使用 Laravel 的 Request 对象获取请求数据

3. 连接池管理

   • 数据库、Redis 等连接需要正确管理
   • 在 config/laravels.php 中配置连接池

4. 热重载机制

   # 平滑重启
   php bin/laravels reload
   
   # 或使用文件监控（开发环境）
   bin/fswatch  # Linux/Mac
   bin/inotify  # Linux
   

🌟 特色功能

1. 动态菜单路由

前端支持动态路由加载，登录后自动根据权限生成菜单树：

// 登录后获取菜单
const menus = await authApi.permissions.menu.get()
userStore.setMenu(menus)

2. 权限指令

前端提供权限指令，方便控制元素显示：

<!-- 只有拥有 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"
/>

🤝 贡献指南

欢迎提交 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
• Swoole
• Laravel-S
• Vue.js
• Ant Design Vue
• Laravel Modules
• CKEditor 5
• ECharts

📝 更新日志

v1.0.0 (2024-01-01)

• 🎉 初始版本发布
• ✅ 完成 Auth 模块（用户、角色、权限、部门）
• ✅ 完成 System 模块（配置、日志、字典、任务、城市、上传）
• ✅ 集成 Swoole 高性能服务
• ✅ 完成前端 Vue3 管理界面
• ✅ 实现 WebSocket 实时通信

---

LarAdmin - 高性能后台管理系统

Made with ❤️ by Tensent