项目介绍

一、项目概述

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 安装

# 进入项目目录
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 数据库迁移

php webman migrate

5.5 启动

开发环境需同时启动后端与前端：

1. 启动后端（API 服务，端口 8787）：

   Linux / Mac：

   php start.php start
   

   Windows：

   php windows.php
   

2. 启动前端（Vue 开发服务，端口 1818）：

   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。

---

六、路由说明

• 后台 API：/admin/{module}.{Controller}/{action}
  • 示例：/admin/mall.User/index → app\admin\controller\mall\User::index
• 前台 API：/api/...
• 安装：/api/Install/...

---

七、已修复问题

问题	修复说明
数据库配置不一致	统一 database.php 与 thinkorm.php 默认值为 webman-builadmin
语言 key 命名错误	quick Search Fields 改为 quickSearchFields
编辑时密码必填	编辑时密码可选，仅新增时必填；后端支持密码加密与重置
多余表单校验	移除 create_time、update_time 的表单校验
mall_user 与 PlayX 资产口径混用	新增重构迁移并改为 mall_user 一对一扩展资产表

---

八、注意事项

1. 错误目录：若存在 webman-builadmin 目录，为路径拼写错误，建议删除或修正为 webman-builadmin/web。
2. 生产环境：建议将 config/app.php 中 debug 改为从 .env 读取，例如 env('app_debug', false)。
3. 密码加密：使用 hash_password() 存储密码，verify_password() 校验。

---

九、相关文档

• CRUD 生成逻辑说明
• Webman 官方文档
• BuildAdmin 官网

---

十、许可证

MIT License