05 插件市场

功能说明

插件市场让管理员在后台浏览官方插件目录、从远程下载安装包、一键安装。

入口：后台 → 插件管理 → 插件市场 Tab。

注意：不支持插件市场离线部署。 生产/内网环境无法通过随代码携带 packages/*.zip 在市场内一键安装；请改用下方 压缩包安装。插件市场仅适用于配置了 MARKETPLACE_SERVER 且能访问外网的 开发环境。

---

两种插件安装方式

方式	适用场景	操作概要
压缩包安装	生产部署、内网、离线	将插件 zip 解压到 public/plugins/{type}/{name}/，在 本地插件 Tab 点击「安装」
开发环境安装	本地开发、联调	.env 配置 MARKETPLACE_SERVER，在 插件市场 Tab 浏览并一键安装

方式一：压缩包安装（生产推荐）

适用于宝塔部署、内网机房、无法访问插件 CDN 的环境。

1. 获取官方插件 zip（单独分发，或从源码 public/plugins/ 目录打包）
2. 解压到 public/plugins/{type}/{name}/（如 public/plugins/addon/login_log/）
3. 后台 插件管理 → 本地插件，找到对应插件，点击 安装
4. 配置、启停均在 本地插件 Tab 完成

zip 包结构见本文 zip 包结构 一节。

方式二：开发环境安装

适用于本地 dev-all.sh 或具备外网的服务器。

1. .env 配置 MARKETPLACE_SERVER（见 配置）
2. 后台 插件管理 → 插件市场 浏览目录
3. 点击 安装 或 升级（从远程下载并解压到 public/plugins/）

resources/marketplace/packages/ 下的 zip 仅供构建发布，不作为生产离线安装介质。

---

数据来源

市场目录（catalog）

1. resources/marketplace/catalog.json（本地官方目录，必带）
2. 远程 GET {MARKETPLACE_SERVER}/api/marketplace/catalog（可选，与本地合并）

未配置 MARKETPLACE_SERVER 时，市场 Tab 仅展示本地目录，无法下载远程包；此时请使用压缩包安装。

市场安装时的包来源（仅开发环境）

配置了 MARKETPLACE_SERVER 且网络可达时，按以下顺序查找：

1. 磁盘已有 public/plugins/{type}/{name}/  → 跳过下载
2. 远程 MARKETPLACE_SERVER 下载

resources/marketplace/packages/ 中的 zip 由 build-marketplace.php 生成，用于发布到市场服务器，不参与生产离线部署。

---

配置

.env

[APP]
MARKETPLACE_SERVER = https://market.kede-finance.com

• 开发环境：填写官方或自建市场地址，启用插件市场一键安装
• 生产/内网：留空即可；插件通过 压缩包安装，不依赖市场下载

也可在后台系统设置写入 general.marketplace_server（优先级高于 .env）。

---

后台 API

方法	路径	说明
GET	/admin/marketplace/index	目录列表（type/keyword/page）
GET	/admin/marketplace/detail	单个插件详情
POST	/admin/marketplace/fetch	仅下载到 plugins 目录
POST	/admin/marketplace/install	下载 + 执行 install()
POST	/admin/marketplace/upgrade	覆盖文件 + 更新版本号

参数：type、name（与插件目录名一致）

---

catalog.json 格式

路径：resources/marketplace/catalog.json

{
  "updated_at": "2026-06-11T00:00:00+08:00",
  "slug": "kede-finance",
  "items": [
    {
      "type": "addon",
      "name": "login_log",
      "title": "登录日志",
      "description": "...",
      "author": "KeDe",
      "version": "1.0.0",
      "category": "安全审计",
      "tags": ["登录", "日志"],
      "price": 0,
      "official": true,
      "bundled": true,
      "download_url": "",
      "sha256": ""
    }
  ]
}

字段	说明
download_url	完整 zip 下载地址（远程包必填）
sha256	包校验（推荐）
bundled	是否随系统分发
price	0 表示免费（预留付费扩展）

---

生成发布包（开发者）

cd kede-finance
php scripts/build-marketplace.php

脚本会：

1. 扫描 public/plugins/ 全部类型
2. 为每个插件打 zip 到 resources/marketplace/packages/{type}/{name}.zip
3. 重写 catalog.json 并填入 sha256

用途： 将 packages/ 与 catalog.json 部署到 MARKETPLACE_SERVER，供开发环境拉取。不要将其作为生产离线安装包随系统分发。

---

自托管市场服务器（可选）

若需自建插件 CDN，实现以下 HTTP API 即可对接：

GET /api/marketplace/catalog

查询参数：slug（产品标识，如 kede-finance）、可选 type、keyword、page

响应：

{
  "status": 200,
  "msg": "ok",
  "data": {
    "items": [ /* 同 catalog.json items */ ]
  }
}

GET /api/marketplace/download

查询参数：type、name、slug

响应：二进制 zip 文件（根目录为 {name}/ 或直接插件文件）

参考实现说明：kede-finance/resources/marketplace-server/README.md

---

zip 包结构

解压目标：public/plugins/{type}/{name}/

支持两种布局：

# 布局 A（推荐）
login_log/
  LoginLog.php
  hooks.php
  config.php

# 布局 B
LoginLog.php
hooks.php
config.php

由 PluginPackageHelper::extract() 自动识别。

---

典型操作流程

生产：压缩包安装「登录日志」

1. 将 login_log.zip 解压到 public/plugins/addon/login_log/
2. 打开 本地插件 Tab，筛选 type=addon
3. 找到「登录日志」，点击 安装
4. 配置、启停均在本地插件页完成

开发：从市场安装「登录日志」

1. 确认 .env 已配置 MARKETPLACE_SERVER
2. 打开 插件市场 Tab，筛选 type=addon
3. 找到「登录日志」，点击 安装（远程下载 + 注册）
4. 若磁盘已有文件则跳过下载，直接 PluginService::install()

开发者：发布新插件到市场

1. 在 public/plugins/sms/my_sms/ 开发完成
2. 运行 php scripts/build-marketplace.php
3. 将 catalog.json + packages/ 部署到 MARKETPLACE_SERVER

---

核心代码位置

文件	作用
app/common/service/MarketplaceService.php	目录、下载、安装
app/common/support/PluginPackageHelper.php	zip 解压/打包
app/admin/controller/Marketplace.php	后台 API
frontend/admin/src/views/system/plugins/MarketplacePanel.vue	市场 UI

---

下一章：06-支付网关