主题后台扩展机制
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 会通过统一扩展注册中心完成下面的流程:
- 读取当前
active_theme - 加载该主题的
theme.admin.json - 匹配当前访问路由
- 从
admin/pages中找到对应组件 - 通过统一后台扩展入口完成渲染
核心装载逻辑位于 useAdminExtensions.ts。
路由命名空间
主题后台扩展页统一走:
/admin/extensions/*
公共入口页位于:
这个页面负责承载所有主题后台扩展组件。
侧栏与搜索自动接入
已注册的扩展页会自动注入到:
- 默认后台侧栏
- 移动端后台菜单
- 后台路由搜索面板
相关文件:
这意味着新增主题后台页时,不需要再去到处手工补多个菜单入口。
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/custom | GET | ext:panel:appstore:view | 返回自建应用定义与预设;?key=... 返回单个定义。版本对象可包含 dataYml、envContent。 |
/api/admin/panel/apps/custom | POST | ext:panel:appstore:edit | 保存版本、重新打包离线包并重建目录。 |
/api/admin/panel/apps/compose | GET | ext: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 与对应离线包,再重建目录。发布只影响后续下载,不改动已安装容器。