144 lines
5.8 KiB
Markdown
144 lines
5.8 KiB
Markdown
# 部署与卸载
|
||
|
||
本仓库的插件是独立服务，不需要把源码复制进 Sub2API Core。安装脚本会构建
|
||
插件二进制、创建低权限 systemd 服务、生成插件配置，并让服务监听各自的
|
||
端口。Core 数据库、Redis 和 Core `data/` 目录始终由 Core 自己管理。
|
||
|
||
## 先部署官方 Core
|
||
|
||
建议先使用官方仓库的全新部署脚本，单独放在自己的目录：
|
||
|
||
```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 默认通过 `http://服务器IP:8080` 提供页面。确认 Core 登录和
|
||
数据库初始化完成后，再安装下面的独立插件。插件不会修改 Core 数据库迁移。
|
||
|
||
## 一键安装
|
||
|
||
在一台已安装 Go 1.23+、Git 和 systemd 的 Linux 主机上：
|
||
|
||
```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`。tag 只是选择版本，不是完整性证明。开发环境如需使用
|
||
可变分支或未 pin 的 tag，必须显式设置对应的开发开关。
|
||
|
||
```sh
|
||
export PLUGIN_ENV=development PLUGIN_REF=main PLUGIN_ALLOW_MUTABLE_REF=true
|
||
curl -fsSL https://git.awaioi.com/awaioi/sub2api-add/raw/branch/main/deploy/install.sh \
|
||
| sudo -E bash -s -- --plugin all
|
||
```
|
||
|
||
只安装控制面：
|
||
|
||
```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 plugin-admin
|
||
```
|
||
|
||
安装订阅插件：
|
||
|
||
```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 subscription-admin
|
||
```
|
||
|
||
默认安装位置：
|
||
|
||
| 内容 | 路径 |
|
||
| --- | --- |
|
||
| 源码 | `/opt/sub2api-add` |
|
||
| 二进制 | `/opt/sub2api-add/<plugin>/bin/` |
|
||
| 配置 | `/etc/sub2api-add/<plugin>.env` |
|
||
| 插件数据 | `/var/lib/sub2api-add/<plugin>/` |
|
||
| systemd | `sub2api-plugin-admin.service`、`sub2api-subscription-admin.service` |
|
||
|
||
安装后先编辑配置：
|
||
|
||
```sh
|
||
sudoedit /etc/sub2api-add/plugin-admin.env
|
||
sudoedit /etc/sub2api-add/subscription-admin.env
|
||
sudo systemctl restart sub2api-plugin-admin sub2api-subscription-admin
|
||
```
|
||
|
||
至少确认 `CORE_BASE_URL`、插件端口、反向代理路径和 HTTPS Cookie 设置。生产
|
||
环境应启用 `PLUGIN_COOKIE_SECURE=true`，并为 plugin-admin 配置稳定的
|
||
`PLUGIN_CONFIG_KEY` 和受信发布者公钥。插件市场默认读取
|
||
`/var/lib/sub2api-add/plugin-admin/marketplace/index.json`；可通过
|
||
`PLUGIN_MARKETPLACE_INDEX` 指向受控本地索引或 HTTPS 索引，并用
|
||
`PLUGIN_MARKETPLACE_ALLOWED_HOSTS` 限定远程索引和包的精确主机。生产远程索引
|
||
还必须设置 `PLUGIN_MARKETPLACE_INDEX_SHA256`，把目录内容固定到已审核的摘要。
|
||
|
||
## 菜单接入
|
||
|
||
1. 让反向代理把 `plugin-admin` 和业务插件分别转发到 `127.0.0.1:8090`
|
||
与 `127.0.0.1:8091`。
|
||
2. 登录 plugin-admin，上传业务插件包，或在插件市场选择目录版本。
|
||
3. 控制面完成签名、哈希和 Core 兼容性校验后，仅将包登记为“已入库，待启用”，不会启动进程。
|
||
4. 对 external 业务插件，先由部署者启动对应后端，再配置 loopback `service_url`；
|
||
对 command 插件，点击启用时控制面才会启动进程。两种模式都必须通过健康和
|
||
就绪检查后才算安装完成。
|
||
5. 预览、确认并应用插件声明的管理员菜单。
|
||
|
||
订阅插件是可选项；未安装或未应用菜单时，Core 管理员菜单不会出现“订阅管理”。
|
||
|
||
## 版本回滚
|
||
|
||
Plugin Admin 会在升级时保留旧 revision。生产回滚建议在插件详情的“版本”页
|
||
选择目标 revision；也可以调用下面的受保护 API（需要 Plugin Admin 会话的
|
||
CSRF token 和唯一 `Idempotency-Key`）：
|
||
|
||
```text
|
||
POST /api/plugins/{plugin_id}/rollback
|
||
{"revision":"<retained revision id>"}
|
||
```
|
||
|
||
控制面会先启动并探测目标 revision，健康后再停止当前版本并原子切换注册表。
|
||
探测失败不会替换当前活动版本。external 插件回滚前必须先确保目标版本的
|
||
独立服务已经监听 `service_url`；command 插件由控制面负责启动和停止。
|
||
|
||
## 一键卸载
|
||
|
||
默认卸载服务和二进制，但保留配置与插件数据，便于重新安装：
|
||
|
||
```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
|
||
```
|
||
|
||
确认同时删除插件配置、插件数据和源码：
|
||
|
||
```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
|
||
```
|
||
|
||
卸载脚本不会删除 PostgreSQL、Redis、Sub2API Core 数据或 Core 配置。若只删除
|
||
订阅插件，使用 `--plugin subscription-admin`；控制面和其他插件保持不变。
|
||
|
||
## 本地安装与升级
|
||
|
||
从已克隆的仓库执行：
|
||
|
||
```sh
|
||
sudo ./scripts/install-local.sh --plugin all
|
||
sudo ./deploy/uninstall.sh --plugin subscription-admin
|
||
```
|
||
|
||
再次运行安装脚本会重新构建并重启选定插件。安装脚本发现源码有未提交修改
|
||
时会中止，避免升级覆盖本地改动。该脚本从 pinned commit 构建控制面和示例
|
||
业务后端；业务 `.s2plugin` 的生产签名由 `plugins/subscription-admin/package.sh`
|
||
和受信发布者密钥负责，Plugin Admin 不以 `.s2plugin` 归档交付。
|