# laradmin

**Repository Path**: ycgpp/laradmin

## Basic Information

- **Project Name**: laradmin
- **Description**: laravel+vue3+uniapp，laravel作为后端开发框架，vue3作为前端开发框架，uniapp作为移动端开发框架
- **Primary Language**: PHP
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 14
- **Forks**: 7
- **Created**: 2024-09-22
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Laravel, Vue, uni-app, Element-UI, admin

## README

<div align="center">

# LarAdmin

基于 Laravel 13 + Swoole + Vue 3 + Element Plus 的高性能后台管理系统 / CMS

[![Laravel](https://img.shields.io/badge/Laravel-13.0-red.svg)](https://laravel.com)
[![PHP](https://img.shields.io/badge/PHP-8.2+-blue.svg)](https://php.net)
[![Vue](https://img.shields.io/badge/Vue-3.5-brightgreen.svg)](https://vuejs.org)
[![Element Plus](https://img.shields.io/badge/Element_Plus-2.14-blue.svg)](https://element-plus.org)
[![Swoole](https://img.shields.io/badge/Swoole-5.1-orange.svg)](https://www.swoole.com)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

## 项目简介

LarAdmin 是一个基于 Laravel 13 + Swoole + Vue 3 的高性能后台管理系统，采用模块化架构设计，提供完整的认证授权、系统管理、业务扩展等功能。项目集成了 `hhxsv5/laravel-s` 实现 Swoole 长生命周期服务，大幅提升系统并发性能和响应速度。

包含三个前端应用：
- **管理后台 SPA**：Vue 3 + Element Plus + VXE Table，位于 `resources/admin/`
- **公开网站**：Nuxt 4 SSR，位于 `resources/web/`
- **移动端应用**：UniApp + Vue 3，支持 App + 多端小程序，位于 `resources/mobile/`

### 核心特性

- **高性能**：基于 Swoole 协程，支持高并发、低延迟
- **模块化**：采用 `nwidart/laravel-modules` 实现业务模块化管理
- **完整权限**：基于 RBAC 的权限控制系统，支持用户、角色、权限、部门管理
- **现代前端**：Vue 3 + Element Plus + VXE Table 构建的现代化管理界面
- **三种布局**：支持 basic（经典侧边栏）、dual（双栏导航）、top（水平导航）布局切换
- **仪表盘**：可拖拽 Widget 系统，支持 StatCard、ChartLine、ChartBar、TodoList、RecentActivity
- **暗色模式**：全局 CSS 变量切换，Element Plus / VXE Table 暗色适配
- **国际化**：vue-i18n，中/英双语支持
- **数据管理**：支持数据导入导出、在线编辑、批量操作
- **WebSocket**：内置 WebSocket 支持，JWT 鉴权、频道订阅、广播、系统通知
- **操作日志**：完整的操作日志记录和审计功能
- **存储驱动**：支持 Local / S3 / MinIO 多种存储驱动
- **任务调度**：可视化的定时任务管理界面

## 技术栈

### 后端

| 依赖 | 版本 | 用途 |
|------|------|------|
| PHP | ^8.2 | 运行时（Docker 使用 8.3） |
| Laravel | ^13.0 | 框架核心 |
| hhxsv5/laravel-s | ^3.8 | Swoole 集成 |
| tymon/jwt-auth | ^2.2 | JWT 认证 |
| nwidart/laravel-modules | ^12.0 | 模块化开发 |
| intervention/image | ^3.11 | 图片处理 |

### 管理后台前端（`resources/admin/`）

| 依赖 | 版本 | 用途 |
|------|------|------|
| Vue | ^3.5 | 框架核心 |
| Vite | ^8.0 | 构建工具 |
| Element Plus | ^2.14 | UI 框架 |
| VXE Table | ^4.19 | 高性能表格 |
| Pinia | ^3.0 | 状态管理 |
| Vue Router | ^4.6 | 路由 |
| Vue I18n | ^9.14 | 国际化 |
| @vueuse/core | ^14.3 | 组合式工具库 |
| Axios | ^1.16 | HTTP 请求 |
| grid-layout-plus | ^1.1 | 仪表盘拖拽布局 |

### 公开网站前端（`resources/web/`）

| 依赖 | 版本 | 用途 |
|------|------|------|
| Nuxt | ^4.4 | SSR 框架 |
| @nuxt/image | ^2.0 | 图片优化 |

### 移动端（`resources/mobile/`）

| 依赖 | 版本 | 用途 |
|------|------|------|
| @dcloudio/uni-ui | ^1.5 | UniApp UI 组件库 |
| luch-request | ^3.1 | 网络请求 |
| mp-html | ^2.5 | 富文本解析 |

## 项目结构

```
laradmin/
├── app/                              # 基础模块目录
│   ├── Http/Controllers/             # 控制器
│   │   ├── Auth/Admin/               # 认证模块后台控制器
│   │   │   ├── Auth.php
│   │   │   ├── User.php
│   │   │   ├── Role.php
│   │   │   ├── Permission.php
│   │   │   └── Department.php
│   │   └── System/                   # 系统模块控制器
│   │       ├── Admin/                # 后台控制器
│   │       │   ├── Config.php
│   │       │   ├── Log.php
│   │       │   ├── Dictionary.php
│   │       │   ├── ScheduledController.php
│   │       │   ├── Attachment.php
│   │       │   ├── StorageConfig.php
│   │       │   ├── Notification.php
│   │       │   └── Upload.php
│   │       └── Api/                  # 公开 API 控制器
│   │           ├── Config.php
│   │           ├── Dictionary.php
│   │           └── Upload.php
│   ├── Models/                       # 模型
│   │   ├── Auth/
│   │   │   ├── User.php
│   │   │   ├── Role.php
│   │   │   ├── Permission.php
│   │   │   └── Department.php
│   │   └── System/
│   │       ├── Config.php
│   │       ├── Dictionary.php
│   │       ├── DictionaryItem.php
│   │       ├── Log.php
│   │       ├── Scheduled.php
│   │       ├── ScheduledLog.php
│   │       ├── Notification.php
│   │       ├── Attachment.php
│   │       └── StorageConfig.php
│   ├── Services/                     # 服务层
│   │   ├── Auth/
│   │   ├── System/
│   │   │   └── Storage/             # 存储驱动
│   │   │       ├── StorageDriverInterface.php
│   │   │       ├── LocalStorageDriver.php
│   │   │       ├── S3StorageDriver.php
│   │   │       ├── MinIOStorageDriver.php
│   │   │       └── OssStorageDriver.php
│   │   └── WebSocket/
│   ├── Exports/                      # Excel 导出类
│   ├── Imports/                      # Excel 导入类
│   ├── Middleware/                   # 中间件
│   │   ├── AuthCheckMiddleware.php
│   │   ├── LogRequestMiddleware.php
│   │   └── RateLimitMiddleware.php
│   └── Traits/                       # 公共 Trait
│       ├── ResponseTrait.php
│       └── ModelTrait.php
├── modules/                          # 业务模块目录（nwidart/laravel-modules）
│   └── Cms/                          # CMS 内容管理模块
│       ├── app/Http/Controllers/
│       │   ├── Admin/
│       │   │   ├── Model.php
│       │   │   ├── Category.php
│       │   │   └── Content.php
│       │   └── Api/
│       │       └── Cms.php
│       ├── app/Models/
│       │   ├── CmsModel.php
│       │   ├── CmsModelField.php
│       │   ├── CmsCategory.php
│       │   └── CmsContentCategory.php
│       ├── app/Services/
│       │   ├── ModelService.php
│       │   ├── CategoryService.php
│       │   ├── ContentService.php
│       │   └── DynamicTableService.php
│       ├── Database/migrations/
│       └── Routes/
│           ├── admin.php
│           └── api.php
├── resources/
│   ├── admin/                        # 管理后台 SPA
│   │   └── src/
│   │       ├── api/                  # API 接口层
│   │       ├── assets/               # 静态资源
│   │       ├── components/           # 共享组件（s 前缀）
│   │       │   ├── sTable/           # VXE Grid 增强表格
│   │       │   └── sSelect/          # Element Plus 增强选择器
│   │       ├── config/               # 应用配置
│   │       ├── hooks/                # 组合式函数
│   │       │   ├── useTable.js       # 表格 CRUD 状态管理
│   │       │   └── useWebSocket.js   # WebSocket 管理
│   │       ├── layouts/              # 布局组件（basic/dual/top）
│   │       ├── locales/              # 国际化（中/英）
│   │       ├── router/               # 路由配置
│   │       ├── stores/               # Pinia 状态管理
│   │       │   ├── app.js
│   │       │   └── modules/
│   │       │       ├── user.js
│   │       │       └── dictionary.js
│   │       ├── utils/                # 工具函数
│   │       └── views/                # 页面视图
│   │           ├── auth/             # 认证管理（用户/角色/权限/部门）
│   │           ├── home/             # 仪表盘（可拖拽 Widget）
│   │           ├── login/            # 登录页
│   │           ├── system/           # 系统管理（配置/日志/字典）
│   │           └── ucenter/          # 个人中心
│   ├── web/                          # 公开网站（Nuxt 4 SSR）
│   │   ├── app/
│   │   │   ├── pages/               # 页面（首页/关于/新闻/产品/案例/联系）
│   │   │   ├── composables/         # API composable（useCms.ts）
│   │   │   ├── components/
│   │   │   └── layouts/
│   │   └── nuxt.config.ts
│   └── mobile/                       # 移动端（UniApp + Vue 3）
│       ├── pages/
│       ├── components/               # sc- 前缀组件
│       ├── store/                    # Pinia 状态管理
│       ├── api/
│       └── utils/
├── routes/
│   ├── admin.php                     # 后台管理路由（/admin 前缀）
│   ├── api.php                       # 公共 API 路由（/api/system 前缀）
│   └── web.php                       # Web 路由
├── config/
│   ├── laravels.php                  # LaravelS / Swoole 配置
│   ├── jwt.php                       # JWT 配置（HS256, 7天有效期）
│   └── modules.php                   # 模块配置
├── database/
│   ├── migrations/                   # 数据库迁移（6 个文件，14 张表）
│   └── seeders/                      # 数据填充
└── storage/
    └── modules_statuses.json         # 模块激活状态
```

## 快速开始

### 环境要求

- PHP >= 8.2（Docker 使用 8.3）
- Composer >= 2.0
- Node.js >= 18.0
- npm >= 9.0
- MySQL >= 8.0
- Swoole >= 5.1（生产环境推荐）
- Docker >= 20.0（可选）

### Docker 部署（推荐）

```bash
# 构建并启动容器
docker-compose up -d

# 进入容器
docker-compose exec php bash

# 初始化项目
composer run setup
```

在 `.env` 中配置数据库连接（Docker 内使用 `host.docker.internal` 连接宿主机）：

```env
DB_HOST=host.docker.internal
DB_DATABASE=laradmin
DB_USERNAME=root
DB_PASSWORD=your_password
```

### 安装步骤

#### 1. 克隆项目

```bash
git clone http://git.tensent.cn/molong/laravel_swoole.git laradmin
cd laradmin
```

#### 2. 自动安装（推荐）

```bash
composer run setup
```

此命令会自动执行：安装依赖 → 配置环境 → 生成密钥 → 生成 JWT 密钥 → 数据库迁移 → 数据填充。

#### 3. 手动安装

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan jwt:secret
# 编辑 .env 配置数据库
php artisan migrate
php artisan db:seed

# 安装前端依赖
cd resources/admin
npm install
npm run build
```

### 运行项目

#### 开发模式

```bash
# 一键启动（artisan serve + queue:listen + pail + npm dev）
composer run dev

# 或分步启动
php artisan serve              # Laravel 开发服务器
cd resources/admin && npm run dev  # Vite 前端开发服务器
```

#### Swoole 模式（生产环境推荐）

```bash
php bin/laravels start        # 启动服务（端口 8000）
php bin/laravels stop         # 停止服务
php bin/laravels reload       # 平滑重载
php bin/laravels status       # 查看状态
```

### 默认账号

```
用户名: admin
密码: 123456
```

## 核心模块

### Auth 模块（认证授权）

提供完整的用户认证和 RBAC 权限管理功能：

- **用户管理**：用户增删改查、批量操作、导入导出
- **角色管理**：角色管理、权限分配
- **权限管理**：权限树管理、菜单配置、按钮权限
- **部门管理**：部门树管理、组织架构

数据库表：`auth_user`、`auth_department`、`auth_role`、`auth_permission`、`auth_user_role`、`auth_role_permission`

### System 模块（系统管理）

提供系统级别的管理功能：

- **系统配置**：配置分组管理、多种数据类型支持
- **数据字典**：字典分类管理、字典项管理
- **操作日志**：日志记录、日志查询、日志统计
- **任务管理**：定时任务管理、手动执行、任务监控
- **通知管理**：系统通知管理
- **文件上传**：单文件/多文件上传、Base64 上传、图片压缩
- **附件管理**：附件管理、存储配置
- **存储驱动**：Local / S3 / MinIO / OSS 四种驱动实现

数据库表：`system_setting`、`system_log`、`system_dictionary`、`system_dictionary_item`、`system_scheduled`、`system_scheduled_log`、`system_notification`、`system_storage_config`、`system_attachment`

### Cms 模块（内容管理）

提供动态内容管理功能：

- **内容模型**：动态定义内容类型和字段，自动创建数据表
- **栏目管理**：树形栏目结构，支持栏目绑定模型
- **内容管理**：基于动态模型的内容 CRUD，支持多栏目、多标签
- **标签管理**：内容标签支持
- **单页管理**：单页内容和区块管理
- **版本历史**：内容版本记录和管理
- **自动菜单**：模型启用时自动注册后台菜单

数据库表：`cms_model`、`cms_model_field`、`cms_category`、`cms_content_category`、`cms_tag`、`cms_content_tag`、`cms_content_version`、`cms_page`、`cms_page_block`

### WebSocket 模块

实时通信功能支持：

- JWT 鉴权连接
- Swoole\Table 连接管理（102400 行）
- 频道订阅、广播、系统通知
- 前端 `useWebSocket` hook：单例模式、自动重连、心跳、消息分发

## API 文档

### 统一响应格式

所有接口返回：

```json
{ "code": 200, "message": "success", "data": { ... } }
```

列表响应 `data` 包含：`{ list, total, page, page_size, last_page }`

### 后台管理 API

基础路径：`/admin`，JWT 鉴权保护，`auth.check:admin` + `log.request` 中间件。

- `POST /admin/auth/login` — 用户登录（限流 5次/15分钟）
- `POST /admin/auth/logout` — 用户登出
- `GET /admin/users` — 获取用户列表
- `GET /admin/roles` — 获取角色列表
- `GET /admin/permissions` — 获取权限列表
- `GET /admin/configs` — 获取系统配置
- `GET /admin/logs` — 获取操作日志
- `GET /admin/dictionaries` — 获取数据字典
- `POST /admin/upload` — 文件上传

### 公共 API

基础路径：`/api/system`，无需鉴权。

- `GET /api/system/configs` — 获取系统配置
- `GET /api/system/dictionaries` — 获取数据字典
- `POST /api/system/upload` — 文件上传

### WebSocket

连接地址：`ws(s)://localhost:8000/ws?user_id={id}&token={token}`

## 架构设计

### 后端：Controller-Service-Model 模式

- **Controller** — 精简控制器，负责验证输入、调用 Service、返回 JSON（无 `Controller` 后缀）
- **Service** — 业务逻辑、事务管理、跨模型协调
- **Model** — 数据结构、关联关系、查询作用域、访问器/修改器
- **Trait** — 公共功能（`ResponseTrait` 9 个响应方法、`ModelTrait` 时区/字段过滤）

### 前端架构（管理后台）

- **Composition API** — 仅使用 `<script setup>`，禁止 Options API
- **API 层** — 嵌套对象格式 `{ resource: { list: { get: ... } } }`
- **共享组件** — `s` 前缀（`sTable`、`sSelect`）
- **useTable hook** — 标准化表格 CRUD 状态管理
- **动态路由** — 静态系统路由 + 后端菜单数据动态加载
- **状态管理** — Pinia + persistedstate 持久化

## 开发规范

### 命名规范

| 对象 | 规范 | 示例 |
|------|------|------|
| 控制器 | 无后缀，PascalCase | `User.php` |
| 服务类 | `{Name}Service` 后缀 | `UserService.php` |
| 数据库表 | `{模块}_{名称}`（复数） | `auth_users`、`system_configs` |
| 字段名 | snake_case | `created_at` |
| 主键 | `id`（BIGINT UNSIGNED） | — |
| 外键 | `{表名}_id` | `user_id` |
| 索引 | `idx_{字段}`，唯一索引：`uidx_{字段}` | `idx_status` |
| 权限标识 | `{模块}.{资源}.{动作}` | `system.user.list` |
| API 路由 | 小写、复数、连字符分隔 | `/admin/users` |
| Vue 组件文件 | PascalCase | `UserList.vue` |
| Vue 组件使用 | kebab-case | `<user-list />` |

### 后端开发

- **ResponseTrait**：`success()`、`error()`、`paginated()`、`created()`、`noContent()`、`forbidden()`、`notFound()`、`unauthorized()`、`validateError()`
- **权限缓存**：Redis 60 分钟，角色/权限变更时级联失效，超级管理员跳过权限检查
- **中间件**：`auth.check`（JWT 验证）、`log.request`（操作日志）、`rate.limit`（限流）
- **Swoole 注意**：禁止静态/全局变量，使用 Laravel Request 对象，禁止 PHP 超全局变量

### Git 提交规范

格式：`<type>(<scope>): <subject>`（中文描述）

类型：`feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`

## 常用命令

### 后端

```bash
composer run dev          # 完整开发环境
composer run start        # 安装依赖 + 生成密钥 + JWT 密钥
composer run setup        # start + migrate + seed
composer run test         # 清除配置 + 运行测试
php artisan migrate       # 运行迁移
php artisan db:seed       # 填充数据
```

### 管理后台前端

```bash
cd resources/admin
npm run dev               # Vite 开发服务器
npm run build             # 生产构建
npm run format            # Prettier 格式化
```

### 公开网站

```bash
cd resources/web
yarn dev                  # Nuxt 开发服务器
yarn build                # Nuxt 构建
```

### 模块管理

```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 版本 | ^8.2（Docker 8.3） |
| Swoole 版本 | 5.1.6 |
| JWT 有效期 | 7 天（10080 分钟），刷新期 14 天 |
| JWT 算法 | HS256，黑名单启用 |
| 队列驱动 | database |
| 缓存驱动 | database（默认）/ Redis（生产推荐） |
| Session 驱动 | database |
| 后台 API 地址 | `http://localhost:8000/admin/` |
| WebSocket 地址 | `ws(s)://localhost:8000/ws?user_id={id}&token={token}` |
| 代码风格 | Laravel Pint（PHP）、Prettier（前端） |
| 测试 | PHPUnit 12，SQLite 内存数据库 |

## 贡献指南

欢迎提交 Issue 和 Pull Request！

Git 提交格式：`<type>(<scope>): <subject>`

类型：`feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`

## 开源协议

本项目采用 MIT 协议开源。

## 联系方式

- 项目地址：http://git.tensent.cn/molong/laravel_swoole
- Issue 提交：http://git.tensent.cn/molong/laravel_swoole/issues