项目介绍
一、项目概述
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 配置
- 复制
.env.example为.env - 配置数据库连接（
database.hostname、database.database、database.username、database.password）
5.4 数据库迁移
php webman migrate
5.5 启动
开发环境需同时启动后端与前端：
-
启动后端（API 服务，端口 8787）：
Linux / Mac：
php start.php startWindows：
php windows.php -
启动前端（Vue 开发服务，端口 1818）：
cd web pnpm dev -
访问地址：
注意：前端通过 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 目录）。
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 |
八、注意事项
- 错误目录：若存在
webman-builadmin目录，为路径拼写错误，建议删除或修正为webman-builadmin/web。 - 生产环境：建议将
config/app.php中debug改为从.env读取，例如env('app_debug', false)。 - 密码加密：使用
hash_password()存储密码，verify_password()校验。
九、相关文档
十、许可证
MIT License