feat: add one-command plugin deployment and removal

2026-08-27 23:48:18 +08:00
parent 5feae3ad41
commit 292dd329af
5 changed files with 362 additions and 0 deletions
@@ -0,0 +1,104 @@
+# 部署与卸载
+
+本仓库的插件是独立服务，不需要把源码复制进 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.local.yml up -d
+```
+
+官方 Core 默认通过 `http://服务器IP:8080` 提供页面。确认 Core 登录和
+数据库初始化完成后，再安装下面的独立插件。插件不会修改 Core 数据库迁移。
+
+## 一键安装
+
+在一台已安装 Go 1.23+、Git 和 systemd 的 Linux 主机上：
+
+```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/install.sh \
+  | sudo bash -s -- --plugin plugin-admin
+```
+
+安装订阅插件：
+
+```sh
+curl -fsSL https://git.awaioi.com/awaioi/sub2api-add/raw/branch/main/deploy/install.sh \
+  | sudo 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` 和受信发布者公钥。
+
+## 菜单接入
+
+1. 让反向代理把 `plugin-admin` 和业务插件分别转发到 `127.0.0.1:8090`
+   与 `127.0.0.1:8091`。
+2. 登录 plugin-admin，上传业务插件包并完成签名/哈希/兼容性校验。
+3. 配置业务插件的 loopback `service_url`。
+4. 启用、健康检查、菜单预览，然后应用菜单。
+
+订阅插件是可选项；未安装或未应用菜单时，Core 管理员菜单不会出现“订阅管理”。
+
+## 一键卸载
+
+默认卸载服务和二进制，但保留配置与插件数据，便于重新安装：
+
+```sh
+curl -fsSL https://git.awaioi.com/awaioi/sub2api-add/raw/branch/main/deploy/uninstall.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
+```
+
+卸载脚本不会删除 PostgreSQL、Redis、Sub2API Core 数据或 Core 配置。若只删除
+订阅插件，使用 `--plugin subscription-admin`；控制面和其他插件保持不变。
+
+## 本地安装与升级
+
+从已克隆的仓库执行：
+
+```sh
+sudo ./scripts/install-local.sh --plugin all
+sudo ./deploy/uninstall.sh --plugin subscription-admin
+```
+
+再次运行安装脚本会重新构建并重启选定插件。安装脚本发现源码有未提交修改
+时会中止，避免升级覆盖本地改动。
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+REPO_URL=${PLUGIN_REPO_URL:-https://git.awaioi.com/awaioi/sub2api-add.git}
+SOURCE_DIR=${PLUGIN_SOURCE_DIR:-/opt/sub2api-add}
+REF=${PLUGIN_REF:-main}
+
+die() { printf '错误：%s\n' "$*" >&2; exit 1; }
+[[ $EUID -eq 0 ]] || die "请使用 root 或 sudo 运行"
+command -v git >/dev/null 2>&1 || die "缺少 git"
+
+if [[ -e "$SOURCE_DIR" && ! -d "$SOURCE_DIR/.git" ]]; then
+  die "$SOURCE_DIR 已存在但不是本插件仓库；请设置 PLUGIN_SOURCE_DIR"
+fi
+
+if [[ -d "$SOURCE_DIR/.git" ]]; then
+  if [[ -n "$(git -C "$SOURCE_DIR" status --porcelain)" ]]; then
+    die "$SOURCE_DIR 有未提交修改，先清理后再升级"
+  fi
+  git -C "$SOURCE_DIR" fetch --depth 1 origin "$REF"
+  git -C "$SOURCE_DIR" checkout --force FETCH_HEAD
+else
+  git clone --depth 1 --branch "$REF" "$REPO_URL" "$SOURCE_DIR"
+fi
+
+exec "$SOURCE_DIR/scripts/install-local.sh" "$@"
@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+ETC_DIR=${PLUGIN_ETC_DIR:-/etc/sub2api-add}
+VAR_DIR=${PLUGIN_VAR_DIR:-/var/lib/sub2api-add}
+PREFIX=${PLUGIN_INSTALL_PREFIX:-/opt/sub2api-add}
+SOURCE_DIR=${PLUGIN_SOURCE_DIR:-/opt/sub2api-add}
+RUN_USER=${PLUGIN_SYSTEM_USER:-sub2api-plugin}
+SELECTION=all
+PURGE=false
+YES=false
+
+die() { printf '错误：%s\n' "$*" >&2; exit 1; }
+[[ $EUID -eq 0 ]] || die "请使用 root 或 sudo 运行"
+
+while (($#)); do
+  case "$1" in
+    --plugin) (($# >= 2)) || die "--plugin 需要参数"; SELECTION=$2; shift 2 ;;
+    --purge) PURGE=true; shift ;;
+    --yes) YES=true; shift ;;
+    -h|--help) printf '%s\n' '用法：deploy/uninstall.sh [--plugin all|plugin-admin|subscription-admin] [--purge --yes]'; exit 0 ;;
+    *) die "未知参数：$1" ;;
+  esac
+done
+
+case "$SELECTION" in
+  all) PLUGINS=(plugin-admin subscription-admin) ;;
+  plugin-admin|subscription-admin) PLUGINS=("$SELECTION") ;;
+  *) die "插件必须是 all、plugin-admin 或 subscription-admin" ;;
+esac
+
+if $PURGE && ! $YES; then
+  [[ -t 0 ]] || die "非交互环境执行 --purge 时必须同时提供 --yes"
+  read -r -p "将删除插件配置和数据，继续？[y/N] " answer
+  [[ "$answer" == [yY] ]] || { printf '%s\n' '已取消'; exit 0; }
+fi
+
+for plugin in "${PLUGINS[@]}"; do
+  unit="sub2api-$plugin.service"
+  systemctl disable --now "$unit" 2>/dev/null || true
+  rm -f "/etc/systemd/system/$unit"
+  rm -rf "$PREFIX/$plugin"
+  if $PURGE; then
+    rm -f "$ETC_DIR/$plugin.env"
+    rm -rf "$VAR_DIR/$plugin"
+  fi
+done
+
+systemctl daemon-reload
+if $PURGE && [[ -d "$ETC_DIR" ]]; then rmdir "$ETC_DIR" 2>/dev/null || true; fi
+if $PURGE && [[ -d "$VAR_DIR" ]]; then rmdir "$VAR_DIR" 2>/dev/null || true; fi
+if $PURGE && [[ -d "$SOURCE_DIR" ]]; then rm -rf "$SOURCE_DIR"; fi
+
+if $PURGE; then
+  userdel "$RUN_USER" 2>/dev/null || true
+  printf '%s\n' '插件、配置、数据和源码已删除；Core 数据库未被触碰。'
+else
+  printf '%s\n' "插件服务已卸载；配置和数据仍保留在 $ETC_DIR 与 $VAR_DIR。"
+fi