# 万能导发布与回滚手册

本手册适用于 1.4.0 起的 Tauri 2 主程序和 Plugin v1 官方插件正式发布。桌面安装包当前按项目策略以未签名形式发布；不要在源码、产物或日志中保存私钥、Cookie、Token、账号密码等敏感信息。

## 发布前检查

在干净工作区运行：

```powershell
rustup toolchain install 1.88.0 --profile minimal --component rustfmt,clippy
rustup target add x86_64-pc-windows-msvc --toolchain 1.88.0
python scripts/quality_check.py
python -m pip_audit -r requirements.txt
cd wandao_electron
npm ci
npm audit --json --registry=https://registry.npmjs.org
cargo +1.88.0 fmt --manifest-path src-tauri/Cargo.toml --all -- --check
cargo +1.88.0 test --manifest-path src-tauri/Cargo.toml --all-targets --locked
cargo +1.88.0 clippy --manifest-path src-tauri/Cargo.toml --all-targets --locked -- -D warnings
npm run build:win:unsigned
cd ..
```

本地构建需要 Rust 1.88.0 和 `x86_64-pc-windows-msvc` target。CI 同样固定到 1.88.0，禁止使用随时间漂移的 `stable`。质量门会校验 Plugin/Provider 契约、Python/Node/Rust 测试、静态语法和空白符；Tauri release 构建还会拒绝 runtime 解释器或 `WANDAO_RUNTIME.json` 缺失、runtime target 与 Rust target 不一致，以及打包源码中残留 `__pycache__`/`.pyc`。

`npm run build:win:unsigned` 生成仅供本地验证的 `wandao_electron/src-tauri/target/release/bundle/nsis/*.exe`。必须安装候选 NSIS 包到干净临时目录，再运行：

```powershell
python scripts/package_smoke.py --resources <安装目录>
```

macOS Apple Silicon 本地候选包使用 `npm run build:mac:arm64:unsigned`，产物位于 `wandao_electron/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/*.app`；smoke 的 `--resources` 指向该 `.app`。不要用源码目录或 Cargo 中间目录代替真实候选包验证。本地和 `workflow_dispatch` 产物都带 `UNSIGNED-SMOKE` 标识，只用于验证且不会自动创建 Release；正式 tag 使用同一未签名构建命令，但必须通过完整发布门禁。

在 GitHub 仓库设置中保护 `main`：要求 PR 和状态检查通过。桌面 Release 不依赖证书 Secret 或发布 Environment；插件发布仍使用独立的 `plugin-signing` Environment 和 Ed25519 信任链，不得因桌面端未签名而取消插件验签。

Windows 正式安装包当前没有 Authenticode 签名，系统可能显示未知发布者；macOS 正式应用没有 Developer ID 签名和 Apple 公证，Gatekeeper 可能阻止首次打开。发布页必须明确披露，不得宣称产物已签名或建议用户执行 `xattr -cr`。未来增加商业签名时应作为独立增强重新引入凭据隔离和验签门禁。

## 正式版本流程

1. 维护者审阅变更、`SECURITY.md`、版本说明、未签名风险披露和兼容性风险。
2. 从已通过 PR 质量门的 `main` 推送格式为 `vX.Y.Z` 的 tag。
3. `Build Desktop` 使用显式 `--no-sign` 命令生成 Windows NSIS 和 macOS Apple Silicon 应用。
4. CI 对 Windows 执行静默安装、旧 Electron 数据迁移和已安装资源 smoke；对 macOS 校验 arm64、最低系统版本、应用结构和打包资源。
5. CI 为发行物生成 `SHA256SUMS`、SPDX SBOM 和 build provenance。1.4.0 创建 `draft` 且 `make_latest: false`，不会直接向用户公开。
6. 从 draft 下载发行资产，在干净 Windows/macOS 系统验证安装、旧版升级、插件中心、一个导出任务与一个恢复任务。macOS 首次打开应记录 Gatekeeper 提示并使用“系统设置 → 隐私与安全性”的系统入口确认，不得执行 `xattr -cr`。维护者确认版本说明和验证证据后再手动公开并决定是否设为 latest。

## 官方插件发布

`publish-plugins.yml` 使用受保护的 `plugin-signing` 环境。插件签名私钥只应作为该环境中的短作用域 Secret 提供。发布前确认：

- `plugin.json` 权限最小化，版本与 `core.minVersion` 正确；
- Provider action 能通过 `--help`、结果协议和样例 smoke；
- registry 的 SHA-256、Ed25519 签名与包内容一致；
- 新版本在离线内置插件上安装后能正常覆盖，卸载后会回退到随应用提供的版本。

## 回滚

- **插件问题**：在插件中心使用“回滚”；如需紧急止损，将有问题版本从签名 registry 移除，随后发布更高版本的修复包。不要替换既有版本包。
- **桌面端问题**：撤回 Release、重新发布修复 tag；已安装用户可保留任务 checkpoint 和导出目录后降级。不要删除用户数据目录。
- **签名密钥疑似泄露**：立即停用对应 trust key，轮换密钥，使用新的 `keyId` 重签 registry 与插件，并在安全公告中说明受影响版本和升级路径。

## 发布后的证据

Release 页面至少应包含安装包、`SHA256SUMS`、SBOM、provenance、未签名风险说明与简明版本说明。将 CI run URL、Windows/macOS 实机安装结果和抽样迁移记录保存到维护者的私有发布记录中。