Webman Essentials

基于 Webman 的后台管理系统 API 骨架，开箱即用地提供 RBAC 权限管理、RSA 加密通信和完整的项目配置。配合前端项目 Vue-Naive-Admin 可直接开始业务开发，省去重复的环境搭建工作。

所有功能均在官方 Webman 基础上增量添加，未修改任何官方核心文件，开发时直接参考官方文档即可。

特性

• RBAC 权限管理 — 用户、角色、菜单权限的完整 CRUD 接口，支持角色切换
• RSA 加密通信 — 请求体 RSA 解密 + Token 鉴权，适用于非 HTTPS 环境下的安全传输
• 统一异常处理 — BusinessException 自动渲染为标准 JSON 错误响应，支持 webhook 异常推送
• 跨域中间件 — 内置 CORS 头处理，前后端分离开发无需额外代理配置
• 多语言支持 — 基于 Symfony Translation，错误信息走翻译文件，默认中文
• 协程支持 — 默认启用 Fiber 协程，安装 Swoole 扩展后自动切换为 Swoole 协程
• AI 开发友好 — 各目录配有 CLAUDE.md 文档，包含架构说明、代码规范和开发指引，适合 AI 辅助编码

技术栈

类别	技术
运行时	PHP >= 8.1, Workerman 5.x
框架	Webman 2.x
数据库	MySQL (Eloquent ORM)
缓存	Redis
队列	Redis Queue
迁移	Phinx
国际化	Symfony Translation

目录结构

├── app/                    # 业务代码
│   ├── bootstrap/          # 启动引导（RSA 密钥生成等）
│   ├── controller/         # 控制器
│   │   └── AdminApi/       # 后台 API 控制器
│   │       └── Framework/  # 认证、用户、角色、权限管理
│   ├── exception/          # 异常处理
│   ├── middleware/         # 中间件（CORS、语言、认证解密）
│   ├── model/              # Eloquent 模型
│   ├── process/            # 进程定义（HTTP + Monitor）
│   └── service/            # 业务逻辑层（静态方法）
├── config/                 # 全部配置文件
│   └── plugin/             # 插件配置（Event、Redis Queue）
├── database/migrations/    # Phinx 数据库迁移文件
├── public/                 # 静态资源（可直接访问）
├── resource/enums/         # PHP 8.1 枚举类
├── vendor/                 # Composer 依赖
├── .env.example            # 环境变量模板
├── phinx.php               # Phinx 配置
└── start.php               # 启动入口

快速开始

环境要求

• PHP >= 8.1
• Composer
• MySQL
• Redis
• Swoole（可选，安装后自动启用协程模式）

安装步骤

# 1. 克隆项目
git clone https://github.com/zxc7563598/php-webman-essentials.git
cd php-webman-essentials

# 2. 安装依赖
composer install

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 填入实际的数据库、Redis 连接信息

# 4. 执行数据库迁移
php vendor/bin/phinx migrate

# 5. 启动服务（开发模式，带热重载）
php start.php start

# 生产模式（守护进程）
php start.php start -d

服务默认监听 http://127.0.0.1:8787，所有 API 路由前缀为 /admin-api。

请求流程

客户端 RSA 加密请求体
  -> AccessMiddleware（CORS 头）
  -> LangMiddleware（设置语言）
  -> AdminAuthMiddleware（解密、Token 校验）
  -> 控制器方法
  -> JSON 响应 {"code": 0, "message": "成功", "data": {}}

加密后的请求参数从 $request->data 获取，前端项目 Vue-Naive-Admin 已适配该通信协议。

API 接口

全部 POST 接口，路由手动注册在 config/route.php。主要功能模块：

• 认证 — 登录、退出、切换角色、修改密码
• 用户管理 — 管理员列表（分页）、详情、增删改
• 角色管理 — 角色增删改、菜单权限分配、用户绑定
• 权限管理 — 菜单树、菜单增删改、启用/禁用切换

常用命令

php start.php start                   # 开发模式（带热重载）
php start.php start -d                # 生产模式（守护进程）
php start.php restart                 # 重启（修改 process.php/server.php 后必须 restart）
php start.php status                  # 查看运行状态
vendor/bin/phinx migrate              # 执行数据库迁移
vendor/bin/phinx create MigrationName # 创建迁移文件

相关链接

• Webman 官方文档
• Vue-Naive-Admin（配套前端）
• Webman 问答社区