fix(ota): OTA_MIN_BINARY 提到 0.2.1 —— 旧外壳 CSP 不含新域名, 拉新前端会白屏; 补充遗留清单与外壳升级策略

2026-10-27 07:52:25 +08:00
parent 702c8daf6c
commit 04bc48b6a7
2 changed files with 206 additions and 121 deletions
@@ -31,11 +31,11 @@ jobs:
      # 其他 VITE_API_BASE 值。否则 OTA 包里的前端可能连错后端, 导致
      # "OTA 更新后登录失败/进不去内部"。与 android-build.yml 保持一致。
      VITE_API_BASE: https://iboard.honor3.com
-      # OTA bundle 要求的最低原生二进制版本。
-      # 与 package.json 的应用版本是**两个概念**: 前端 OTA 不碰原生层,
-      # 现有 APK 仍是 0.1.0, 所以这里固定 0.1.0 (否则旧 APK 会被判定为不兼容而收不到更新)。
-      # 重打 APK 并确认原生层无破坏后, 再提升此值。
-      OTA_MIN_BINARY: '0.1.0'
+      # OTA bundle 要求的最低原生二进制版本 (hotswap 据此拒绝不兼容的旧外壳)。
+      # 0.2.1 起必须为 0.2.1: 旧外壳 (0.1.0) 的 CSP 白名单编译进了原生二进制,
+      # 不含 https://iboard.honor3.com, 若让它拉到 0.2.1 前端会因 CSP 拦截而白屏。
+      # 旧外壳请整包升级 (Windows 重装 exe / Android 换装 APK), 不要靠 OTA。
+      OTA_MIN_BINARY: '0.2.1'
    steps:
      - uses: https://gitea.com/actions/checkout@v4

@@ -279,12 +279,97 @@ CI 未配 PG secrets → 只构建不部署；生产已由步骤 B~E 手工就
 | --- | --- |
 | 新栈起不来 | 旧容器未停，现网不受影响，回步骤 B 排查 |
 | 迁移数据不对 | 清空 `deploy/prod/data/pg` 后重跑 ETL |
-| 切换后严重故障 | 用 `iboard:mysql-final` 旧镜像按原 MySQL 参数恢复 3001 |
+| 切换后严重故障 | **`docker start iboard`**（旧容器仍在，见 6.2 警告：旧镜像已被 prune，不能重建） |

-## 六、已知遗留
+## 六、遗留清单与清理建议（2026-10-27 实测）
+
+### 6.1 本机（Windows）
+
+| 路径 | 占用 | 建议 | 说明 |
+| --- | --- | --- | --- |
+| `workbetch/iboard`（主 worktree） | 3.81 GB | **保留** | 含 `node_modules` 0.49 GB + `src-tauri/target` 2.56 GB |
+| `workbetch/iboard-dev-0.2.1` | 0.53 GB | **可删** | 内容已全部并入 `dev-0.2` |
+| `workbetch/iboard-dev-windows` | 8.88 GB | **可删** | 同上，最大占用（含 Rust 编译产物） |
+| `iboard/src-tauri/target` | 2.56 GB | 可选 `cargo clean` | 删后下次打包需重编译（约 8 分钟） |
+| `iboard/artifacts/windows` | 32 MB | 保留最新安装包 | 0.2.1 exe/zip |
+| `%TEMP%\node-portable` | 78 MB | **保留** | 本机无系统 Node/npm，`npm run build:win` 依赖它 |
+| `%TEMP%\esbuild-*`（4 个） | 8 MB | 可删 | 构建残留 |
+| `%TEMP%\iboard-e2e`、`iboard-shell-offline` | < 1 MB | 可删 | 验证截图 |
+| `%TEMP%\edge-e2e-profile` | ~100 MB | 可删 | 无头浏览器测试配置 |
+
+```bash
+# 删除 worktree 与已合并分支（内容已在 dev-0.2）
+git worktree remove ../iboard-dev-0.2.1
+git worktree remove ../iboard-dev-windows
+git branch -d dev-0.2.1 dev-windows-0.1
+git branch -D tmp-offline-edit
+```
+
+### 6.2 服务器 baihu
+
+| 路径/对象 | 占用 | 建议 | 说明 |
+| --- | --- | --- | --- |
+| `/app/iboard-prod` | 72 MB | **保留** | 当前生产 |
+| `/app/iboard` | 24 KB | 暂留 → 可删 | 旧生产只剩 `cache/`（`auth.txt` 已复制到新栈）+ `start.sh` |
+| `/app/iboard-0.2.1` | 71 MB | **可删** | 验证栈已 down；其中 `deploy/0.2.1/data` 67 MB 是废弃 PG 数据 |
+| `/app/cicd` | 36 KB | **保留** | act_runner 配置 |
+| 容器 `iboard`（Exited） | — | **暂留** | 当前唯一回滚手段（见下方警告） |
+| 镜像 `iboard-021-app:latest` | 924 MB | **可删** | 验证栈镜像 |
+| 镜像 `iboard:latest` | 934 MB | 保留 | CI 构建产物 |
+| 悬空镜像 + 构建缓存 | 18.7 GB + 2.4 GB | 可清 | `docker image prune -f && docker builder prune -af` |
+
+> **⚠ 回滚能力警告（实测更正）**
+> 原计划保留的 `iboard:mysql-final` 旧镜像**已被 `docker image prune` 清除** —— 旧镜像失去 tag 后成为悬空镜像被回收。
+> 现在唯一回滚途径是重启仍存在的旧容器 `iboard`（镜像层随容器保留）：
+>
+> ```bash
+> docker stop iboard-prod-app-1
+> docker start iboard          # 旧 MySQL 版立即恢复 3001
+> ```
+>
+> **在再次执行 `docker image prune` 前，务必先确认旧容器仍在**；容器一旦删除，MySQL 版镜像只能从 git 历史重新构建。
+
+### 6.3 代码与其他
+
+- 临时测试脚本（`scripts/_prod-e2e.mjs`、`_browser-test.mjs`、`_shell-offline-test.mjs`）含真实口令，已加入 `.gitignore`（`scripts/_*.mjs`），**不要入库**
+- `0.2.1` 验证库里的测试任务（如 `浏览器验证任务`）已按 MySQL 现状一并迁入 PG，如需清理直接在 PG 删除
+- `prisma/migrations/` 仍是 MySQL 语法，**新环境建表必须用 `prisma db push --accept-data-loss`**（已写入 `deploy/prod/README.md`）
+- `JWT_SECRET` 仍为弱值（`iboard`），建议择机换新（换新需全员重新登录）
+- `node_modules` 在多个 Node 版本间切换过，遇 esbuild 权限报错时清空重装
+
+## 七、外壳升级策略：必须整包升级，不能只靠 OTA
+
+### 结论
+
+| 平台 | 结论 | 关键原因 |
+| --- | --- | --- |
+| Windows 外壳（0.1.0） | **必须重装 exe** | ① CSP 白名单编译进原生二进制，0.1.0 不含 `https://iboard.honor3.com`；② 旧外壳 OTA 检查地址指向 `13001`，**该端口已下线**，连检查都失败 |
+| Android（0.1.0 APK） | **必须换装 APK** | CSP 同样是原生配置；旧 APK 的 OTA 端点（3001）虽然有效，但拉到 0.2.1 前端会被 CSP 拦截 → 白屏 |
+
+### 为什么 OTA 不够
+
+`tauri-plugin-hotswap` 的 OTA 包内容只有 `bundle.tar.gz`（即 `dist/` 前端资源），**不触碰原生层**：
+
+| 配置项 | 位置 | OTA 能否修改 |
+| --- | --- | --- |
+| CSP 白名单（`connect-src`） | `tauri.conf.json` → 编译期 `generate_context!` 注入二进制 | ❌ |
+| OTA 检查 endpoint | 同上 | ❌ |
+| 窗口尺寸/最小尺寸 | 同上（另可被 `shell-config.json` 覆盖） | ❌ |
+| 托盘 / 悬浮球 / 自启动 | Rust `src-tauri/src/shell/*` | ❌ |
+| 页面 JS/CSS/WASM（含离线编辑、徽标、编号展示） | `dist/` | ✅ |
+
+因此旧外壳无法通过 OTA 获得访问新域名的能力。
+
+### 已采取的保护措施
+
+CI 的 `OTA_MIN_BINARY` 已从 `0.1.0` 提升到 **`0.2.1`**：
+
+- 旧外壳（0.1.0 < 0.2.1）会被 hotswap 判定为不兼容 → **拒绝接收新前端**
+- 旧外壳继续运行旧前端，仍访问 `http://bh.vps.honor3.com:3001`（该地址现指向新栈，`/api` 完全兼容）
+- 结果：**旧外壳不会白屏**，只是缺少离线编辑、项目编号等 0.2.1 新能力
+
+### 升级后
+
+- 新外壳版本 0.2.1，CSP 含 `https://iboard.honor3.com`，OTA 恢复正常（后续纯前端改动可继续走 OTA）
+- Windows 窗口尺寸通过 `%APPDATA%\com.iboard.app\shell-config.json` 的 `window_width` 单值配置

- `dev-0.2.1` / `dev-windows-0.1` 两个 worktree 分支内容已全部并入 `dev-0.2`，可择机删除。
- `tmp-offline-edit` 分支 = `1cd5b85`，历史遗留，可删。
- 临时测试脚本 `scripts/_browser-test.mjs`、`scripts/_shell-offline-test.mjs` 含真实口令，**不要入库**。
- 0.2.1 验证库里可能残留测试任务（`浏览器验证任务` / `IBOARD-8`），迁移后建议清理。
- `node_modules` 曾在多种 Node 版本间切换，如遇 esbuild 权限报错，清 `node_modules` 重装即可。