255 lines
7.7 KiB
Markdown
255 lines
7.7 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 启动
|
||
|
||
**开发环境需同时启动后端与前端：**
|
||
|
||
1. **启动后端（API 服务，端口 8787）：**
|
||
|
||
**Linux / Mac：**
|
||
```bash
|
||
php start.php start
|
||
```
|
||
|
||
**Windows：**
|
||
```bash
|
||
php windows.php
|
||
```
|
||
|
||
2. **启动前端（Vue 开发服务，端口 1818）：**
|
||
```bash
|
||
cd web
|
||
pnpm dev
|
||
```
|
||
|
||
3. **访问地址：**
|
||
- 安装向导：http://localhost:1818/install/
|
||
- 前台地址：http://localhost:1818/index.html/#/
|
||
- 后台地址：http://localhost:1818/index.html/#/admin
|
||
|
||
> 注意：前端通过 Vite 代理将 `/api`、`/admin`、`/install` 转发到后端 8787 端口，请勿直接访问 8787 端口的前端页面，否则可能出现 404。
|
||
|
||
### 5.6 生产环境 Nginx（反向代理 Webman）
|
||
|
||
部署到服务器时，若使用 **Nginx** 作为站点入口，需将请求转发到本机 **Webman** 进程（默认监听端口与 `config/process.php` 中 `listen` 一致，一般为 `8787`，反代目标使用 `127.0.0.1:8787`）。
|
||
|
||
在站点 **`server { }`** 块中可增加如下写法：**先由 Nginx 根据 `root` 判断是否存在对应静态文件；不存在则转发到 Webman**（`root` 建议指向项目 `public` 目录）。
|
||
|
||
```nginx
|
||
location ^~ / {
|
||
proxy_set_header Host $http_host;
|
||
proxy_set_header X-Forwarded-For $remote_addr;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Connection "";
|
||
if (!-f $request_filename) {
|
||
proxy_pass http://127.0.0.1:8787;
|
||
}
|
||
}
|
||
```
|
||
|
||
修改配置后执行 `nginx -t` 校验，再重载 Nginx；并确保 Webman 已启动（如 `php start.php start -d`）。
|
||
|
||
若前端与接口为**不同域名**（跨域），除反代外还需保证 **HTTPS 证书与域名一致**，以及后端 **CORS / 预检（OPTIONS）** 与前端请求头（如 `think-lang`、`server` 等）配置一致，否则浏览器会报跨域相关错误。
|
||
|
||
---
|
||
|
||
## 六、路由说明
|
||
|
||
- **后台 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
|