98 lines
4.8 KiB
Markdown
98 lines
4.8 KiB
Markdown
# Sub2API Subscription Admin Business Plugin V1
|
||
|
||
这是一个独立运行的管理员只读业务插件，不是现有 `.s2plugin` transport 插件，也不是插件管理后台。它不导入 Sub2API `internal` 包，不连接 Core 数据库，也不修改 Core Go/Vue、迁移、路由或 `.s2plugin` ABI。
|
||
|
||
生产/集成环境由通用 `plugins/plugin-admin` 控制面安装、启用和升级本插件；本插件不会预装，也不会成为控制面首页。只有健康检查通过并由管理员执行菜单预览/应用后，Core 管理员菜单才会出现“订阅管理”入口。直接运行本目录仅用于本地开发和契约测试。
|
||
|
||
## 本地启动
|
||
|
||
```sh
|
||
CORE_BASE_URL=http://127.0.0.1:8080 \
|
||
PLUGIN_HOST=127.0.0.1 \
|
||
PLUGIN_PORT=8091 \
|
||
go run .
|
||
```
|
||
|
||
打开 `http://127.0.0.1:8091/admin/`。生产环境应通过 HTTPS 反向代理，并设置 `PLUGIN_COOKIE_SECURE=true`。挂载到子路径时同时设置 `PLUGIN_PUBLIC_BASE_PATH` 和 `PLUGIN_COOKIE_PATH`，例如 `/extensions/qiu.subscription-admin`。
|
||
|
||
## V1 范围
|
||
|
||
- Core 管理员账号登录和 Core 2FA；普通账号统一拒绝。
|
||
- 插件 HttpOnly、SameSite 会话和写请求 CSRF 校验。
|
||
- Core token 只保存在插件服务端内存会话中，不进入浏览器、URL、HTML、LocalStorage、响应或日志。
|
||
- 只读套餐、订阅列表、订阅详情和插件操作记录。
|
||
- Core access token 失效时最多刷新一次；刷新失败会销毁插件会话。
|
||
- 页面刷新会从插件会话恢复，并重新取得短期 CSRF token；服务端不会把 Core token 返回浏览器。
|
||
- 登录会读取 Core 公开验证码配置并透传 Turnstile、腾讯、阿里云或 GeeTest 的验证结果；验证码本身仍由 Core 校验。
|
||
- 余额购买、续费、撤销、退款和外部支付不在 V1，页面不渲染提交按钮。
|
||
|
||
## Core API allowlist
|
||
|
||
插件服务端仅调用这些明确路径：
|
||
|
||
```text
|
||
POST /api/v1/auth/login
|
||
POST /api/v1/auth/login/2fa
|
||
POST /api/v1/auth/refresh
|
||
POST /api/v1/auth/logout
|
||
GET /api/v1/auth/me
|
||
GET /api/v1/settings/public
|
||
GET /api/v1/admin/payment/plans
|
||
GET /api/v1/admin/subscriptions
|
||
GET /api/v1/admin/subscriptions/{id}
|
||
GET /api/v1/admin/users/{id}
|
||
GET /api/v1/admin/users/{id}/subscriptions
|
||
```
|
||
|
||
列表请求只接受 `page`、`page_size`、`limit`、`user_id`、`group_id`、`status`、`platform`、`sort_by`、`sort_order` 参数。插件不会代理任意 URL，也不会调用尚不存在的 `/api/v1/plugin-host/*`。
|
||
|
||
## Core 菜单与反向代理
|
||
|
||
控制面会依据清单中的菜单声明生成下面的 `custom_menu_items` 项；部署时无需手工写入订阅菜单：
|
||
|
||
```json
|
||
{
|
||
"id": "qiu.subscription-admin",
|
||
"label": "订阅管理",
|
||
"url": "https://CORE_ORIGIN/extensions/qiu.subscription-admin/",
|
||
"visibility": "admin",
|
||
"sort_order": 200
|
||
}
|
||
```
|
||
|
||
Core 自定义页面的 sandbox iframe 不会继承 Core `localStorage` 登录态，因此 V1 首屏显示插件登录页是预期行为；同时提供新窗口入口。不要把 JWT 放进 URL。
|
||
|
||
## 测试
|
||
|
||
```sh
|
||
go test ./... -count=1
|
||
node --check ui/app.js
|
||
```
|
||
|
||
`main_test.go` 覆盖 Core 路径 allowlist、查询参数过滤、管理员角色拒绝、插件 Cookie、Core token 不泄露、会话过期、请求 ID、登录限流和 2FA pending 一次性消费。浏览器验收脚本位于 `test/browser-check.mjs`，可使用本地 Mock Core 验证直连、子路径反代和三种视口。
|
||
|
||
## 生成可安装包
|
||
|
||
```sh
|
||
./package.sh
|
||
```
|
||
|
||
脚本生成 `dist/qiu.subscription-admin.s2plugin`，包内根文件名为
|
||
`manifest.json`，并包含清单声明哈希的 UI 文件。该插件采用外部服务模式：
|
||
安装后先独立启动 `subscription-admin`，再在 `plugin-admin` 的配置中填写
|
||
`service_url`（插件 loopback 地址）和 `public_url`（反向代理地址），然后执行
|
||
启用、健康检查和菜单应用。生产环境必须把签名文件通过
|
||
`SIGNATURE_FILE=/path/to/signature.json ./package.sh` 放入包内，并将对应公钥
|
||
加入控制面受信发布者配置；未签名包仅限 development + loopback。
|
||
|
||
## 清单和发布
|
||
|
||
`business-plugin-manifest.v1.json` 是部署层清单，不由 Core 读取。生产发布应由独立 CI 签名并校验清单、版本、健康路径和兼容的 Core 版本；不要把发布私钥放入仓库或插件包。插件版本独立于 `backend/cmd/server/VERSION`。
|
||
|
||
## 已知限制
|
||
|
||
- V1 使用内存会话，服务重启会要求重新登录；多实例部署需将会话存储替换为插件自有 Redis/共享会话服务。
|
||
- 现有 Core 自定义 iframe 没有 token handoff，V1 不提供无感 SSO；真正 SSO 需要单独的 V1.1 Core 交接接口。
|
||
- Core 当前套餐响应中的 `features` 可能是 JSON 字符串，UI 会兼容字符串和数组。
|
||
- Core 开启验证码时，管理员必须先完成对应提供商的挑战并将结果填入登录表单；插件不保存验证码票据。
|