release: harden plugin deployment and recovery

deploy/README.md

@@ -24,7 +24,7 @@ docker compose -f docker-compose.yml up -d
 ```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`，并从受信任的发布记录复制
@@ -42,7 +42,7 @@ curl -fsSL https://git.awaioi.com/awaioi/sub2api-add/raw/branch/main/deploy/inst
 ```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 plugin-admin
+  | sudo env PLUGIN_REF=v1.1.1 PLUGIN_COMMIT_SHA="$RELEASE_SHA" bash -s -- --plugin plugin-admin
 ```
 
 安装订阅插件：
@@ -50,7 +50,7 @@ curl -fsSL "https://git.awaioi.com/awaioi/sub2api-add/raw/commit/${RELEASE_SHA}/
 ```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 subscription-admin
+  | sudo env PLUGIN_REF=v1.1.1 PLUGIN_COMMIT_SHA="$RELEASE_SHA" bash -s -- --plugin subscription-admin
 ```
 
 默认安装位置：
@@ -85,11 +85,28 @@ sudo systemctl restart sub2api-plugin-admin sub2api-subscription-admin
    与 `127.0.0.1:8091`。
 2. 登录 plugin-admin，上传业务插件包，或在插件市场选择目录版本。
 3. 控制面完成签名、哈希和 Core 兼容性校验后，仅将包登记为“已入库，待启用”，不会启动进程。
-4. 配置业务插件的 loopback `service_url`，再点击启用；健康检查通过后才算安装完成。
+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 插件由控制面负责启动和停止。
+
 ## 一键卸载
 
 默认卸载服务和二进制，但保留配置与插件数据，便于重新安装：
@@ -121,4 +138,6 @@ sudo ./deploy/uninstall.sh --plugin subscription-admin
 ```
 
 再次运行安装脚本会重新构建并重启选定插件。安装脚本发现源码有未提交修改
-时会中止，避免升级覆盖本地改动。
+时会中止，避免升级覆盖本地改动。该脚本从 pinned commit 构建控制面和示例
+业务后端；业务 `.s2plugin` 的生产签名由 `plugins/subscription-admin/package.sh`
+和受信发布者密钥负责，Plugin Admin 不以 `.s2plugin` 归档交付。