# 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`：可选的订阅管理业务插件。它不是插件管理
  控制面，只有安装、启用并应用菜单后才会出现。
- `docs/`：插件框架、清单、边界、架构、开发和验收契约。

两个插件都是独立 Go module，可以分别构建和发布。生产环境应使用独立的
低权限服务账号、HTTPS 反向代理、签名包和稳定的 Core API 兼容基线。

## 推荐部署顺序

先单独部署官方 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.local.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)
```

生成订阅插件包：

```sh
(cd plugins/subscription-admin && ./package.sh)
```

构建脚本只生成本地二进制或 `dist/` 包，不将它们提交到仓库。

## 接入顺序

1. 启动 `plugin-admin` 和需要的业务插件，各自监听独立端口。
2. 使用 Core 管理员账号登录插件服务；普通账号被拒绝。
3. 在 `plugin-admin` 上传并校验业务插件包，配置 loopback `service_url`。
4. 启用插件并完成健康检查。
5. 预览、确认并应用插件声明的管理员菜单。

Core 继续作为用户、余额、订阅、计费和用量账本的权威来源。插件浏览器端
不持有 Core JWT、Admin Key 或其他服务密钥。

## 一键部署与卸载

Linux + systemd 环境可直接使用仓库内的安装脚本：

```sh
curl -fsSL https://git.awaioi.com/awaioi/sub2api-add/raw/branch/main/deploy/install.sh \
  | sudo bash -s -- --plugin all
```

默认卸载并保留配置/数据：

```sh
curl -fsSL https://git.awaioi.com/awaioi/sub2api-add/raw/branch/main/deploy/uninstall.sh \
  | sudo bash -s -- --plugin all
```

需要清除插件配置、数据和源码时，显式使用 `--purge --yes`。完整部署、反向
代理、菜单应用和升级说明见 [`deploy/README.md`](deploy/README.md)。