4.2 KiB
Sub2API Business Plugins
独立的 Sub2API 业务插件仓库。插件作为独立服务运行，通过 Sub2API 的公开
HTTP API、管理员鉴权和 custom_menu_items 接入 Core；插件不导入 Core
源码、不连接 Core 数据库，也不修改 Core 的 Go、Vue、迁移或现有
.s2plugin transport ABI。
目录
plugins/plugin-admin：通用插件管理控制面，负责清单、签名、插件市场、 下载入库、启用、停用、升级、回滚、删除、配置、健康检查、审计和菜单注入。plugins/subscription-admin：可选的订阅管理业务模块后端。它不是插件管理 控制面；只有安装并启用后才会挂载到 Plugin Admin 的统一导航中。docs/：插件框架、清单、边界、架构、开发和验收契约。
Plugin Admin 的浏览器控制面位于 plugins/plugin-admin/ui-vue，基于腾讯
TDesign Vue Next starter。运行 plugins/plugin-admin/build-ui.sh 会完成
TypeScript/Vite 构建，并把本地打包的 TDesign、线性图标和 ECharts 嵌入
Go 服务；官方 Core 的 frontend/ 不参与构建。
控制面和业务模块后端可以独立构建和发布，但浏览器端只有一个 Plugin Admin 登录入口。生产环境应使用独立的 低权限服务账号、HTTPS 反向代理、签名包和稳定的 Core API 兼容基线。
推荐部署顺序
先单独部署官方 Sub2API Core，再部署本仓库的插件。官方 Core 的全新 Docker 部署命令（官方仓库和官方镜像）：
mkdir -p /opt/sub2api-core && cd /opt/sub2api-core
curl -fsSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
docker compose -f docker-compose.yml up -d
Core 和插件使用不同的目录、服务、端口及数据边界；不要把插件源码复制到 Core 仓库，也不要让插件连接 Core PostgreSQL/Redis。
快速验证
(cd plugins/plugin-admin && go test -race ./... && go vet ./...)
(cd plugins/subscription-admin && go test -race ./... && go vet ./...)
(cd plugins/subscription-admin && go run ./tools/manifestcheck)
生成订阅插件包：
(cd plugins/subscription-admin && ./package.sh)
构建脚本只生成本地二进制或 dist/ 包，不将它们提交到仓库。
接入顺序
- 启动
plugin-admin和需要的业务模块后端，各自监听独立端口。 - 使用 Core 管理员账号登录 Plugin Admin 一次；普通账号被拒绝，业务模块不再单独登录。
- 在
plugin-admin上传或从插件市场下载并校验业务插件包；包只进入“已入库，待启用”状态。 - 配置 loopback
service_url，点击启用并完成健康检查后，插件才会启动。 - 预览、确认并应用插件声明的管理员菜单；停用后可删除插件。
订阅模块进入统一控制面后使用 /modules/subscription/* 路由。Plugin Admin
通过同源 BFF 代理固定的套餐、订阅和用户只读接口，浏览器不再访问订阅
服务的登录页，也不会创建第二个管理员会话。
Core 继续作为用户、余额、订阅、计费和用量账本的权威来源。插件浏览器端 不持有 Core JWT、Admin Key 或其他服务密钥。
一键部署与卸载
Linux + systemd 环境可直接使用仓库内的安装脚本：
RELEASE_SHA=COMMIT_SHA_40_HEX
curl -fsSL "https://git.awaioi.com/awaioi/sub2api-add/raw/commit/${RELEASE_SHA}/deploy/install.sh" \
| sudo env PLUGIN_REF=v1.1.0 PLUGIN_COMMIT_SHA="$RELEASE_SHA" bash -s -- --plugin all
生产安装必须提供发布提交的 PLUGIN_COMMIT_SHA；上面的 RELEASE_SHA
应从受信任的发布记录中复制，并与 PLUGIN_REF 对应。脚本默认使用
v1.1.0 tag，但 tag 本身不作为完整性证明。可变分支和未 pin 的 tag
仅能在开发环境分别显式开启 PLUGIN_ALLOW_MUTABLE_REF=true 或
PLUGIN_ALLOW_UNPINNED_TAG=true。
默认卸载并保留配置/数据：
RELEASE_SHA=COMMIT_SHA_40_HEX
curl -fsSL "https://git.awaioi.com/awaioi/sub2api-add/raw/commit/${RELEASE_SHA}/deploy/uninstall.sh" \
| sudo bash -s -- --plugin all
需要清除插件配置、数据和源码时，显式使用 --purge --yes。完整部署、反向
代理、菜单应用和升级说明见 deploy/README.md。