编写readme文档

This commit is contained in:
2026-02-08 22:45:43 +08:00
parent 334d2c6312
commit 616314eef2
2 changed files with 576 additions and 40 deletions

614
README.md
View File

@@ -1,59 +1,595 @@
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
<div align="center">
<p align="center">
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
</p>
# Laravel Swoole 管理系统
## About Laravel
基于 Laravel + Swoole + Vue3 的高性能后台管理系统
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
[![Laravel](https://img.shields.io/badge/Laravel-12.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)
[![Swoole](https://img.shields.io/badge/Swoole-Latest-orange.svg)](https://www.swoole.com)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
</div>
Laravel is accessible, powerful, and provides tools required for large, robust applications.
## 📖 项目简介
## Learning Laravel
本项目是一个基于 Laravel 12 + Swoole + Vue3 的高性能后台管理系统,采用模块化架构设计,提供完整的认证授权、系统管理、业务扩展等功能。项目集成了 `hhxsv5/laravel-s` 实现 Swoole 长生命周期服务,大幅提升系统并发性能和响应速度。
Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application.
### ✨ 核心特性
If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
- 🚀 **高性能**:基于 Swoole 协程,支持高并发、低延迟
- 📦 **模块化**:采用 `nwidart/laravel-modules` 实现业务模块化管理
- 🔐 **完整权限**:基于 RBAC 的权限控制系统,支持用户、角色、权限、部门管理
- 🎨 **现代前端**Vue 3 + Ant Design Vue + Vite 构建的现代化管理界面
- 📊 **数据管理**:支持数据导入导出、在线编辑、批量操作
- 🌐 **WebSocket**:内置 WebSocket 支持,实现实时通信
- 📝 **操作日志**:完整的操作日志记录和审计功能
- 🏙️ **城市数据**:内置全国省市区三级联动数据
- ⚙️ **系统配置**:灵活的系统配置管理,支持多种数据类型
- 🔄 **任务调度**:可视化的定时任务管理界面
## Laravel Sponsors
## 🛠 技术栈
We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).
### 后端
### Premium Partners
- **PHP**: 8.2+
- **Laravel**: 12.0
- **Laravel-S**: 3.8+ (Swoole 集成)
- **Swoole**: 最新稳定版
- **JWT-Auth**: 2.2+ (用户认证)
- **Laravel Modules**: 12.0+ (模块化开发)
- **[Vehikl](https://vehikl.com)**
- **[Tighten Co.](https://tighten.co)**
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
- **[64 Robots](https://64robots.com)**
- **[Curotec](https://www.curotec.com/services/technologies/laravel)**
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
- **[Redberry](https://redberry.international/laravel-development)**
- **[Active Logic](https://activelogic.com)**
### 前端
## Contributing
- **Vue**: 3.5+
- **Vite**: 7.2+
- **Ant Design Vue**: 4.2+
- **Vue Router**: 5.0+
- **Pinia**: 3.0+ (状态管理)
- **Axios**: HTTP 客户端
- **Vue I18n**: 国际化支持
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
## 📁 项目结构
## Code of Conduct
```
laravel_swoole/
├── 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/
│ ├── Models/ # 模型
│ │ ├── Auth/
│ │ │ ├── User.php
│ │ │ ├── Role.php
│ │ │ ├── Permission.php
│ │ │ └── Department.php
│ │ └── System/
│ ├── Services/ # 服务层
│ │ ├── Auth/
│ │ └── System/
│ └── Exports/ # 导出类
│ └── Imports/ # 导入类
├── 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/ # 公共组件
│ │ │ ├── layouts/ # 布局组件
│ │ │ ├── pages/ # 页面组件
│ │ │ ├── router/ # 路由配置
│ │ │ ├── stores/ # 状态管理
│ │ │ ├── utils/ # 工具函数
│ │ │ └── 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/ # 存储目录
```
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
## 🚀 快速开始
## Security Vulnerabilities
### 环境要求
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
- PHP >= 8.2
- Composer >= 2.0
- Node.js >= 18.0
- npm >= 9.0
- Redis >= 6.0
- MySQL >= 8.0
- Swoole 扩展 (>= 4.8)
## License
### 安装步骤
The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
#### 1. 克隆项目
```bash
git clone http://git.tensent.cn/molong/laravel_swoole.git
cd laravel_swoole
```
#### 2. 安装依赖
```bash
# 安装后端依赖
composer install
# 安装前端依赖
cd resources/admin
npm install
cd ../..
```
#### 3. 环境配置
```bash
# 复制环境配置文件
cp .env.example .env
# 生成应用密钥
php artisan key:generate
# 配置数据库、Redis等参数
# 编辑 .env 文件
```
#### 4. 执行数据库迁移
```bash
# 执行迁移
php artisan migrate
# 填充初始数据
php artisan db:seed
```
#### 5. 配置 JWT
```bash
# 生成 JWT 密钥
php artisan jwt:secret
```
#### 6. 构建前端
```bash
cd resources/admin
npm run build
cd ../..
```
### 运行项目
#### 开发模式
```bash
# 启动 Laravel 开发服务器
php artisan serve
# 启动前端开发服务器(另开终端)
cd resources/admin
npm run dev
```
#### Swoole 模式(推荐)
```bash
# 启动 Laravel-S 服务
php bin/laravels start
# 停止服务
php bin/laravels stop
# 重启服务
php bin/laravels restart
# 重载服务(平滑重启)
php bin/laravels reload
```
访问地址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
```
## 🤝 贡献指南
欢迎提交 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)
---
<div align="center">
Made with ❤️ by [Tensent](http://git.tensent.cn)
</div>

View File

@@ -101,7 +101,7 @@ return [
|
*/
'ttl' => env('JWT_TTL', 60),
'ttl' => env('JWT_TTL', 60 * 60 * 24 * 7),
/*
|--------------------------------------------------------------------------