# plugin-center

**Repository Path**: topextend/plugin-center

## Basic Information

- **Project Name**: plugin-center
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Plugin Center（插件中心）

ThinkPHP 8 + Vue 3 全栈 **插件市场与管理平台**，前后端同仓。在通用管理后台框架（基于 [Kadmin](https://gitee.com/topextend/kadmin) / [topextend/think-library](https://packagist.org/packages/topextend/think-library)）之上，扩展插件生态运营能力：开发者入驻、插件发布与审核、市场运营、用户浏览下载，以及钱包 / 收益 / 提现等财务能力。

---

## 目录

- [产品定位与三端门户](#产品定位与三端门户)
- [技术栈](#技术栈)
- [目录结构](#目录结构)
- [架构说明](#架构说明)
- [数据库设计](#数据库设计)
- [菜单与权限](#菜单与权限)
- [安装部署](#安装部署)
- [本地开发](#本地开发)
- [环境配置](#环境配置)
- [API 概览](#api-概览)
- [插件业务生命周期](#插件业务生命周期)
- [CLI 命令](#cli-命令)
- [已有库升级](#已有库升级)
- [生产部署](#生产部署)
- [常见问题](#常见问题)
- [相关仓库](#相关仓库)

---

## 产品定位与三端门户

系统面向三类用户，共用一套 API 与前端工程，通过 **路由门户（portal）** 区分体验与登录态：

| 门户 | 访问路径 | 登录账号表 | 用途 |
|------|----------|------------|------|
| **运营后台** | `/login`、`/dashboard`、`/review/*`、`/market/*`、`/setting/*` | `platform_user` | 平台运营：RBAC 动态菜单、审核工作台、市场运营、系统配置 |
| **插件市场** | `/store/*` | `platform_market_user` | 终端用户：浏览插件、注册登录、下载、钱包充值、申请开发者 |
| **开发者工作台** | `/developer/*` | `platform_market_user`（需 `platform_developer.status=active`） | 插件开发者：入驻申请、我的插件、版本提交 |

**账号隔离原则（重要）**

- `platform_user`：后台运营人员，走 JWT `type=admin`，受 RBAC 菜单与按钮权限控制。
- `platform_market_user`：市场/开发者前台账号，走 JWT `type=store`，与运营账号 **物理表隔离、不可混用**。
- 超级管理员：`platform_config.base.super_user_id` 记录安装时创建的首个管理员 ID（`AdminSuperUser`），非硬编码 `id=1`。

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | PHP >= 8.1、ThinkPHP 8、think-orm、think-filesystem |
| 核心库 | topextend/think-library ^1.0（JWT、RBAC、操作日志、系统配置） |
| 前端 | Vue 3.5、TypeScript、Vite 8、Element Plus、Pinia、Vue Router 5、vue-i18n |
| 数据库 | MySQL 或 PostgreSQL（二选一，安装时选择） |
| 包管理 | Composer（后端）、npm（前端） |

默认开发端口：

| 服务 | 地址 |
|------|------|
| 后端 API | `http://127.0.0.1:8788` |
| 前端 SPA | `http://127.0.0.1:5175` |
| 安装向导 | `http://127.0.0.1:5175/install` |

---

## 目录结构

```
plugin-center/
├── app/                              # PHP 后端（ThinkPHP 多应用）
│   ├── admin/                        # 管理 API，URL 前缀 /admin
│   │   ├── application/              # 业务用例层（*Manage 类）
│   │   │   ├── AdminMenuCatalog.php  # 通用后台菜单目录
│   │   │   ├── PluginMenuCatalog.php # 插件中心菜单扩展（审核/市场）
│   │   │   ├── AdminMenuSync.php     # 菜单同步到 platform_menu
│   │   │   ├── DeveloperManage.php   # 开发者入驻与审核
│   │   │   ├── PluginManage.php      # 插件 CRUD、包上传
│   │   │   ├── PluginReviewManage.php# 版本审核
│   │   │   ├── StoreManage.php       # 市场前台 API
│   │   │   ├── StoreWalletManage.php # 钱包/提现
│   │   │   ├── PortalConfigManage.php# 市场/开发者门户页配置
│   │   │   └── …
│   │   ├── controller/               # HTTP 薄控制器
│   │   ├── persistence/              # Repository 数据访问
│   │   ├── command/                  # CLI 命令
│   │   └── route/app.php             # 全部 Admin 路由
│   ├── install/                      # 安装向导 API，前缀 /install
│   └── index/                        # 默认应用（健康检查等）
│
├── config/                           # ThinkPHP 全局配置
│   ├── app.php                       # 多应用映射、CORS
│   ├── library.php                   # think-library 绑定
│   ├── database.php / jwt.php / …
│   └── console.php                   # CLI 命令注册
│
├── database/                         # 安装 SQL（MySQL / PostgreSQL 各一套）
│   ├── mysql/
│   │   ├── install.sql               # 通用 platform_* 表 + 种子
│   │   ├── menu-buttons.sql          # RBAC 按钮与 api_list
│   │   ├── table-columns.sql         # 列表页默认列配置
│   │   ├── plugin-tables.sql         # 插件业务表（安装时自动执行）
│   │   └── plugin-table-columns.sql  # 插件相关列表列配置
│   └── pgsql/                        # 同上，PostgreSQL 语法
│
├── deploy/                           # 生产部署脚本与说明
│   ├── DEPLOY.md
│   ├── deploy.sh
│   ├── post-pull.sh
│   └── prepare-dist.sh
│
├── lang/                             # 后端语言包（zh-cn / en-us）
├── public/                           # Web 根目录（站点运行目录指向此处）
│   ├── index.php                     # 入口
│   ├── dist/                         # 前端构建产物（npm run build）
│   ├── storage/                      # 本地上传文件（Git 忽略）
│   └── install.lock                  # 安装完成标记（Git 忽略）
│
├── runtime/                          # 缓存与日志（Git 忽略）
│
├── web/                              # 前端源码（Vue 3 SPA）
│   ├── src/
│   │   ├── views/
│   │   │   ├── install/ login/ dashboard/ setting/ user/  # 通用后台
│   │   │   ├── review/               # 审核工作台
│   │   │   ├── market/               # 市场运营
│   │   │   ├── store/                # 插件市场门户
│   │   │   ├── developer/            # 开发者工作台
│   │   │   └── error/                # 404 / 服务不可用
│   │   ├── layout/
│   │   │   ├── index.vue             # 运营后台布局
│   │   │   ├── store/                # 市场布局
│   │   │   └── developer/            # 开发者布局
│   │   ├── router/                   # 静态路由 + 动态 RBAC 路由
│   │   ├── stores/                   # user / site / portalSession 等
│   │   ├── api/                      # 接口封装（按模块拆分）
│   │   └── components/               # ScTable、MediaPicker、portal 等
│   └── vite.config.ts                # 构建输出 → ../public/dist
│
├── .env.example                      # 后端环境变量模板
├── composer.json / composer.lock
├── package.json                      # 根目录：npm run dev 启动 PHP 内置服务
└── README.md
```

更细的前端说明见 **[web/README.md](web/README.md)**，数据库 SQL 说明见 **[database/README.md](database/README.md)**。

---

## 架构说明

### 后端分层

```
HTTP 请求
  → Controller（参数校验、统一 success/error 响应）
    → Manage / Application（业务编排、权限校验）
      → Repository（单表 CRUD）
        → platform_* 数据表
```

- **Controller**：继承 `AdminController`，不含复杂业务。
- **Manage**（`application/`）：如 `UserManage`、`PluginManage`、`StoreWalletManage`。
- **Repository**（`persistence/`）：如 `PluginCatalogRepository`、`DeveloperRepository`。
- **think-library**：通过 `config/library.php` 注入 JWT、RBAC 守卫、操作日志等；中间件由库自动注册。

### 前端路由

| 类型 | 来源 | 说明 |
|------|------|------|
| 静态路由 | `router/systemRoutes.ts` | 安装、登录、市场、开发者、错误页 |
| 动态路由 | `GET /admin/bootstrap` 返回菜单树 | 运营后台 `views/setting/*`、`review/*`、`market/*` |

安装门控（与 Kadmin 同步）：

| 条件 | 行为 |
|------|------|
| 存在 `public/install.lock` 或 API 返回 `installed/lock` | 正常业务 |
| 无 lock，安装 API 可用 | 跳转 `/install` |
| 无 lock，安装 API 不可用 | 跳转 `/error/service` |

---

## 数据库设计

表前缀默认为 **`platform_`**（安装时可填 `DB_PREFIX`，SQL 中的 `platform_` 会被替换）。

### 通用表（`install.sql`）

| 表 | 用途 |
|----|------|
| `platform_user` | **运营后台**管理员 |
| `platform_role` / `platform_user_role` / `platform_role_menu` | RBAC |
| `platform_dept` | 部门 |
| `platform_menu` | 菜单树（含按钮节点与 `api_list`） |
| `platform_config` / `platform_data` | 系统配置与扩展数据 |
| `platform_dict` / `platform_dict_item` | 数据字典 |
| `platform_table` | 各列表页表格列 JSON |
| `platform_message` | 消息中心 |
| `platform_queue` | 计划任务 |
| `platform_media` | 素材库（含 `owner_id`：0=后台，>0=市场用户图片空间） |
| `platform_oplog` | 操作日志 |
| `platform_async_task` | 异步任务 |

### 插件业务表（`plugin-tables.sql`，安装时自动执行）

| 表 | 用途 |
|----|------|
| `platform_market_user` | 市场/开发者前台账号 |
| `platform_developer` | 开发者入驻资料与审核状态 |
| `platform_category` | 插件类目 |
| `platform_catalog` | 插件商品（code、描述、价格类型等） |
| `platform_version` | 插件版本包（`.plug` 路径、manifest、审核状态） |
| `platform_review` | 审核操作记录 |
| `platform_market_wallet_log` | 消费钱包流水 |
| `platform_market_earnings_log` | 开发者收益流水 |
| `platform_market_payout_method` | 提现方式 |
| `platform_market_withdrawal` | 提现申请 |
| `platform_market_settlement` | 开发者结算单 |

表格列：`TableColumnSeeds.php` 为逻辑来源；全新安装时由 `database/*/plugin-table-columns.sql` 写入 `platform_table`；运行后以数据库为准。详见 `docs/ecosystem.md` §6.4。

---

## 菜单与权限

菜单 **不在独立 SQL 种子** 里手写业务模块，而是：

1. **PHP 目录定义**
   - `AdminMenuCatalog`：控制台 + 系统配置（用户/角色/字典/素材等）
   - `PluginMenuCatalog`：经 `AdminMenuRegistry::extend()` 追加 **审核工作台**、**市场运营**
2. **同步入库**：安装向导或 CLI 将目录 upsert 到 `platform_menu`
3. **运行时**：`AdminMenuBuilder` 从数据库按 RBAC 构建侧栏；前端 `bootstrap` 动态注册路由

运营后台插件相关菜单节点：

| 模块 | 路径 | 说明 |
|------|------|------|
| 审核工作台 | `/review/developers`、`/review/plugins` | 开发者/插件版本审核 |
| 市场运营 | `/market/category`、`/market/plugins`、`/market/portal`、`/market/portal-decorate`、`/market/orders`、`/market/users` | 类目、上架管理、门户配置、门户装修、订单、市场用户 |

```bash
# 已有库补同步菜单（升级或改过 PluginMenuCatalog 后执行）
php think admin:menu:sync
```

---

## 安装部署

### 方式一：Web 安装向导（推荐）

1. Web 服务器 **运行目录指向 `public/`**
2. 安装依赖：

```bash
composer install
cp .env.example .env
cd web && npm install && npm run build && cd ..
```

3. 浏览器访问 **`https://your-domain/install`**（本地：`http://127.0.0.1:5175/install`）
4. 按向导完成：环境检测 → 数据库 → 管理员 → 站点/存储/安全 → 完成
5. 生成 **`public/install.lock`**，此后 `/install` 拒绝重复安装

安装向导自动执行 SQL 顺序：

```
install.sql → menu-buttons.sql → table-columns.sql
  → plugin-tables.sql → plugin-table-columns.sql
```

并会：写入 `.env`、记录 `super_user_id`、合并 `CORS_ORIGINS`（支持 `frontend_origin` 参数）、生成 JWT、执行 `AdminMenuSync::sync()`。

### 方式二：手动导入 SQL

```bash
composer install && cp .env.example .env
# 编辑 .env

# MySQL 示例
mysql -u root -p your_db < database/mysql/install.sql
mysql -u root -p your_db < database/mysql/menu-buttons.sql
mysql -u root -p your_db < database/mysql/table-columns.sql
mysql -u root -p your_db < database/mysql/plugin-tables.sql
mysql -u root -p your_db < database/mysql/plugin-table-columns.sql

php think admin:menu:sync
```

手动导入后仍建议通过 `/install` 或自行创建管理员与 JWT；**推荐始终走安装向导**。

---

## 本地开发

**终端 1 — 后端**

```bash
composer install
cp .env.example .env
# 根目录快捷启动（8788）
npm run dev
# 或
php think run --host 0.0.0.0 --port 8788
```

**终端 2 — 前端**

```bash
cd web
npm install
npm run dev
```

- 前端：`http://127.0.0.1:5175`
- API 代理：Vite 将 `/admin`、`/install/`、`/storage` 代理到 `8788`
- 开发时 `web/.env` 中 `VITE_API_URL` 可留空，走代理

类型检查与生产构建：

```bash
cd web && npm run build   # 含 vue-tsc，输出到 public/dist/
```

---

## 环境配置

### 后端 `.env`

| 变量 | 说明 |
|------|------|
| `APP_DEBUG` | 调试模式（生产务必 `false`） |
| `DB_DRIVER` | `mysql` 或 `pgsql` |
| `DB_HOST` / `DB_NAME` / `DB_USER` / `DB_PASS` / `DB_PORT` | 数据库连接 |
| `DB_PREFIX` | 表前缀（默认空，即 `platform_`） |
| `DEFAULT_LANG` | 默认语言 `zh-cn` / `en-us` |
| `CORS_ORIGINS` | 允许跨域的前端 Origin，逗号分隔；安装时自动合并 |
| `CLOUD_JWT_SECRET` | JWT 密钥（≥32 位；安装向导也会写入 `platform_config`） |
| `OFFICIAL_INIT_PASSWORD` | 官方发布账号 `official` 的初始/重置密码参考值 |

### 前端 `web/.env.production`

```env
# 前后端同域（Nginx 反代 /admin）
VITE_API_URL=/admin

# 前后端分域
VITE_API_URL=https://api.example.com/admin
```

模板：`web/.env.production.example`

### `config/library.php`

绑定 think-library 与业务表：`platform_config`、`platform_data`、JWT scope `admin`、RBAC 节点匹配等。详见 Kadmin 文档。

---

## API 概览

多应用映射见 `config/app.php`：`/admin/*` → `app/admin`，`/install/*` → `app/install`。

### 通用后台 `/admin`

| 分组 | 示例 | 说明 |
|------|------|------|
| 认证 | `POST /admin/auth/login` | 运营登录（`portal=admin`） |
| 注册 | `POST /admin/auth/register` | 市场用户注册 |
| 引导 | `GET /admin/bootstrap` | 菜单、权限、`super_user_id`、站点信息 |
| 用户/系统 | `GET /admin/admin/list` | 用户、角色、部门、菜单、字典、队列表等 |
| 配置 | `PUT /admin/config/sys` | 站点与安全 |
| 素材 | `POST /admin/media/upload` | 运营后台素材库（`owner_id=0`） |
| 账户 | `GET /admin/account/messages` | 个人中心、消息、任务 |

完整路由：**`app/admin/route/app.php`**

### 插件域 `/admin`

| 前缀 | 说明 |
|------|------|
| `/admin/developer/*` | 开发者入驻、审核、资料（运营侧 list/approve/reject；前台 status/apply/profile） |
| `/admin/plugin/*` | 插件 CRUD、包上传、版本提交/发布/下架 |
| `/admin/review/*` | 待审列表、通过/驳回、上架、版本包下载 |
| `/admin/market/*` | 类目、推荐、门户配置（store/developer 登录页）、市场用户管理 |
| `/admin/store/*` | 市场前台：类目/列表/详情/下载（公开或需市场登录） |
| `/admin/account/wallet/*` | 市场用户钱包、充值、收益、提现（需 `type=store` JWT） |
| `/admin/account/media/*` | 市场用户图片空间（按 `owner_id` 隔离，有配额） |

### 安装 `/install`

| 路径 | 说明 |
|------|------|
| `GET /install/status` | 安装状态（`installed`、`lock`） |
| `GET /install/check` | 环境检测 |
| `POST /install/db-test` | 数据库连接测试 |
| `POST /install/db-migrate` | 执行全部安装 SQL |
| `POST /install/admin` | 创建管理员 + `super_user_id` |
| `PUT /install/site` | 站点信息 |
| `PUT /install/storage` | 存储配置 |
| `PUT /install/security` | JWT、登录开关等 |
| `POST /install/finish` | 完成安装（可传 `frontend_origin`） |

---

## 插件业务生命周期

```
开发者注册 (platform_market_user)
  → 提交入驻申请 (platform_developer: pending)
  → 运营审核通过 (active)
  → 创建插件 (platform_catalog: draft)
  → 上传版本包 .plug (platform_version: draft)
  → 提交审核 (pending_review)
  → 运营审核通过 (approved) → 上架 publish (published)
  → 市场用户浏览/下载 (/store)
```

状态字段详见 `platform_developer.status`、`platform_catalog.status`、`platform_version.status`。

官方语言包等种子数据：

```bash
php think plugin:seed-official-lang
php think official:reset-password   # 重置 official 账号密码
```

---

## CLI 命令

| 命令 | 说明 |
|------|------|
| `php think admin:menu:sync` | 将 PHP 菜单目录同步到 `platform_menu` |
| `php think admin:queue:run` | 执行到期计划任务（建议 crontab 每分钟） |
| `php think admin:queue:exec` | 执行单条队列任务 |
| `php think official:reset-password` | 重置官方发布账号密码 |
| `php think plugin:seed-official-lang` | 种子官方语言包插件数据 |

```cron
* * * * * cd /path/to/plugin-center && php think admin:queue:run >> /dev/null 2>&1
```

---

## 已有库升级

从旧版或仅含通用表的环境升级：

```bash
# 1. 补插件业务表（已存在则跳过）
mysql -u root -p your_db < database/mysql/plugin-tables.sql

# 2. 补插件列表列配置（可选）
mysql -u root -p your_db < database/mysql/plugin-table-columns.sql

# 3. 同步菜单与 RBAC 节点
php think admin:menu:sync

# 4. 拉取代码后更新依赖并重建前端
composer install
cd web && npm ci && npm run build
```

若从 **Kadmin** 基座迁移：本仓库已同步 Kadmin 的样式、安装门控、超级管理员、`AdminSuperUser`、响应式布局等修复，并保留插件中心扩展模块。

---

## 生产部署

详见 **[deploy/DEPLOY.md](deploy/DEPLOY.md)**。

概要：

1. 克隆代码，`cp .env.example .env`，`cp web/.env.production.example web/.env.production`
2. `composer install --no-dev`
3. `cd web && npm ci && npm run build` → `public/dist/`
4. 站点运行目录 **`public/`**
5. 访问 `/install` 完成首次配置
6. Gitee WebHook + 宝塔：`bash deploy/post-pull.sh`（**禁止** `composer update` / `npm update`）

**勿提交 Git**：`.env`、`web/.env.production`、`public/install.lock`、`public/storage/`、`runtime/`、`vendor/`、`web/node_modules/`、`public/dist/`。

---

## 常见问题

**跨域失败**  
检查 `.env` 中 `CORS_ORIGINS` 是否与浏览器 Origin 完全一致（含协议、端口）。安装完成时会自动合并当前访问域名。

**菜单缺少「审核/市场」**  
执行 `php think admin:menu:sync`，并为角色分配对应菜单权限。

**市场图片空间配额**  
`platform_market_user.media_quota` / `media_used`；素材表 `platform_media.owner_id` 按用户隔离。

**构建 EPERM（宝塔 `.user.ini`）**  
见 `deploy/DEPLOY.md`；`vite.config.ts` 已设 `emptyOutDir: false`，构建前由 `deploy/prepare-dist.sh` 清理。

**PostgreSQL 表前缀**  
安装向导在 `pgsql` 下会校验前缀格式；测试连接前请按向导提示填写合法前缀。

---

## 相关仓库

| 项目 | 说明 |
|------|------|
| [topextend/think-library](https://packagist.org/packages/topextend/think-library) | JWT / RBAC / Oplog 基础设施 |
| [Kadmin](https://gitee.com/topextend/kadmin) | 通用管理后台基座（本项目的上游修复来源） |

---

## 许可证

MIT — 见 [LICENSE.txt](LICENSE.txt)