115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
# 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 兼容基线。业务 `.s2plugin` 归档必须使用受信发布者签名；Plugin
|
|
Admin 本身是独立的控制面服务，使用 immutable commit checkout 后本地编译，
|
|
不通过 `.s2plugin` 发布。
|
|
|
|
## 推荐部署顺序
|
|
|
|
先单独部署官方 Sub2API Core，再部署本仓库的插件。官方 Core 的全新 Docker
|
|
部署命令（官方仓库和官方镜像）：
|
|
|
|
```sh
|
|
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。
|
|
|
|
## 快速验证
|
|
|
|
```sh
|
|
(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)
|
|
```
|
|
|
|
生成订阅业务插件包（Plugin Admin 本身不生成 `.s2plugin`）：
|
|
|
|
```sh
|
|
(cd plugins/subscription-admin && ./package.sh)
|
|
```
|
|
|
|
构建脚本只生成本地二进制或 `dist/` 包，不将它们提交到仓库。
|
|
|
|
## 接入顺序
|
|
|
|
1. 启动 `plugin-admin` 和需要的业务模块后端，各自监听独立端口。
|
|
2. 使用 Core 管理员账号登录 Plugin Admin 一次；普通账号被拒绝，业务模块不再单独登录。
|
|
3. 在 `plugin-admin` 上传或从插件市场下载并校验业务插件包；包只进入“已入库，待启用”状态。
|
|
4. 对托管 command 插件，点击启用后由控制面启动进程并完成健康检查；对
|
|
`subscription-admin` 这类 external 插件，必须先由部署者或 systemd 启动
|
|
后端，再配置 loopback `service_url`，启用只负责探测和挂载，不会替外部服务
|
|
创建进程。
|
|
5. 预览、确认并应用插件声明的管理员菜单；停用后可删除插件。
|
|
|
|
订阅模块进入统一控制面后使用 `/modules/subscription/*` 路由。Plugin Admin
|
|
通过同源 BFF 代理固定的套餐、订阅和用户只读接口，浏览器不再访问订阅
|
|
服务的登录页，也不会创建第二个管理员会话。
|
|
|
|
Core 继续作为用户、余额、订阅、计费和用量账本的权威来源。插件浏览器端
|
|
不持有 Core JWT、Admin Key 或其他服务密钥。
|
|
|
|
## 一键部署与卸载
|
|
|
|
Linux + systemd 环境可直接使用仓库内的安装脚本：
|
|
|
|
```sh
|
|
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.1 PLUGIN_COMMIT_SHA="$RELEASE_SHA" bash -s -- --plugin all
|
|
```
|
|
|
|
生产安装必须提供发布提交的 `PLUGIN_COMMIT_SHA`；上面的 `RELEASE_SHA`
|
|
应从受信任的发布记录中复制，并与 `PLUGIN_REF` 对应。脚本默认使用
|
|
`v1.1.1` tag，但 tag 本身不作为完整性证明。可变分支和未 pin 的 tag
|
|
仅能在开发环境分别显式开启 `PLUGIN_ALLOW_MUTABLE_REF=true` 或
|
|
`PLUGIN_ALLOW_UNPINNED_TAG=true`。
|
|
|
|
控制面回滚（保留旧 revision）：
|
|
|
|
在插件详情的“版本”页选择目标 revision 执行回滚。等价 API 请求为：
|
|
|
|
```text
|
|
POST /api/plugins/{plugin_id}/rollback
|
|
X-CSRF-Token: <plugin csrf token>
|
|
Idempotency-Key: <unique key>
|
|
{"revision":"<retained revision id>"}
|
|
```
|
|
|
|
回滚会先健康检查目标 revision，成功后切换活动版本并更新菜单；失败时保留
|
|
当前活动版本。external 插件回滚前仍须确保其 `service_url` 对应服务已运行。
|
|
|
|
默认卸载并保留配置/数据：
|
|
|
|
```sh
|
|
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`](deploy/README.md)。
|