223 lines
5.9 KiB
Markdown
223 lines
5.9 KiB
Markdown
# 项目介绍
|
||
|
||
## 一、项目概述
|
||
|
||
**webman-builadmin** 是基于 **Webman**（Workerman）的 BuildAdmin 后台管理系统，将原 ThinkPHP8 版 BuildAdmin 迁移到 Webman 框架，实现前后端分离、常驻内存运行，提供高性能、可扩展的后台管理能力。
|
||
|
||
### 核心特性
|
||
|
||
- **常驻内存**：基于 Workerman，避免传统 PHP-FPM 的进程反复创建开销
|
||
- **前后端分离**：Vue 3 + TypeScript 前端，RESTful API 后端
|
||
- **CRUD 代码生成**：可视化设计表结构，自动生成控制器、模型、验证器、前端页面
|
||
- **权限管理**：RBAC 权限模型，支持管理员分组、菜单规则
|
||
- **多语言**：中文、英文等多语言支持
|
||
- **安全特性**：XSS 过滤、敏感数据脱敏、数据回收站等
|
||
|
||
---
|
||
|
||
## 二、技术栈
|
||
|
||
### 后端（PHP）
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| PHP | >= 8.1 | 运行环境 |
|
||
| workerman/webman-framework | ^2.1 | Webman 框架 |
|
||
| webman/think-orm | ^2.1 | ThinkORM 数据库 |
|
||
| webman/validation | ^2.2 | 表单验证 |
|
||
| topthink/think-validate | ^3.0 | 验证器 |
|
||
| vlucas/phpdotenv | ^5.6 | 环境变量 |
|
||
| robmorgan/phinx | ^0.15 | 数据库迁移 |
|
||
| voku/anti-xss | ^4.1 | XSS 防护 |
|
||
|
||
### 前端
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Vue | 3.5.13 | 前端框架 |
|
||
| Element Plus | 2.9.1 | UI 组件库 |
|
||
| TypeScript | 5.7.2 | 类型系统 |
|
||
| Vite | 6.3.5 | 构建工具 |
|
||
| Pinia | 2.3.0 | 状态管理 |
|
||
| Vue Router | 4.5.0 | 路由 |
|
||
| Axios | 1.9.0 | HTTP 客户端 |
|
||
| ECharts | 5.5.1 | 图表 |
|
||
| Vue I18n | 11.1.3 | 国际化 |
|
||
|
||
---
|
||
|
||
## 三、项目结构
|
||
|
||
```
|
||
webman-builadmin/
|
||
├── app/ # 应用代码
|
||
│ ├── admin/ # 后台管理
|
||
│ │ ├── controller/ # 控制器（auth、user、routine、crud、security、mall 等）
|
||
│ │ ├── model/ # 模型
|
||
│ │ ├── validate/ # 验证器
|
||
│ │ ├── lang/ # 语言包
|
||
│ │ └── library/ # 库（Auth、CRUD、traits）
|
||
│ ├── api/ # 前台 API
|
||
│ ├── common/ # 公共模块
|
||
│ └── support/ # 基础类
|
||
├── config/ # 配置文件
|
||
│ ├── app.php # 应用配置
|
||
│ ├── route.php # 路由
|
||
│ ├── database.php # Webman 数据库连接池
|
||
│ ├── thinkorm.php # ThinkORM 配置（主 ORM）
|
||
│ └── buildadmin.php # BuildAdmin 业务配置
|
||
├── database/
|
||
│ └── migrations/ # 数据库迁移
|
||
├── extend/ # 扩展
|
||
├── modules/ # 模块
|
||
├── public/ # 入口与静态资源
|
||
├── web/ # 前端 Vue 源码
|
||
│ └── src/
|
||
│ ├── api/ # API 封装
|
||
│ ├── components/ # 通用组件
|
||
│ ├── lang/ # 多语言
|
||
│ ├── router/ # 路由
|
||
│ ├── stores/ # Pinia
|
||
│ ├── utils/ # 工具
|
||
│ └── views/ # 页面
|
||
├── start.php # 主启动
|
||
├── windows.php # Windows 启动
|
||
└── composer.json
|
||
```
|
||
|
||
---
|
||
|
||
## 四、主要功能模块
|
||
|
||
### 4.1 权限管理（auth）
|
||
|
||
- 管理员管理（admin）
|
||
- 管理员分组（group）
|
||
- 菜单规则（rule）
|
||
|
||
### 4.2 用户管理（user）
|
||
|
||
- 用户管理（user）
|
||
- 用户分组（group）
|
||
- 用户规则（rule）
|
||
- 余额日志（moneyLog）
|
||
- 积分日志（scoreLog）
|
||
|
||
### 4.3 常规配置（routine）
|
||
|
||
- 系统配置（config）
|
||
- 管理员资料（adminInfo）
|
||
- 附件管理（attachment）
|
||
|
||
### 4.4 安全中心（security）
|
||
|
||
- 敏感数据管理
|
||
|
||
### 4.5 积分商城（mall）
|
||
|
||
- 积分商城用户（player）
|
||
|
||
### 4.6 CRUD 设计（crud）
|
||
|
||
- 可视化表设计
|
||
- 一键生成控制器、模型、验证器、前端页面
|
||
|
||
---
|
||
|
||
## 五、快速开始
|
||
|
||
### 5.1 环境要求
|
||
|
||
- PHP >= 8.1
|
||
- MySQL >= 5.7
|
||
- Composer
|
||
- Node.js >= 18（前端开发）
|
||
|
||
### 5.2 安装
|
||
|
||
```bash
|
||
# 进入项目目录
|
||
cd webman-builadmin
|
||
|
||
# 安装 PHP 依赖
|
||
composer install
|
||
|
||
# 安装前端依赖
|
||
cd web && pnpm install
|
||
```
|
||
|
||
### 5.3 配置
|
||
|
||
1. 复制 `.env.example` 为 `.env`
|
||
2. 配置数据库连接（`database.hostname`、`database.database`、`database.username`、`database.password`）
|
||
|
||
### 5.4 数据库迁移
|
||
|
||
```bash
|
||
php webman migrate
|
||
```
|
||
|
||
### 5.5 启动
|
||
|
||
**Linux / Mac：**
|
||
|
||
```bash
|
||
php start.php start
|
||
```
|
||
|
||
**Windows：**
|
||
|
||
```bash
|
||
php windows.php
|
||
```
|
||
|
||
### 5.6 前端开发
|
||
|
||
```bash
|
||
cd web
|
||
pnpm dev
|
||
```
|
||
|
||
---
|
||
|
||
## 六、路由说明
|
||
|
||
- **后台 API**：`/admin/{module}.{Controller}/{action}`
|
||
- 示例：`/admin/mall.Player/index` → `app\admin\controller\mall\Player::index`
|
||
- **前台 API**：`/api/...`
|
||
- **安装**：`/api/Install/...`
|
||
|
||
---
|
||
|
||
## 七、已修复问题
|
||
|
||
| 问题 | 修复说明 |
|
||
|------|----------|
|
||
| 数据库配置不一致 | 统一 `database.php` 与 `thinkorm.php` 默认值为 `webman-builadmin` |
|
||
| 语言 key 命名错误 | `quick Search Fields` 改为 `quickSearchFields` |
|
||
| 编辑时密码必填 | 编辑时密码可选，仅新增时必填；后端支持密码加密与重置 |
|
||
| 多余表单校验 | 移除 `create_time`、`update_time` 的表单校验 |
|
||
| mall_player 表缺失 | 新增迁移文件 `20250318120000_mall_player.php` |
|
||
|
||
---
|
||
|
||
## 八、注意事项
|
||
|
||
1. **错误目录**：若存在 `webman-builadmin` 目录，为路径拼写错误，建议删除或修正为 `webman-builadmin/web`。
|
||
2. **生产环境**：建议将 `config/app.php` 中 `debug` 改为从 `.env` 读取，例如 `env('app_debug', false)`。
|
||
3. **密码加密**：使用 `hash_password()` 存储密码，`verify_password()` 校验。
|
||
|
||
---
|
||
|
||
## 九、相关文档
|
||
|
||
- [CRUD 生成逻辑说明](docs/CRUD生成逻辑说明.md)
|
||
- [Webman 官方文档](https://webman.workerman.net)
|
||
- [BuildAdmin 官网](https://wonderful-code.gitee.io/buildadmin/)
|
||
|
||
---
|
||
|
||
## 十、许可证
|
||
|
||
MIT License
|