iboard/docs/021任务.md

# 0.2.1 发布任务 — 目标与现状

> 最后更新：2026-10-27 08:20
> 分支：`dev-0.2` 与 `master` 均已发布（`a1c267b`）
> 状态：**全部完成** —— 生产已切 0.2.1 单端口架构，master 发布 CI 通过，Android APK 与 Windows 安装包均已产出

## 零、执行结果速览（2026-10-27 已完成）

| 项目 | 结果 |
| --- | --- |
| 生产地址 | `https://iboard.honor3.com` → baihu **3001**（NPM + 有效证书） |
| 生产架构 | `iboard-prod-app-1`(3001 对外) + `iboard-prod-pg-1`(内网) + `iboard-prod-powersync-1`(内网) |
| 端口 | **只剩 3001**；13001 / 13002 / 13443 全部下线 |
| 数据迁移 | MySQL → PG 完成：Project 3、Task 25、BoardColumn 12、User 1、CheckIn 17、News 19、IndicatorPoint 245、Mihome 等全部迁入 |
| 旧生产 | 容器 `iboard` 已 **stop（未删除）**，`docker start iboard` 可秒级回滚 |
| 登录态 | `JWT_SECRET` 沿用 `iboard`，现有用户无需重新登录 |
| 米家凭证 | `/app/iboard/cache` → `deploy/prod/data/cache`（`auth.txt` + `apizero/`） |
| E2E 验证 | 在线：项目卡片 + `ADMIN-16`/`ADMIN-18` 编号；断网：徽标出现、任务页数据完整、无 fail fetch；恢复：徽标消失 |
| master 发布 | 已推 `master`（`a1c267b`）；CI `build-image` **10/10 步成功**（版本校验 / 前端 / OTA 签名包 / 镜像 / 部署步按设计跳过） |
| Android | `android-1.0` CI **16/16 步成功**，APK 20MB（versionName 0.2.1）已发布到 Gitea packages |
| Windows | 本地 `npm run build:win` 成功：NSIS 6.9MB + 便携 zip 7.9MB |
| OTA 热更 | **已打通**：`https://iboard.honor3.com/api/ota/check/0` 返回 `0.2.1-ota`、`min_binary_version: 0.2.1`、签名与下载地址齐全 |

### 迁移过程中踩到并修掉的坑

1. `prisma/migrations/` 是 **MySQL 语法**（反引号），PG 无法 `migrate deploy` → 改用 `prisma db push --accept-data-loss` 按 schema 建表。
2. `db push` 首次因参数不被识别而输出帮助（表结构停在旧 schema，缺 `autoArchive`）→ 去掉错误参数重跑，列已补齐。
3. 新库缺 **uuid 镜像触发器**（`projectUuid`/`columnUuid`/`parentUuid`/`taskUuid`）→ 从 0.2.1 验证库导出 5 个函数 + 5 个触发器，落库并入库 `deploy/prod/sql/uuid-triggers.sql`。
4. bash 把 `$$` 展开成 PID 导致 TRUNCATE 脚本报错 → 改用 SQL 文件传入。
5. baihu 上 `docker build` 缺 buildx → 改用 `docker compose build`。
6. **OTA 包此前完全没有**：手工构建的镜像内 `/app/ota-package` 只有 README（`ota-package/` 被 `.gitignore` 排除，CI 部署段又跳过），线上 OTA 接口返回空 → 已给 app 容器加 `data/ota` 挂载，并新增 CI 步骤用 `docker cp` 经 bind-mount 容器写入宿主（CI 在容器内无法直接写宿主文件）。
7. CI 首次写入路径多写了一层 `data/ota`（与 compose 的 `deploy/prod/data/ota` 不一致）→ 路径已对齐。
8. `OTA_MIN_BINARY` 由 `0.1.0` 提升到 **`0.2.1`**，防止旧外壳拉到新域名前端后被 CSP 拦截白屏。

---

## 一、任务目标（用户原始要求）

1. 域名 `iboard.honor3.com` 已指向 3000 端口、HTTPS 证书已配好 → 客户端全面切到该域名。
2. **Windows 外壳 + 离线编辑功能正式合并到 `dev-0.2`**，完整版本号 **0.2.1**。
3. 确保 **Android** 功能正常（通过 CI 编译验证，不在本地装 Android 工具链）。
4. 确保 **CI/CD** 正常。
5. Windows **本地打包正常**即可。
6. `dev-0.2` 更新完成后 **通过 `master` 分支发布**。
7. 追加要求：**不要再有 13002 这类独立端口**，所有版本合并成一套。

---

## 二、已完成

### 2.1 分支合并

| 内容 | 结果 |
| --- | --- |
| `dev-0.2.1`（离线编辑 + 项目编号 + PG/PowerSync）→ `dev-0.2` | 已合并 `e689e44` |
| `dev-windows-0.1`（Windows 外壳：托盘/悬浮球/吸附/自启动）→ `dev-0.2` | 已按路径迁入 `eef2969` |
| `dev-0.2` → `android-1.0`（触发 APK 构建） | 已合并 `4958359` |
| 冲突处理 | `projects.js`/`tasks.js`/`api/task.js` 手工合并，**两边功能都保留**（`autoArchive` 归档 + `code` 编号） |
| 归档功能补齐到本地库 | `src/api/task.js` 新增 `archive`/`unarchive`/`archivedList`；`schema.js` 加 `archived/archivedAt/archiveSource/autoArchive`；`sync-config.yaml` 与 upload 处理器同步 |
| Prisma 客户端补齐 | dev-0.2 原来缺任务模块 6 个模型，已重新 generate `fc23919` |

### 2.2 版本与域名

- 版本统一 **0.2.1**：`package.json` / `src-tauri/tauri.conf.json` / `Cargo.toml` / `Cargo.lock`（`scripts/ci/check-version.mjs` 通过）
- 域名切 `https://iboard.honor3.com`：
  - `src/api/client.js` 注释、`.env.shell`、`scripts/wsl/build-apk.sh`、`.gitea/workflows/android-build.yml`、`.gitea/workflows/docker-build.yml`、`Dockerfile`（`OTA_PUBLIC_BASE`）、`tauri.conf.json`（OTA endpoint + CSP）
- 旧域名 `bh.vps.honor3.com:3001` 仅保留在 CSP 白名单里做滚动兼容

### 2.3 单端口架构（去掉 13002）

| 改动 | 位置 |
| --- | --- |
| Express 增加 `/sync`、`/socket` 同域反代到内网 powersync | `server/powersync-proxy.js` + `server/index.js`（挂在 `express.json()` 之前，支持长连接） |
| 生产编排：app(3001 对外) + pg(内网) + powersync(内网) | `deploy/prod/docker-compose.yml` |
| 生产部署脚本（幂等：迁移 → publication → 起栈 → 健康检查） | `scripts/deploy/prod.sh` |
| PG 初始化（powersync_storage 用户） | `deploy/prod/initdb/01-powersync-storage.sh` |
| 逻辑复制 publication（**建表后**执行） | `deploy/prod/sql/publication.sql` |
| 部署文档 | `deploy/prod/README.md`、`.env.example` |
| CI 部署段改为调用宿主脚本，未配 PG secrets 时自动跳过 | `.gitea/workflows/docker-build.yml` |

### 2.4 Windows 本地打包 — 通过 ✅

`npm run build:win` 全流程成功（本机需 Node 20.19+；已用便携 Node 20.18.1 之外的 Node 24 验证过 vite 构建）：

| 产物 | 路径 | 大小 |
| --- | --- | --- |
| 安装包 | `artifacts/windows/iBoard_0.2.1_x64-setup.exe` | 6.9 MB |
| 便携版 zip | `artifacts/windows/iBoard_0.2.1_x64-portable.zip` | 7.9 MB |

外壳能力（继承 dev-windows-0.1）：托盘、悬浮球吸附、自动隐藏、单实例、自启动、窗口尺寸单值配置
（`%APPDATA%\com.iboard.app\shell-config.json` 的 `window_width`，高度按 405:720 锁定推导）。

离线能力（继承 0.2.1）：GET 响应本地缓存、同步凭证持久化（离线不清库）、左上角「离线」徽标。

### 2.5 Android CI — 通过 ✅

- 触发：`android-1.0` 分支 push（`4ded8e3`）
- 结果：**16 个步骤全部 success**，`Build release APK` + `Publish APK to Gitea packages` 成功
- 产物：`app-universal-release.apk`（20 MB），versionName = **0.2.1**
  已发布到 `http://git.honor3.com/api/packages/Fullstack/generic/iboard/1.0-4ded8e30/`
- 首次失败原因：runner 宿主机（baihu）磁盘 **95%** → `No space left on device`；
  清理悬空镜像 + 构建缓存后释放 11.5 GB，重跑通过。**磁盘现已 60%（39 GB 可用）**

### 2.6 CI/CD 现状

| Workflow | 触发 | 状态 |
| --- | --- | --- |
| `docker-build.yml` | `master` push | 改造完成，未在 master 上验证（部署段会因缺 secrets 跳过） |
| `android-build.yml` | `android-*` push | **已验证通过** |
| `ota-build.yml` / `sync-registry.yml` | 参照原逻辑 | 未改动 |

---

## 三、当前卡点（生产切换未执行）

生产镜像 **已构建成功**：`iboard:latest` = `db6b27b851b8`（924 MB，2026-10-26 22:53）

baihu 上当前跑着两套：

| 容器 | 用途 | 端口 |
| --- | --- | --- |
| `iboard`（旧） | **现网生产**，MySQL（宿主 3306） | 3001 |
| `iboard-021-app-1` 等 4 个 | 0.2.1 验证栈 | 13001 / 13002 / 13443 |
| （未启动）`iboard-prod` | **新生产栈**（PG + PowerSync + app） | 3001（计划） |

`/app/iboard-prod` 已上传源码、`deploy/prod/.env` 已生成（6 个密钥，600 权限）。

**剩余步骤（约 4 步）**：

1. 起新栈（先用 `HOST_PORT=13011` 灰度，不动现网）
2. 数据迁移：现网 MySQL → 新 PG（`scripts/etl-mariadb-to-pg.mjs`，只读源库）
3. 验证：健康检查、登录、任务列表、离线编辑（断网后仍可读）、同步回流
4. 切换：停 `iboard` 旧容器 → 新栈改绑 3001 → 域名 `iboard.honor3.com` 生效 → 下线验证栈（13001/13002/13443）

然后 `dev-0.2` → `master` 合并推送，触发 CI 发布。

---

## 四、需要确认的信息（阻塞项）

1. **Gitea Actions Secrets 是否要配 PG 密钥？**
   需配：`PG_PASSWORD`、`PS_STORAGE_PASSWORD`、`JWT_SECRET`、`POWERSYNC_JWT_SECRET`、`POWERSYNC_JWT_KEY_B64`。
   不配的话：master 的 CI 只构建镜像不部署，生产靠手工执行 `scripts/deploy/prod.sh`（当前默认路径）。

2. **生产数据迁移的时间窗口**：迁移需短暂停写（现网 MySQL 只读快照）。是否可以挑一个低峰时间、期间 (~10 分钟) 站点只读？

3. **现网 MySQL 里的米家凭证/缓存**：`/app/iboard/cache`（`auth.txt` 等）是否要一并搬到新栈的 `deploy/prod/data/cache`？

4. **用户密码**：迁移只搬数据，`JWT_SECRET` 若换新，所有人需重新登录；是否沿用现网 `JWT_SECRET`（`iboard`）以保持登录态？**建议换新**（当前值过弱）。

5. **域名端口说明**：`iboard.honor3.com` 实际反代到 baihu **3001**（NPM 配置：`114.134.187.170:3001`，SSL 强制）。
   你提到"已转向 3000 端口"——请确认指的是 `honor3.com` 根域（→ homepage）而非 `iboard` 子域，
   否则需要调整 NPM 的 forward_port。

---

## 五、关键路径与命令速查

```bash
# 仓库
C:\Users\Rabbit\Documents\workbetch\iboard          # dev-0.2 主工作区
C:\Users\Rabbit\Documents\workbetch\iboard-dev-0.2.1 # 研究分支 worktree
C:\Users\Rabbit\Documents\workbetch\iboard-dev-windows # Windows 外壳 worktree

# 服务器
ssh root@baihu            # 生产 + CI runner（baihu 上跑 act_runner，注册名 baishe）
ssh root@baishe           # 反代（NPM）、Gitea、homepage

# 生产目录
/app/iboard-prod/deploy/prod/{docker-compose.yml,.env,data/,powersync/,sql/,initdb/}

# 常用
docker compose -f /app/iboard-prod/deploy/prod/docker-compose.yml --env-file /app/iboard-prod/deploy/prod/.env ps
bash /app/iboard-prod/scripts/deploy/prod.sh
curl -s https://iboard.honor3.com/api/health
```

## 五之二、后续动作执行步骤（已确认方案，按序执行）

### 决策确认（2026-10-27）

| 项 | 决定 |
| --- | --- |
| PG 密钥 | **不进 Gitea Secrets**，直接写在服务器 `/app/iboard-prod/deploy/prod/.env`（600） |
| 迁移时机 | 立即执行 |
| 米家凭证 | 保留，`/app/iboard/cache` 搬到新栈 `deploy/prod/data/cache` |
| `JWT_SECRET` | 沿用现网值（`iboard`），保持现有登录态 |
| 域名 | `iboard.honor3.com` → baihu **3001**（NPM 已配好，SSL 强制） |

### 步骤 A：准备（不改动现网）

```bash
# A1. 沿用现网 JWT_SECRET (其余密钥保持已生成的随机值)
cd /app/iboard-prod/deploy/prod
sed -i 's/^JWT_SECRET=.*/JWT_SECRET=iboard/' .env

# A2. 搬米家缓存 (auth.txt 等)
mkdir -p data/cache
rsync -a /app/iboard/cache/ data/cache/

# A3. 保留旧镜像用于回滚
docker tag iboard:latest iboard:mysql-final      # 需在重新构建前执行; 若已覆盖见"回滚预案"
```

### 步骤 B：起灰度栈（不动现网 3001）

```bash
cd /app/iboard-prod/deploy/prod
HOST_PORT=13011 docker compose --project-name iboard-prod \
  --env-file .env -f docker-compose.yml up -d pg

# 迁移建表
docker run --rm --network iboard-prod_default \
  -e DATABASE_URL="postgresql://iboard:$(grep ^PG_PASSWORD .env | cut -d= -f2)@pg:5432/iboard" \
  iboard:latest npx prisma migrate deploy

# 建 publication (必须在建表之后)
docker compose --project-name iboard-prod --env-file .env -f docker-compose.yml exec -T pg \
  psql -U iboard -d iboard -v ON_ERROR_STOP=1 -f /dev/stdin < sql/publication.sql

# 起 app + powersync (只有 13011 对外)
HOST_PORT=13011 docker compose --project-name iboard-prod \
  --env-file .env -f docker-compose.yml up -d app powersync

# 验收
curl -s http://127.0.0.1:13011/api/health      # {"ok":true,...}
ss -tlnp | grep -E ':(13011|5432|8080)\b'      # 只应看到 13011
```

### 步骤 C：数据迁移（MySQL → PG）

```bash
docker run --rm --network iboard-prod_default \
  -e DATABASE_URL="postgresql://iboard:<PG_PASSWORD>@pg:5432/iboard" \
  -e SRC_DATABASE_URL="mysql://root:<MYSQL_PASSWORD>@<host>:3306/iboard" \
  iboard:latest node scripts/etl-mariadb-to-pg.mjs

# 迁移后重启同步服务重建快照
docker compose --project-name iboard-prod --env-file .env -f docker-compose.yml restart powersync
```

**验收**：项目 3 个（ADMIN / IBOARD / P3F921）、任务 ~22 条、用户 1 个（admin@iboard.local）；
`docker compose logs powersync` 显示 replication 已激活且无报错。

### 步骤 D：功能验证（13011）

- 登录 `admin@iboard.local`
- 任务页：项目卡片、任务编号（如 `ADMIN-16`）
- **离线验证**：断网后列表仍可读、左上角出现「离线」徽标，恢复网络自动同步回流
- 监控 / 宏观 / 打卡页有数据

### 步骤 E：切换生产

```bash
# E1. 停旧容器 (MySQL 版)
docker rm -vf iboard || true

# E2. 新栈改绑 3001
cd /app/iboard-prod/deploy/prod
HOST_PORT=3001 docker compose --project-name iboard-prod \
  --env-file .env -f docker-compose.yml up -d app
curl -s https://iboard.honor3.com/api/health       # 经 NPM + 证书

# E3. 下线 0.2.1 验证栈 (释放 13001/13002/13443)
cd /app/iboard-0.2.1/deploy/0.2.1 && docker compose down
```

**验收**：`https://iboard.honor3.com` 可登录、任务正常、离线可编辑；
`ss -tlnp` 只剩 3001（外加仅供本机的 3306）。

### 步骤 F：发布

```bash
git checkout master && git merge dev-0.2 --no-edit
git push origin master        # 触发 CI: 构建镜像 + OTA
```

CI 未配 PG secrets → 只构建不部署；生产已由步骤 B~E 手工就绪。

### 回滚预案

| 场景 | 动作 |
| --- | --- |
| 新栈起不来 | 旧容器未停，现网不受影响，回步骤 B 排查 |
| 迁移数据不对 | 清空 `deploy/prod/data/pg` 后重跑 ETL |
| 切换后严重故障 | **`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` 单值配置