feat: 构建资源本地缓存 + restore-build-cache.sh + 更新 BUILD.md

- restore-build-cache.sh: 自动从 build-resources/ 或镜像恢复缓存 - build-resources/ 已在 .gitignore（不进 git，145MB） - BUILD.md: 重写为快速构建 3 步指南
2026-04-07 02:20:41 +08:00
parent 8f77bcfb1a
commit 9f01138062
2 changed files with 191 additions and 125 deletions
@@ -6,116 +6,86 @@
 - Node.js v22+
 - Wine 9.0+（用于 electron-builder 交叉编译）
 - i386 架构已启用（`dpkg --add-architecture i386`）
+- p7zip-full（解压构建资源）

-## 构建步骤
-
-### 1. 克隆项目
+## 快速构建（3 步）

 ```bash
+# 1. 克隆并安装依赖
 git clone https://gitee.com/thzxx/metona-ollama.git
 cd metona-ollama
-git checkout metona-ollama-desktop-v3
+npm config set registry https://registry.npmmirror.com
+npm install
+
+# 2. 恢复构建缓存（首次从镜像下载，后续使用本地缓存）
+bash restore-build-cache.sh
+
+# 3. 构建
+ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist
 ```

-### 2. 安装依赖（使用国内镜像）
+产出文件在 `release/` 目录。
+
+## 构建资源管理
+
+构建需要以下资源（共 ~145MB），通过 `restore-build-cache.sh` 自动管理：
+
+| 资源 | 大小 | 来源 |
+|------|------|------|
+| Electron v33.4.11 win32-x64 | 110MB | npmmirror |
+| NSIS 3.0.4.1 | 7.8MB | GitHub (ghfast.top 代理) |
+| NSIS Resources 3.4.1 | 3.0MB | GitHub (ghfast.top 代理) |
+| winCodeSign 2.6.0 | 24MB | GitHub (ghfast.top 代理) |
+
+**工作原理**：
+- 首次运行：从镜像下载 → 自动缓存到 `build-resources/` 和 `~/.cache/`
+- 后续运行：从 `build-resources/` 复制到 `~/.cache/`（秒级完成）
+- `build-resources/` 在 `.gitignore` 中，不进 git（Electron 二进制 110MB 超 git 限制）
+
+**自定义镜像**：
+```bash
+GITHUB_PROXY=https://gh-proxy.com/ bash restore-build-cache.sh
+```
+
+## 详细步骤
+
+### 1. 安装 Wine
+
+```bash
+dpkg --add-architecture i386
+apt-get update
+apt-get install -y wine wine32 p7zip-full
+```
+
+### 2. 安装 npm 依赖

 ```bash
 npm config set registry https://registry.npmmirror.com
 npm install
 ```

-> ⚠️ **不要用默认 npm 源**，国内环境下大概率超时。npmmirror 速度快且稳定。
+### 3. 恢复构建缓存

-### 3. 构建 Windows 安装包
+```bash
+bash restore-build-cache.sh
+```
+
+首次会从镜像下载约 145MB 资源，后续构建只需秒级恢复。
+
+### 4. 构建 Windows 安装包

 ```bash
 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist
 ```

-> ⚠️ **必须设置 `ELECTRON_MIRROR`**，否则 electron-builder 会从 GitHub 下载 Electron 二进制（115MB），国内基本连不上。
-
-## 遇到的问题与解决方案
-
-### 问题 1：apt 源不可用（阿里云镜像超时）
-
-**现象**：`apt-get update` 报错 `mirrors.cloud.aliyuncs.com` 连接超时。
-
-**解决**：替换为 Ubuntu 官方源：
-
-```bash
-sed -i 's|http://mirrors.cloud.aliyuncs.com/ubuntu|http://archive.ubuntu.com/ubuntu|g' /etc/apt/sources.list
-```
-
-### 问题 2：npm install 超时
-
-**现象**：使用默认 npm registry 下载依赖超时。
-
-**解决**：切换到 npmmirror 国内镜像：
-
-```bash
-npm config set registry https://registry.npmmirror.com
-```
-
-### 问题 3：Electron 下载超时（GitHub 连不上）
-
-**现象**：electron-builder 打包时卡在 `downloading electron-v33.4.11-win32-x64.zip`，115MB 从 GitHub 下载，国内超时。
-
-**解决**：设置环境变量使用 npmmirror 的 Electron 镜像：
-
-```bash
-ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist
-```
-
-设置后 4.22 秒下载完成，vs 之前直接超时。
-
-### 问题 4：Wine 未安装
-
-**现象**：构建时报错 `cannot find wine`，electron-builder 需要 Wine 来交叉编译 Windows 应用。
-
-**解决**：安装 Wine 以及 32 位支持：
-
-```bash
-# 启用 i386 架构
-dpkg --add-architecture i386
-
-# 如果阿里云 apt 源不可用，先切到官方源
-sed -i 's|http://mirrors.cloud.aliyuncs.com/ubuntu|http://archive.ubuntu.com/ubuntu|g' /etc/apt/sources.list
-apt-get update
-
-# 安装 Wine
-apt-get install -y wine wine32
-```
-
-> 💡 `wine32` 包是必须的，否则 electron-builder 的 32 位打包步骤会失败。
-
-### 问题 5：winCodeSign 下载慢
-
-**现象**：electron-builder 需要从 GitHub 下载 `winCodeSign-2.6.0`（5.6MB）。
-
-**说明**：这个文件较小，即使从 GitHub 下载通常也能完成（可能需要几分钟）。如果超时，可以手动下载放到缓存目录：
-
-```bash
-# electron-builder 缓存目录
-~/.cache/electron-builder/winCodeSign/winCodeSign-2.6.0/
-```
-
 ## 常用命令

 ```bash
-# 开发运行
-npm start
-
-# 仅构建目录（不打包，用于测试）
-npm run pack
-
-# 构建 NSIS 安装包
-npm run dist:nsis
-
-# 构建绿色便携版
-npm run dist:portable
-
-# 构建全部（NSIS + Portable）
-npm run dist
+npm start              # 开发运行
+npm run pack           # 仅构建目录（不打包）
+npm run dist:nsis      # 仅 NSIS 安装包
+npm run dist:portable  # 仅绿色便携版
+npm run dist           # 全部（NSIS + Portable）
 ```

 ## 构建产物
@@ -127,56 +97,55 @@ npm run dist

 ## 发布到 Gitee

+### 创建 Release
+
+```bash
+TOKEN="your_access_token"
+curl -X POST "https://gitee.com/api/v5/repos/thzxx/metona-ollama/releases?access_token=$TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag_name":"v3.1.0","name":"v3.1.0","body":"Release notes","target_commitish":"refactor/modular-architecture"}'
+```
+
 ### 上传附件

 ```bash
 TOKEN="your_access_token"
-RELEASE_ID="600168"  # v1.1.0 release ID
-
-curl -X POST \
-  "https://gitee.com/api/v5/repos/thzxx/metona-ollama/releases/$RELEASE_ID/attach_files?access_token=$TOKEN" \
-  -H "Content-Type: multipart/form-data" \
-  -F "file=@release/Metona Ollama Setup 1.1.0.exe"
-
-curl -X POST \
-  "https://gitee.com/api/v5/repos/thzxx/metona-ollama/releases/$RELEASE_ID/attach_files?access_token=$TOKEN" \
-  -H "Content-Type: multipart/form-data" \
-  -F "file=@release/MetonaOllama-Portable-1.1.0.exe"
+RELEASE_ID="600564"
+curl -X POST "https://gitee.com/api/v5/repos/thzxx/metona-ollama/releases/$RELEASE_ID/attach_files?access_token=$TOKEN" \
+  -H "Content-Type: multipart/form-data" -F "file=@release/Metona Ollama Setup 3.1.0.exe"
+curl -X POST "https://gitee.com/api/v5/repos/thzxx/metona-ollama/releases/$RELEASE_ID/attach_files?access_token=$TOKEN" \
+  -H "Content-Type: multipart/form-data" -F "file=@release/MetonaOllama-Portable-3.1.0.exe"
 ```

-### 清理重复附件
+## 故障排查

-```bash
-# 查看附件列表
-curl -s "https://gitee.com/api/v5/repos/thzxx/metona-ollama/releases/$RELEASE_ID/attach_files?access_token=$TOKEN"
-
-# 删除指定附件
-curl -X DELETE "https://gitee.com/api/v5/repos/thzxx/metona-ollama/releases/$RELEASE_ID/attach_files/$ASSET_ID?access_token=$TOKEN"
-```
+| 问题 | 解决方案 |
+|------|----------|
+| apt 源超时 | `sed -i 's\|mirrors.cloud.aliyuncs.com\|archive.ubuntu.com\|g' /etc/apt/sources.list` |
+| npm 超时 | `npm config set registry https://registry.npmmirror.com` |
+| Electron 下载超时 | 设 `ELECTRON_MIRROR` 或用 `restore-build-cache.sh` |
+| NSIS/winCodeSign 下载超时 | `GITHUB_PROXY=https://gh-proxy.com/ bash restore-build-cache.sh` |
+| "symbol already declared" | 检查 TS 文件中的重复 `const`/`let` 声明 |

 ## 构建日志

-### v3.0.0 构建记录（2026-04-06）
+### v3.1.0（2026-04-07）

-**环境**：Ubuntu 24.04 (Linux 6.8.0-100-generic x64)，Node.js v22.22.1
+- ✅ `Metona Ollama Setup 3.1.0.exe`（78MB）
+- ✅ `MetonaOllama-Portable-3.1.0.exe`（78MB）
+- ✅ Gitee Release v3.1.0（ID: 600564）

-**遇到的问题**：
-1. apt 阿里云镜像源连接超时 → 切换到 Ubuntu 官方源
-2. 未安装 Wine → 需安装 `wine` 和 `wine32`（i386 架构）
-3. npm 使用默认源下载慢 → 切换到 npmmirror
+### v3.0.0（2026-04-06）

-**构建结果**：
- ✅ `Metona Ollama Setup 3.0.0.exe`（78MB，NSIS 安装包）
- ✅ `MetonaOllama-Portable-3.0.0.exe`（78MB，便携版）
- ✅ 发布到 Gitee Release v3.0.0（Release ID: 600370）
-
-**耗时**：约 20 分钟（含依赖安装 + Wine 安装 + 打包）
+- ✅ `Metona Ollama Setup 3.0.0.exe`（78MB）
+- ✅ `MetonaOllama-Portable-3.0.0.exe`（78MB）
+- ✅ Gitee Release v3.0.0（ID: 600370）

 ## 提速清单

-| 环节 | 默认方案 | 加速方案 | 效果 |
-|------|----------|----------|------|
-| apt 源 | archive.ubuntu.com | 保持官方源即可 | 稳定可用 |
-| npm 依赖 | registry.npmjs.org | registry.npmmirror.com | 59s 完成 |
-| Electron 下载 | github.com | npmmirror.com/mirrors/electron | 4s 完成（vs 超时） |
-| winCodeSign | github.com | 小文件可等待 / 手动缓存 | 通常可完成 |
+| 环节 | 默认 → 加速 | 效果 |
+|------|------------|------|
+| apt 源 | aliyuncs → archive.ubuntu.com | 稳定 |
+| npm | npmjs → npmmirror | ~17s |
+| Electron | github → npmmirror | ~3s |
+| NSIS/winCodeSign | github → ghfast + 本地缓存 | 秒级 |
@@ -0,0 +1,97 @@
+#!/bin/bash
+# restore-build-cache.sh
+# 从 build-resources/ 恢复 electron-builder 缓存，加速构建
+# 如果本地资源不存在，自动从镜像下载
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CACHE_ELECTRON="$HOME/.cache/electron"
+CACHE_BUILDER="$HOME/.cache/electron-builder"
+LOCAL="$SCRIPT_DIR/build-resources"
+
+ELECTRON_MIRROR="${ELECTRON_MIRROR:-https://npmmirror.com/mirrors/electron/}"
+GITHUB_PROXY="${GITHUB_PROXY:-https://ghfast.top/}"
+GITHUB_ORIG="https://github.com/electron-userland/electron-builder-binaries/releases/download"
+
+ELECTRON_VERSION="33.4.11"
+NSIS_VERSION="3.0.4.1"
+NSIS_RES_VERSION="3.4.1"
+WINCODESIGN_VERSION="2.6.0"
+
+echo "===== 恢复构建缓存 ====="
+
+ELECTRON_FILE="electron-v${ELECTRON_VERSION}-win32-x64.zip"
+mkdir -p "$CACHE_ELECTRON"
+if [ -f "$LOCAL/electron/$ELECTRON_FILE" ]; then
+    echo "[1/4] Electron ← 本地缓存"
+    cp "$LOCAL/electron/$ELECTRON_FILE" "$CACHE_ELECTRON/"
+elif [ -f "$CACHE_ELECTRON/$ELECTRON_FILE" ]; then
+    echo "[1/4] Electron ← 缓存已存在"
+else
+    echo "[1/4] Electron ← 下载 ${ELECTRON_MIRROR}${ELECTRON_FILE}"
+    mkdir -p "$LOCAL/electron"
+    wget -q --show-progress -O "$CACHE_ELECTRON/$ELECTRON_FILE" "${ELECTRON_MIRROR}${ELECTRON_FILE}"
+    cp "$CACHE_ELECTRON/$ELECTRON_FILE" "$LOCAL/electron/"
+fi
+
+mkdir -p "$CACHE_BUILDER/nsis"
+NSIS_DIR="$CACHE_BUILDER/nsis/nsis-${NSIS_VERSION}"
+if [ -d "$LOCAL/electron-builder/nsis-${NSIS_VERSION}" ]; then
+    echo "[2/4] NSIS ${NSIS_VERSION} ← 本地缓存"
+    cp -r "$LOCAL/electron-builder/nsis-${NSIS_VERSION}" "$NSIS_DIR"
+elif [ -d "$NSIS_DIR" ]; then
+    echo "[2/4] NSIS ${NSIS_VERSION} ← 缓存已存在"
+else
+    echo "[2/4] NSIS ${NSIS_VERSION} ← 下载"
+    mkdir -p "$LOCAL/electron-builder"
+    wget -q --show-progress -O "/tmp/nsis-${NSIS_VERSION}.7z" \
+        "${GITHUB_PROXY}${GITHUB_ORIG}/nsis-${NSIS_VERSION}/nsis-${NSIS_VERSION}.7z"
+    cd "$CACHE_BUILDER/nsis"
+    7z x -y "/tmp/nsis-${NSIS_VERSION}.7z" -o"nsis-${NSIS_VERSION}" >/dev/null
+    rm -f "/tmp/nsis-${NSIS_VERSION}.7z"
+    cp -r "$NSIS_DIR" "$LOCAL/electron-builder/"
+    cd "$SCRIPT_DIR"
+fi
+
+NSIS_RES_DIR="$CACHE_BUILDER/nsis/nsis-resources-${NSIS_RES_VERSION}"
+if [ -d "$LOCAL/electron-builder/nsis-resources-${NSIS_RES_VERSION}" ]; then
+    echo "[3/4] NSIS Resources ${NSIS_RES_VERSION} ← 本地缓存"
+    cp -r "$LOCAL/electron-builder/nsis-resources-${NSIS_RES_VERSION}" "$NSIS_RES_DIR"
+elif [ -d "$NSIS_RES_DIR" ]; then
+    echo "[3/4] NSIS Resources ${NSIS_RES_VERSION} ← 缓存已存在"
+else
+    echo "[3/4] NSIS Resources ${NSIS_RES_VERSION} ← 下载"
+    mkdir -p "$LOCAL/electron-builder"
+    wget -q --show-progress -O "/tmp/nsis-resources-${NSIS_RES_VERSION}.7z" \
+        "${GITHUB_PROXY}${GITHUB_ORIG}/nsis-resources-${NSIS_RES_VERSION}/nsis-resources-${NSIS_RES_VERSION}.7z"
+    cd "$CACHE_BUILDER/nsis"
+    7z x -y "/tmp/nsis-resources-${NSIS_RES_VERSION}.7z" -o"nsis-resources-${NSIS_RES_VERSION}" >/dev/null
+    rm -f "/tmp/nsis-resources-${NSIS_RES_VERSION}.7z"
+    cp -r "$NSIS_RES_DIR" "$LOCAL/electron-builder/"
+    cd "$SCRIPT_DIR"
+fi
+
+WINCS_DIR="$CACHE_BUILDER/winCodeSign/winCodeSign-${WINCODESIGN_VERSION}"
+if [ -d "$LOCAL/electron-builder/winCodeSign-${WINCODESIGN_VERSION}" ]; then
+    echo "[4/4] winCodeSign ${WINCODESIGN_VERSION} ← 本地缓存"
+    mkdir -p "$CACHE_BUILDER/winCodeSign"
+    cp -r "$LOCAL/electron-builder/winCodeSign-${WINCODESIGN_VERSION}" "$WINCS_DIR"
+elif [ -d "$WINCS_DIR" ]; then
+    echo "[4/4] winCodeSign ${WINCODESIGN_VERSION} ← 缓存已存在"
+else
+    echo "[4/4] winCodeSign ${WINCODESIGN_VERSION} ← 下载"
+    mkdir -p "$LOCAL/electron-builder"
+    mkdir -p "$CACHE_BUILDER/winCodeSign"
+    wget -q --show-progress -O "/tmp/winCodeSign-${WINCODESIGN_VERSION}.7z" \
+        "${GITHUB_PROXY}${GITHUB_ORIG}/winCodeSign-${WINCODESIGN_VERSION}/winCodeSign-${WINCODESIGN_VERSION}.7z"
+    cd "$CACHE_BUILDER/winCodeSign"
+    7z x -y "/tmp/winCodeSign-${WINCODESIGN_VERSION}.7z" -o"winCodeSign-${WINCODESIGN_VERSION}" >/dev/null
+    rm -f "/tmp/winCodeSign-${WINCODESIGN_VERSION}.7z"
+    cp -r "$WINCS_DIR" "$LOCAL/electron-builder/"
+    cd "$SCRIPT_DIR"
+fi
+
+echo ""
+echo "===== 缓存恢复完成 ====="
+echo "现在可以运行: ELECTRON_MIRROR=$ELECTRON_MIRROR npm run dist"