# likeadmin-webman（PHP版）

**Repository Path**: suyibk/workman-likeadmin-all

## Basic Information

- **Project Name**: likeadmin-webman（PHP版）
- **Description**: 基于likeadmin框架更换webman开发版本，常驻内存，定时任务，支持redis队列，SSE协议，webman/thinkorm, 支持AWS S3直传，,支持swoole，swow，fiber 协程，基于likeadmin-php项目开发
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: https://gitee.com/suyibk/workman-likeadmin-all
- **GVP Project**: No

## Statistics

- **Stars**: 58
- **Forks**: 31
- **Created**: 2024-02-19
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: PHP, TypeScript, webman, Vue, uni-app

## README

# workman-likeadmin-all

> 基于 [webman](https://www.workerman.net/webman)（Workerman）常驻内存版的多端内容 / 电商中后台解决方案。
> 后端由 likeadmin（ThinkPHP 版）改写为 **PHP 8.2 + webman**，前端覆盖 **后台管理 / PC 官网 / 移动端** 三端。

[![PHP](https://img.shields.io/badge/PHP-%3E%3D8.2-777BB4?logo=php&logoColor=white)](https://www.php.net/)
[![webman](https://img.shields.io/badge/webman-%5E2.1-00A2FF)](https://www.workerman.net/webman)
[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

[English](./README.en.md) | 简体中文

---

## 一、架构图

![workman-likeadmin-all 总体架构](./workman-likeadmin-all.svg)

> 交互式架构图（可切换主题 / 风格、按链路高亮、导出 PNG / SVG）：打开 [`架构预览图.html`](./架构预览图.html)

```
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ admin 后台    │ │ pc 官网       │ │ uniapp 移动端     │
│ Vue3 + Vite  │ │ Nuxt3 SSR    │ │ H5/小程序/App     │
└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘
       │ /adminapi      │ /api             │ /api
       └────────────────┴────────┬─────────┘
                                 ▼
                    ┌─────────────────────────┐
                    │   Nginx 反向代理（单域名） │
                    └────────────┬────────────┘
                                 ▼
        ┌────────────────────────────────────────────┐
        │  webman 应用服务（PHP 8.2 常驻内存）         │
        │  ┌────────────┐ ┌────────┐ ┌────────────┐  │
        │  │ adminapi   │ │  api   │ │  common    │  │
        │  │ RBAC 鉴权  │ │ C端接口│ │ model/     │  │
        │  │            │ │        │ │ service/   │  │
        │  │            │ │        │ │ storage    │  │
        │  └────────────┘ └────────┘ └────────────┘  │
        │  ┌────────────┐                            │
        │  │ 代码生成器  │ 在线产出前后端 + 菜单 SQL    │
        │  └────────────┘                            │
        └───┬──────────┬──────────────┬──────────────┘
            ▼          ▼              ▼
        ┌───────┐  ┌───────┐   ┌────────────┐  ┌──────────────┐
        │ MySQL │  │ Redis │   │ 对象存储    │  │ 微信/支付宝   │
        │ThinkORM3│ │缓存/token│ │OSS/COS/七牛│  │ 支付 + 回调   │
        └───────┘  └───────┘   └────────────┘  └──────────────┘
```

**三条主链路**

| 链路 | 路径 |
|---|---|
| 后台请求主链路 | `admin` → Nginx → `adminapi` → `common` → MySQL |
| 文件上传直传链路 | `uniapp` → Nginx → `api` → `common` 签发预签名 URL → 前端直传对象存储 |
| 支付链路 | `pc` → Nginx → `api` → 微信支付 / 支付宝（含异步回调） |

---

## 二、特性

- **常驻内存高性能**：webman 常驻内存模型，无传统 FPM 每请求重复初始化开销。
- **四端一体**：`server` 后端 + `admin` 运营后台 + `pc` PC 官网 + `uniapp` 移动端（H5 / 小程序 / App）。
- **双应用前缀**：`app/adminapi`（运营端）与 `app/api`（C 端）共享 `app/common`，业务逻辑各自独立。
- **在线代码生成器**：选表即可生成后端 5 文件 + 前端 3 文件 + 菜单 SQL，支持预览、ZIP 下载、自动写入菜单。
- **存储抽象**：本地 / 阿里云 OSS / 腾讯云 COS / 七牛 / AWS S3 统一接口，支持**预签名直传**，上传不走服务端中转。
- **多进程与推送**：主服务、慢业务、SSE、HTTP-Chunk 分端口部署，长耗时与推送消息不阻塞主链路。
- **完善的鉴权**：Header `token` + Redis 缓存 + 自动续期，后台 RBAC 权限精确到 URI。

---

## 三、技术栈

| 端 | 技术栈 |
|---|---|
| **server** | PHP 8.2 · webman 2.1 · Workerman 5.1 · ThinkORM 3 · webman/redis-queue · workerman/crontab · taoser/webman-validate · easywechat 6 · alipay easysdk · OSS/COS/七牛/S3 SDK · PhpSpreadsheet |
| **admin** | Vue 3.4 · Vite 3 · TypeScript 4.7 · Element Plus 2.2.27 · Pinia · Tailwind CSS 3 · Axios 0.27 · ECharts 5 |
| **pc** | Nuxt 3.6.5 · Vue 3.3 · Element Plus 2.5 · Pinia · Tailwind CSS · SSR 可开关 |
| **uniapp** | uni-app 3.0 · Vue 3.2 · Vite 4 · uView UI · Pinia · z-paging · Tailwind CSS |

---

## 四、目录结构

```
workman-likeadmin-all/
├── server/                 # 后端：webman 应用
│   ├── app/
│   │   ├── adminapi/       # 运营端应用（controller 45 / logic 41 / lists 23 / validate 31）
│   │   ├── api/            # C 端应用
│   │   ├── common/         # 公共模块（model / service / storage / enum / cache / lists ...）
│   │   ├── queue/          # Redis 队列消费者
│   │   ├── crontab/        # 定时任务
│   │   └── ...             # 中间件按应用分布：
│   │                       #   adminapi/middleware      → Init / Login / Auth
│   │                       #   api/middleware           → Init / Login
│   │                       #   common/http/middleware   → Allow / Base / End
│   ├── config/             # app / database / think-orm / server / process / middleware / route / project ...
│   ├── sql/                # like.sql 初始化建表脚本
│   ├── public/             # Web 根目录
│   ├── install.php         # 交互式安装脚本（Linux / macOS）
│   ├── windows.bat         # Windows 安装 / 启动脚本
│   ├── start.php           # 服务启动入口
│   ├── Dockerfile
│   └── docker-compose.yaml
├── admin/                  # 后台管理前端（Vue3 + Vite）
├── pc/                     # PC 官网（Nuxt3）
├── uniapp/                 # 移动端（uni-app）
├── workman-likeadmin-all.svg   # 架构图（静态）
└── 架构预览图.html              # 架构图（交互式预览）
```

---

## 五、环境要求

| 组件 | 版本要求 |
|---|---|
| PHP | >= 8.2 |
| PHP 扩展 | `json` `fileinfo` `simplexml` `bcmath` `curl` `zip` `mbstring` `redis` `pdo` |
| Composer | >= 2 |
| MySQL | >= 5.7（推荐 8.0） |
| Redis | >= 5.0 |
| Node.js | >= 18（前端构建） |

> **注意**：Windows 环境仅建议用于开发调试。生产环境请使用 Linux，Windows 下不支持 `event`/`swoole` 等协程事件循环，且无文件监控热重载。

---

## 六、快速开始

### 6.1 后端

```bash
cd server

# 1. 安装依赖
composer install

# 2. 配置环境
cp .example.env .env      # Windows: copy .example.env .env
#    按需修改 DB_* / REDIS_* / SERVER_LISTEN 等配置

# 3. 初始化数据库与管理员账号
#    Windows：双击或执行
./windows.bat
#    Linux / macOS：交互式安装
php install.php
```

安装脚本会引导填写数据库地址、端口、库名、表前缀、账号密码、Redis 配置以及**超级管理员账号密码**，并自动导入 `server/sql/like.sql`。

如提示存在被禁用的函数，可执行 webman 提供的修复命令：

```bash
php webman fix-disable-functions
```

### 6.2 启动

```bash
cd server

# 开发调试（前台运行，Linux 下修改 PHP 文件自动热重载）
php start.php start

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

# 其他
php start.php stop        # 停止
php start.php restart     # 重启
php start.php reload      # 平滑重载业务代码
php start.php status      # 查看状态
```

Windows 下直接执行 `server/windows.bat`，脚本会自动检查依赖并在未安装时调用安装流程。

> ⚠️ **常驻内存模型**：生产环境（`-d` 守护模式）修改 PHP 代码后**必须重启**才能生效（`php start.php restart` 或 `reload`）。

### 6.3 前端

```bash
# 运营后台
cd admin && npm install && npm run dev        # 构建：npm run build

# PC 官网
cd pc && npm install && npm run dev           # 静态构建：npm run build；SSR 构建：npm run build:ssr

# 移动端（H5）
cd uniapp && npm install && npm run dev:h5    # 微信小程序：npm run dev:mp-weixin
```

---

## 七、端口与进程

端口与附加进程均在 `server/.env` 中配置，留空或置为 `off` 则不启动对应进程。

| 环境变量 | 默认端口 | 说明 |
|---|---|---|
| `SERVER_LISTEN` | `8789` | 主 HTTP 服务 |
| `SLOW_SERVER_LISTEN` / `SLOW_PROCESS_STATUS` | `8790` | 慢业务进程，Nginx 将耗时路由反代到此端口，避免阻塞主服务 |
| `SSE_SERVER_LISTEN` / `SSE_STATUS` | `8791` | SSE（`text/event-stream`）服务端推送 |
| `CHUNK_SERVER_LISTEN` / `CHUNK_STATUS` | `8792` | HTTP-Chunk 服务端推送 |
| `CRONTAB_STATUS` | - | 定时任务进程（`app/crontab/Task.php`） |

### 事件循环 / 协程切换

编辑 `server/config/server.php`：

```php
// 进程数：默认 cpu_count() * 4
'count' => cpu_count() * 4,
// 事件循环：留空为 webman 自动选择（推荐）
'event_loop' => '',
```

| 可选值 | 说明 |
|---|---|
| `''`（默认） | 交给 webman 自动选择，兼容性最好 |
| `\Workerman\Events\Event::class` | 需 `event` 扩展，高并发横向扩展首选（Windows 不支持） |
| `\Workerman\Events\Swoole::class` | 需 `swoole` 扩展，协程异步非阻塞；并发能力更强，**需调大下方的连接池连接数**（Windows 不支持） |
| `\Workerman\Events\Fiber::class` | PHP 原生纤程，适合并发量不大的场景 |
| `\Workerman\Events\Select::class` | 原生实现，受限于 1024 文件描述符 |

### 连接池

MySQL 与 Redis 的连接池**已内置**（webman/database 与 webman/cache 提供），切换协程模式后无需额外改造，**按需调整连接数即可**。

| 连接池 | 配置位置 |
|---|---|
| MySQL | `server/config/think-orm.php` → `connections.mysql.pool` |
| Redis | `server/config/think-cache.php` → `stores.redis.pool` |

```php
'pool' => [
    'max_connections'    => 5,  // 最大连接数
    'min_connections'    => 1,  // 最小连接数
    'wait_timeout'       => 3,  // 从连接池获取连接的等待超时时间（秒）
    'idle_timeout'       => 60, // 连接最大空闲时间（秒），超时后被回收
    'heartbeat_interval' => 50, // 心跳检测间隔（秒），需小于 60
],
```

> ⚠️ `max_connections` 是**单个进程**的连接数上限，实际占用的总连接数 ≈ `max_connections × 进程数`（进程数见 `config/server.php` 的 `count`，默认 `cpu_count() * 4`）。
> 调整时需与 MySQL / Redis 服务端自身的 `max_connections` 对齐，避免打满数据库连接数。
> 协程模式下并发能力更强，通常应相应调大 `max_connections`；若日志出现获取连接超时，优先调大该值或 `wait_timeout`。

---

## 八、四端对接约定

| 前端 | 请求前缀 | 鉴权方式 |
|---|---|---|
| `admin` | `/adminapi` | Header `token` + 后端 RBAC 权限校验 |
| `pc` | `/api` | Header `token`（SSR 可开关） |
| `uniapp` | `/api` | Header `token` + `pages.json` 中 `meta.auth` 路由守卫 |

- 统一响应结构：`{ code, msg, data, show }`，由 `JsonService::success/fail/data/dataLists` 产出。
- 路由为 webman **默认自动路由**：`/应用名/控制器/方法`，新增接口 **无需注册路由**。
- `app/api` 与 `app/adminapi` 共享 `app/common`，业务逻辑各自独立。

---

## 九、后端架构约定

### 9.1 分层

```
Controller（参数校验 + 返回 JSON）
    └── Logic（业务编排）
            └── Service / Model（数据访问与领域能力）
```

- 列表查询统一放 `lists/` 目录，继承 `BaseDataLists`；
- 实现 `ListsSearchInterface` / `ListsSortInterface` / `ListsExcelInterface` 即可开启搜索、排序、Excel 导出（超过 2000 条自动分批）。

### 9.2 中间件与鉴权

`config/middleware.php` 按前缀分组：

- 全局：`Allow`（跨域）+ `Base`（请求日志）
- `adminapi`：`Init` → `Login` → `Auth` → `End`
- `api`：`Init` → `Login` → `End`

- Token 通过 **HTTP Header `token`** 传递，缓存于 Redis（`AdminTokenCache` / `UserTokenCache`）；
- 临近过期自动续期，续期阈值见 `config/project.php` 的 `*.be_expire_duration`；
- 控制器通过 `public array $notNeedLogin = ['login'];` 声明免登录方法；
- RBAC 由 `AuthMiddleware` 比对 `AdminAuthCache`：`root === 1` 超管直接放行，未登记在全量 URI 表中的接口免校验。

### 9.3 常驻内存开发规范（易踩坑）

| 规范 | 说明 |
|---|---|
| **禁止用控制器成员变量保存请求态数据** | 常驻内存下成员变量会在请求间残留，必须使用 `support\Context` + `ContextEnum` |
| 获取当前登录态 | `BaseAdminController` / `BaseApiController` 已用 `__get`/`__set` 代理，`$this->userId`、`$this->adminInfo` 直接可用 |
| 枚举集中管理 | 统一放 `app/common/enum/` |
| 分页 / 导出默认值 | `config/project.php` |
| 修改 PHP 代码 | 必须重启 / reload 服务 |

---

## 十、文件上传（跨端直传）

存储抽象位于 `app/common/service/storage/`：`Driver.php` + `engine/{Local,Server,Aliyun,Qcloud,Qiniu}.php`，配置由 `ConfigService::get('storage')` 读取，`default` 指定当前引擎。

`UploadService::getUploadToken()` 生成上传凭证：当引擎配置了 `region` + `endpoint` 且 `is_oss_req = 1` 时，使用 AWS S3 SDK `createPresignedRequest(PutObject, +1h)` 生成**预签名 PUT URL**。

**直传三步（admin / uniapp 通用）**

1. `POST /{前缀}/upload/getUploadToken`，参数 `{ name, size, contentType }` → 返回中 `is_oss_req == 1` 时取 `req_url`
2. 客户端 `PUT req_url`，body 为文件二进制，**`Content-Type` 必须与签名时一致**
3. `POST /{前缀}/upload/setUploadFile`，参数 `{ cid, type, name, uri: req_file_url, size }` → 服务端 `FileService::setFileUrl()` 去除域名后写入 `file` 表

- `is_oss_req = 0` 时走服务端中转上传。
- admin 端实现：`admin/src/components/upload/indexS3.vue`（`is_oss_req = 0` 时使用 `index.vue`）。
- uniapp 端实现：`uniapp/src/utils/upload.ts` 的 `uploadFile()`，直传失败自动回落到 `/api/upload/image`。
- 小程序需将对象存储域名加入 **request 合法域名**；H5 需在对象存储侧配置 **CORS 允许 PUT**。

---

## 十一、代码生成器

| 组成 | 路径 |
|---|---|
| 控制器 | `app/adminapi/controller/tools/GeneratorController.php` |
| 服务 | `app/common/service/generator/GenerateService.php` |
| 生成器 | `app/common/service/generator/core/`（9 个：Controller / Logic / Lists / Model / Validate / Sql / VueApi / VueIndex / VueEdit，另含 `BaseGenerator` 与 `GenerateInterface`） |
| 模板 | `app/common/service/generator/stub/`（35 个） |

一次性产出：**后端 5 个文件 + 前端 3 个文件 + 菜单 SQL**，支持在线预览、ZIP 下载、直接写入菜单。
入口：后台「开发工具 → 代码生成」。

---

## 十二、部署

### 12.1 Docker 部署后端

前置要求：Docker、Docker Compose。

```bash
cd server

# 1. 确认已配置好 .env（可复制 .example.env）
cp .example.env .env

# 2. 构建并启动
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f server

# 停止 / 重启 / 重新构建
docker compose down
docker compose restart
docker compose up -d --build
```

> 若使用旧版 `docker-compose`（带横线），将上述命令的 `docker compose` 替换为 `docker-compose` 即可。
> 默认映射端口：`8789` / `8790` / `8791` / `8792`。

### 12.2 Nginx 部署（单域名前后台一体）

目录参考：

```
/server     - 后端 API 服务
/admin      - 后台打包产物目录
/pc         - PC 端打包产物目录
```

**后台 API 反代**

```nginx
#PROXY-START/adminapi

location /adminapi/
{
    proxy_pass http://127.0.0.1:8789/adminapi/;
    proxy_set_header Host $host;
    proxy_set_header Scheme $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_http_version 1.1;

    add_header X-Cache $upstream_cache_status;

    set $static_filehlp70f2i 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_filehlp70f2i 1;
        expires 1m;
    }
    if ( $static_filehlp70f2i = 0 )
    {
        add_header Cache-Control no-cache;
    }
}
#PROXY-END/adminapi
```

**C 端 API 反代（pc / uniapp）**

```nginx
#PROXY-START/api

location /api/
{
    proxy_pass http://127.0.0.1:8789/api/;
    proxy_set_header Host $host;
    proxy_set_header Scheme $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_http_version 1.1;

    add_header X-Cache $upstream_cache_status;

    set $static_filehlp70f2i 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_filehlp70f2i 1;
        expires 1m;
    }
    if ( $static_filehlp70f2i = 0 )
    {
        add_header Cache-Control no-cache;
    }
}
#PROXY-END/api
```

**静态资源反代 + 缓存**

```nginx
#PROXY-START/resource

location /resource/
{
    proxy_pass http://127.0.0.1:8789/resource/;
    proxy_set_header Host $host;
    proxy_set_header Scheme $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_http_version 1.1;

    add_header X-Cache $upstream_cache_status;

    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        expires 1m;
    }
    proxy_ignore_headers Set-Cookie Cache-Control expires;
    proxy_cache cache_one;
    proxy_cache_key $host$uri$is_args$args;
    proxy_cache_valid 200 304 301 302 1m;
}

#PROXY-END/resource
```

**后台页面伪静态**

```nginx
location /admin {
    alias /www/wwwroot/your-domain.com/admin;
    index index.html;
    try_files $uri $uri/ /admin/index.html;
}
```

**PC 端页面伪静态**

```nginx
location /pc {
    alias /www/wwwroot/your-domain.com/pc;
    index index.html;
    try_files $uri $uri/ /pc/index.html;
}
```

**慢业务接口分流**（可选）：将耗时接口单独代理到 `SLOW_SERVER_LISTEN` 端口，避免占满主服务进程。

---

## 十三、开发速查

1. **新增后台接口**：在 `app/adminapi/controller` 新建控制器并继承 `BaseAdminController`，列表查询放 `adminapi/lists`，业务逻辑放 `logic`，参数校验放 `validate`；**无需注册路由**。
2. **请求态数据**一律走 `support\Context`，禁止使用控制器成员变量。
3. **修改 PHP 代码后必须重启** webman。
4. **CRUD 优先使用**后台「开发工具 → 代码生成」。
5. 枚举放 `app/common/enum/`；分页 / 导出默认值在 `config/project.php`。

---

## 十四、常见问题

| 问题 | 处理 |
|---|---|
| 修改 PHP 代码后不生效 | 常驻内存模型，执行 `php start.php restart`（或 `reload`） |
| 上传报签名 / CORS 错误 | 检查对象存储 CORS 是否允许 `PUT`，小程序是否配置了 request 合法域名 |
| 接口提示未登录 | 确认请求头携带 `token`，且该控制器方法已加入 `$notNeedLogin` |
| 无权限访问 | RBAC 未授权该 URI，或超级管理员账号 `root !== 1` |
| 慢接口拖垮整体 | 将接口反代到 `SLOW_SERVER_LISTEN` 端口，或改用队列异步处理 |
| Windows 下无热重载 | 属预期行为，文件监控仅在 Linux 生效 |

---

## 十五、参考文档

- [webman 官方文档](https://www.workerman.net/doc/webman/)
- [webman 主页](https://www.workerman.net/webman)
- [Workerman 文档](https://www.workerman.net/doc)
- [likeadmin PHP 版（原项目）](https://gitee.com/likeadmin/likeadmin_php)
- [gather-admin](https://gitee.com/MuZJun/gather-admin)

## 十六、性能压测

[TechEmpower Benchmarks](https://www.techempower.com/benchmarks/#section=test&runid=9716e3cd-9e53-433c-b6c5-d2c48c9593c1&hw=ph&test=db&l=zg24n3-1r&a=2)

![benchmark](https://user-images.githubusercontent.com/6073368/96447814-120fc980-1245-11eb-938d-6ea408716c72.png)

---

## 项目主页

[![歪比巴卜/likeadmin-webman（PHP版）](https://gitee.com/suyibk/workman-likeadmin-all/widgets/widget_card.svg?colors=ffffff,1e252b,323d47,455059,d7deea,99a0ae)](https://gitee.com/suyibk/workman-likeadmin-all)

## LICENSE

[MIT](./LICENSE)