release: harden plugin deployment and recovery

README.md

@@ -7,7 +7,7 @@ HTTP API、管理员鉴权和 `custom_menu_items` 接入 Core；插件不导入
 
 ## 目录
 
-- `plugins/plugin-admin`：通用插件管理控制面，负责清单、签名、插件市场、
+- `plugins/plugin-admin`：通用插件管理控制面，负责清单、业务包签名校验、插件市场、
   下载入库、启用、停用、升级、回滚、删除、配置、健康检查、审计和菜单注入。
 - `plugins/subscription-admin`：可选的订阅管理业务模块后端。它不是插件管理
   控制面；只有安装并启用后才会挂载到 Plugin Admin 的统一导航中。
@@ -19,8 +19,10 @@ TypeScript/Vite 构建，并把本地打包的 TDesign、线性图标和 ECharts
 Go 服务；官方 Core 的 `frontend/` 不参与构建。
 
 控制面和业务模块后端可以独立构建和发布，但浏览器端只有一个 Plugin Admin
-登录入口。生产环境应使用独立的
-低权限服务账号、HTTPS 反向代理、签名包和稳定的 Core API 兼容基线。
+登录入口。生产环境应使用独立的低权限服务账号、HTTPS 反向代理和稳定的
+Core API 兼容基线。业务 `.s2plugin` 归档必须使用受信发布者签名；Plugin
+Admin 本身是独立的控制面服务，使用 immutable commit checkout 后本地编译，
+不通过 `.s2plugin` 发布。
 
 ## 推荐部署顺序
 
@@ -44,7 +46,7 @@ Core 仓库，也不要让插件连接 Core PostgreSQL/Redis。
 (cd plugins/subscription-admin && go run ./tools/manifestcheck)
 ```
 
-生成订阅插件包：
+生成订阅业务插件包（Plugin Admin 本身不生成 `.s2plugin`）：
 
 ```sh
 (cd plugins/subscription-admin && ./package.sh)
@@ -57,7 +59,10 @@ Core 仓库，也不要让插件连接 Core PostgreSQL/Redis。
 1. 启动 `plugin-admin` 和需要的业务模块后端，各自监听独立端口。
 2. 使用 Core 管理员账号登录 Plugin Admin 一次；普通账号被拒绝，业务模块不再单独登录。
 3. 在 `plugin-admin` 上传或从插件市场下载并校验业务插件包；包只进入“已入库，待启用”状态。
-4. 配置 loopback `service_url`，点击启用并完成健康检查后，插件才会启动。
+4. 对托管 command 插件，点击启用后由控制面启动进程并完成健康检查；对
+   `subscription-admin` 这类 external 插件，必须先由部署者或 systemd 启动
+   后端，再配置 loopback `service_url`，启用只负责探测和挂载，不会替外部服务
+   创建进程。
 5. 预览、确认并应用插件声明的管理员菜单；停用后可删除插件。
 
 订阅模块进入统一控制面后使用 `/modules/subscription/*` 路由。Plugin Admin
@@ -74,15 +79,29 @@ 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.0 PLUGIN_COMMIT_SHA="$RELEASE_SHA" bash -s -- --plugin all
+  | 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.0` tag，但 tag 本身不作为完整性证明。可变分支和未 pin 的 tag
+`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