主题后台扩展机制

APayShop 现已支持 主题自带后台扩展页。这套机制允许当前激活主题提供自己的后台工作区,但不会替换系统核心 /admin 后台框架。

设计目标

目标不是让每个主题完整重写后台,而是让主题通过统一扩展边界,向系统后台注册自己的页面。

也就是说:

  • 核心后台页面仍然放在 app/pages/admin/
  • 登录鉴权、后台布局、系统级流程仍然由主系统统一维护
  • 主题自己的后台页统一挂在 /admin/extensions/*

目录结构

每个主题都可以通过下面的结构注册自己的后台页:

app/themes/[theme]/
  theme.admin.json
  admin/
    pages/
      theme-workspace.vue
      content-studio.vue

Manifest 文件

主题后台扩展注册文件为:

app/themes/[theme]/theme.admin.json

这个文件负责声明当前主题有哪些后台扩展页需要暴露出来。

页面组件目录

真正的 Vue 页面组件放在:

app/themes/[theme]/admin/pages/

运行时流程

运行时,APayShop 会通过统一扩展注册中心完成下面的流程:

  1. 读取当前 active_theme
  2. 加载该主题的 theme.admin.json
  3. 匹配当前访问路由
  4. 从 admin/pages 中找到对应组件
  5. 通过统一后台扩展入口完成渲染

核心装载逻辑位于 useAdminExtensions.ts。

路由命名空间

主题后台扩展页统一走:

/admin/extensions/*

公共入口页位于:

extensions route

这个页面负责承载所有主题后台扩展组件。

侧栏与搜索自动接入

已注册的扩展页会自动注入到:

  • 默认后台侧栏
  • 移动端后台菜单
  • 后台路由搜索面板

相关文件:

这意味着新增主题后台页时,不需要再去到处手工补多个菜单入口。

Manifest 示例

{
  "name": "Extensions",
  "pages": [
    {
      "key": "theme-workspace",
      "title": "Theme Workspace",
      "description": "管理当前主题的运营工作区。",
      "route": "/admin/extensions/theme-workspace",
      "component": "theme-workspace.vue",
      "icon": "ph:stack",
      "order": 10
    }
  ]
}

当前约定

API 鉴权与宿主接入

在 theme.admin.json 旁的 theme.host.json 声明主题 API 权限:

{
  "adminApiPermissions": {
    "models": { "permission": "ext:example:models" }
  }
}

/api/admin/example/models 与已有的 /api/example/admin/models 兼容地址都 进入宿主管理员鉴权,并使用相同权限。GET/HEAD 要求 ext:example:models:view,写操作要求 :edit;存量不带后缀的 ext:example:models 同时允许读写。未映射接口仍只允许拥有全部权限的管理员。 兼容地址也进入统一操作审计。

存量服务令牌回调必须声明具体路由与允许方法,处理器仍复核令牌,不能豁免标准后台地址。 Qingpu 维护任务与规则包发布继续使用原有凭证。

theme.host.json 还声明程序管理的公开/私有设置、前台登录策略、Sitemap 数据源 和主题构建检查。修改后运行 node scripts/generate-theme-build.mjs。 前台主题与业务 API 分开选择:不设置 APAY_SERVER_THEMES 时保留已有生产 API; 显式列表包含指定业务模块及当前构建的前台主题,core 表示仅保留前台主题自身的 API。

核心工单截图改走 POST /api/admin/tickets/upload(tickets:edit)或 POST /api/users/tickets/upload(已登录用户)。通过 multipart 提交一个 file, 返回 { "url": "/uploads/tickets/..." }。支持 JPEG、PNG、WebP,最大 10MB。 原有附件地址继续有效,上传不再依赖主题数据库或外部 Provider 凭证。

使用主题后台扩展机制时,建议严格遵循以下规则:

  • 核心后台页面继续保留在 app/pages/admin/
  • 主题专属后台页面只放在主题目录里
  • 扩展入口统一通过 theme.admin.json 注册
  • 路由统一走 /admin/extensions/*
  • 不要让主题整体接管整个后台 layout

为什么这很重要

这种方式可以让 APay:

  • 更容易维护
  • 更安全地升级
  • 更适合多模板并存
  • 更方便 AI 理解和生成扩展结构

简而言之:现在主题已经可以扩展后台,但系统仍然拥有后台壳。

Panel 自建应用

Panel 应用商店编辑器支持 docker-compose.yml、data.yml 和 .env。编辑 data.yml 后移出编辑器,安装参数表格会同步更新;修改表格则同步更新 additionalProperties.formFields。保存时以 YAML 中的默认值作为发布目录的来源,保留数字、布尔值、选择项和自定义元数据。应用 Key 与版本号以对应表单字段为准。

.env 是独立的环境变量默认值文件,保留注释、引号和空值;修改它不会重写安装表单默认值。最终安装值按 GoPanel 的安装流程与 Compose 规则解析。

接口方法权限契约
/api/admin/panel/apps/customGEText:panel:appstore:view返回自建应用定义与预设;?key=... 返回单个定义。版本对象可包含 dataYml、envContent。
/api/admin/panel/apps/customPOSText:panel:appstore:edit保存版本、重新打包离线包并重建目录。
/api/admin/panel/apps/composeGEText:panel:appstore:view传入 key、version,从实际安装包返回 { compose, dataYml, envContent, filePath, isLocal, isFallback? };不存在的附属文件返回空字符串。

POST 的原有字段(key、name、version、compose、formFields 及应用元数据)继续支持,新增两个可选文本字段:

  • dataYml:应用版本的 YAML 元数据。非空时优先于请求中的 formFields,其中的 additionalProperties.formFields 同时用于安装包与目录;传空文本则根据表单生成,省略则保留已有自定义元数据并允许旧客户端更新 formFields。
  • envContent:原样保存的 .env 文本。传空字符串会写入空 .env,省略则保留已有内容。内容仅通过管理员接口返回,并包含在可下载的应用安装包中,不进入公开目录 JSON。

响应为 { code: 0, data }。YAML 语法错误、非对象元数据、无效安装参数或非文本文件内容在写入前返回 HTTP 400。上传注册与后续编辑会保留 .env、data.yml 及其他附属文件。旧记录缺少新字段时从本地包读取;若旧版本已经丢弃这些文件,需从原始安装包恢复。

新包生成完成后才替换旧包并保存自建应用记录。YAML 校验或 tar 生成失败时,原包与记录保持不变。文件替换和后续目录构建分别执行:替换后出现 I/O 或目录构建失败,可能需要恢复备份的 data/custom-apps.json 与对应离线包,再重建目录。发布只影响后续下载,不改动已安装容器。