From dacf6c0e1f54514ba3b706cbdc3ee1bd0a53f014 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Sat, 12 Sep 2026 01:17:49 +0800 Subject: [PATCH] =?UTF-8?q?feat(client):=20=E6=89=93=E9=80=9A=20Electron?= =?UTF-8?q?=20=E5=AE=89=E8=A3=85=E5=8C=85=E6=89=93=E5=8C=85=EF=BC=8C?= =?UTF-8?q?=E5=B9=B6=E7=95=99=E4=B8=8B=E6=9E=84=E5=BB=BA=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # 背景 Electron 桌面安装包一直没打出来过（`release/` 为空，只有 web bundle）。 这次把它跑通，并验证了产物本身而不只是"文件存在"。 # 改动 **package.json 补齐 electron-builder 需要的元数据**（缺哪个就会让某个 target 直接失败，而报错不一定指向字段本身）： | 字段 | 位置 | 不填的后果 | |---|---|---| | `description` | 根 | deb 描述为空 | | `author`（含 email） | 根 | deb 缺 maintainer | | `homepage` | 根 | **deb 直接失败**：`Please specify project homepage` | | `desktopName` | 根 | 窗口无法与 .desktop 关联（缺 `StartupWMClass`） | | `linux.syncDesktopName` | `build.linux` | 同上 | | `linux.synopsis` | `build.linux` | deb 描述只有一行 | **新增 `client/electron/BUILD.md`**：记录构建命令、本机两个坑（见下）、 元数据清单、两个产物的实质区别、以及验证产物的方法。 # 两个产物（已在 release/，被 .gitignore 排除） - `AgentMail-0.1.0.AppImage` 122MB，有效 x86-64 ELF、可执行位已设 - `agentmail-web_0.1.0_amd64.deb` 100MB，Maintainer/Homepage/Depends/两行 Description 齐全 **实测的实质区别（不是猜测，来自解包对照）**： | | AppImage | deb | |---|---|---| | `.desktop` Exec | `AppRun --no-sandbox %U` | `/opt/AgentMail/agentmail-web %U` | | Chromium 沙箱 | **禁用**（squashfs 无法保留 setuid 的 chrome-sandbox） | **启用**（postinst 按能力 `0755` 或 `4755`，并装 AppArmor 配置） | | 卸载 | 删文件 | postrm 清理 alternatives / AppArmor / desktop-mime 库 | 结论写进文档：**对外分发优先 deb**。 # 验证（不只查存在性） - AppImage：`--appimage-extract` 解包成功；`resources/app.asar` 8.5MB； asar 清单里 `/dist/index.html`、`/dist/assets/{index,CalendarView}.js`、 `/dist/assets/{agentmail.svg,favicon.ico,apple-touch-icon.png}`、 `/electron/{main,preload}.cjs` 齐全；`index.html` 里 DOCTYPE 仍是大写 （即格式化器修复也进了包） - deb：`dpkg-deb --info/--contents` 核对元数据与布局；7 档图标尺寸齐全； 读 postinst 确认沙箱策略与 AppArmor 安装 # 环境坑（已写进 BUILD.md） **本网络下 `SHASUMS256.txt` 不可达**（直连 20s 超时、走代理也失败）， 而 electron 构件本身 0.8s 就拿到（HTTP 206）。`@electron/get` 即使命中缓存 也会取校验文件 → 构建卡 10 分钟后失败。用命令行覆盖绕过： npx electron-builder --linux -c.electronDownload.isVerifyChecksum=false **刻意不写进 package.json** —— 那会让今后每次构建都跳过完整性校验。一次性绕过 网络限制不该固化成永久弱化的默认值。代价已写进文档（关校验后可被篡改镜像在 TLS 之外替换构件）。 # 待用户确认的占位值 - `author.email` 用了仓库自身的 git 身份 `jianf@noreply.localhost` —— 容器占位邮箱， **不是真实联系地址**。项目里没有可用的真实邮箱，我没有编造一个。 - `homepage` 用 git remote 的唯一真实地址（内网 Gitea `192.168.2.106:3000`）。 两者对外分发前都应替换。 --- client/electron/BUILD.md | 96 ++++++++++++++++++++++++++++++++++++ client/electron/package.json | 11 ++++- 2 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 client/electron/BUILD.md diff --git a/client/electron/BUILD.md b/client/electron/BUILD.md new file mode 100644 index 0000000..b32f161 --- /dev/null +++ b/client/electron/BUILD.md @@ -0,0 +1,96 @@ +# 桌面安装包构建 + +生成 Linux / Windows 安装包。日常开发只需 `npm run build`（出 web 产物）， +本文只讲**分发用安装包**。 + +## 命令 + +```bash +npm run build:linux # AppImage + deb +npm run build:win # NSIS 安装器 +``` + +产物在 `release/`（已在 `.gitignore` 里，不要提交 —— AppImage 约 122MB、deb 约 100MB）。 + +## 本机环境的两个坑 + +### 1. `SHASUMS256.txt` 不可达 → 构建会卡 10 分钟后失败 + +现象： + +``` +• downloaded label=electron progress=100% +⨯ Timeout awaiting 'request' for 600000ms failedTask=build +``` + +**不是构件下载失败**。实测该网络下： + +| URL | 结果 | +|---|---| +| `…/releases/download/v44.2.0/electron-v44.2.0-linux-x64.zip` | HTTP 206，0.8s ✅ | +| `…/releases/download/v44.2.0/SHASUMS256.txt` | 直连 20s 超时、走 Clash 代理也失败 ❌ | + +`@electron/get` 即使命中本地缓存，也会去取 `SHASUMS256.txt` 校验，于是卡死。 + +**绕过**（命令行覆盖，不要写进 `package.json`）： + +```bash +npx electron-builder --linux -c.electronDownload.isVerifyChecksum=false +``` + +**为什么不写进配置**：那会让今后**每一次**构建都跳过完整性校验。一次性绕过 +网络限制不该固化成永久弱化的默认值。关校验后，被篡改的镜像可以在 TLS 之外替换 +构件而无人察觉 —— 本场景可接受（构件来自官方 GitHub 的 TLS 连接，且本地缓存 +已验证可读），但不该成为默认。 + +### 2. 依赖缓存齐全，可离线完成 + +`~/.cache/electron-builder/` 下以下条目的 `.state` 均为 `complete` 即可离线： + +`appimage-12.0.1`（AppImage 运行时）、`fpm@2.1.4`（deb）、`7zip@1.0.0`、 +`nsis-resources-3.4.1` + `nsis-3.0.4.1`（Windows 安装器）。 + +Electron 二进制在 `~/.cache/electron/`（首次需要网络，`electron-v44.2.0-linux-x64.zip` 约 123MB）。 + +## package.json 里与打包有关的元数据 + +这些字段缺失会让某个 target 直接失败，报错信息不一定指向字段本身： + +| 字段 | 位置 | 不填的后果 | +|---|---|---| +| `description` | 根 | deb 描述为空 | +| `author`（含 email） | 根 | deb 缺 maintainer 信息 | +| `homepage` | 根 | **deb 直接构建失败**：`Please specify project homepage` | +| `desktopName` | 根 | 窗口无法与 `.desktop` 关联（`StartupWMClass` 缺失） | +| `linux.syncDesktopName` | `build.linux` | 同上，配合 `desktopName` 一起用 | +| `linux.synopsis` | `build.linux` | deb 描述只有一行 | + +> ⚠️ 当前 `author.email` 是容器占位值 `jianf@noreply.localhost`， +> `homepage` 是内网 Gitea 地址。**正式对外分发前必须替换成真实值。** + +## 两个产物的实质区别（实测） + +| | AppImage | deb | +|---|---|---| +| `.desktop` 的 Exec | `AppRun --no-sandbox %U` | `/opt/AgentMail/agentmail-web %U` | +| Chromium 沙箱 | **禁用** —— squashfs 里无法保留 setuid 的 `chrome-sandbox` | **启用** —— postinst 按能力决定：能跑用户命名空间则 `0755`，否则设 `4755`；并安装 AppArmor 配置（Ubuntu 24+ 需要） | +| 卸载 | 删文件即可 | postrm 清理 alternatives、AppArmor 配置、desktop/mime 数据库 | + +**要给用户装，优先分发 deb**：沙箱可用、依赖声明完整、可被包管理器卸载。 + +## 验证产物的方法（别只看文件存在） + +```bash +# deb 元数据与依赖 +dpkg-deb --info release/*.deb +# deb 内容布局（含 chrome-sandbox 权限、desktop 文件、图标尺寸） +dpkg-deb --contents release/*.deb | grep -E '\.desktop|chrome-sandbox|app\.asar' +# postinst 的沙箱策略 +dpkg-deb --control release/*.deb /tmp/ctl && cat /tmp/ctl/postinst + +# AppImage：不依赖 FUSE 解包并看载荷 +./release/AgentMail-0.1.0.AppImage --appimage-extract +ls squashfs-root/resources/app.asar +# 确认 asar 里是真正构建的应用（而不是空壳） +node -e "const a=require('@electron/asar');console.log(a.listPackage('release/linux-unpacked/resources/app.asar').filter(p=>/^\/(dist|electron)\//.test(p)).join('\n'))" +``` diff --git a/client/electron/package.json b/client/electron/package.json index f27384e..1b4a48e 100644 --- a/client/electron/package.json +++ b/client/electron/package.json @@ -2,6 +2,13 @@ "name": "agentmail-web", "version": "0.1.0", "private": true, + "description": "AgentMail —— 以邮件交互为统一范式的多智能体协作平台桌面客户端", + "author": { + "name": "JianFeeeee", + "email": "jianf@noreply.localhost" + }, + "homepage": "http://192.168.2.106:3000/jianf/MailUI4Agents", + "desktopName": "AgentMail", "type": "module", "main": "electron/main.cjs", "scripts": { @@ -67,7 +74,9 @@ { "target": "AppImage", "arch": ["x64"] }, { "target": "deb", "arch": ["x64"] } ], - "category": "Network" + "category": "Network", + "synopsis": "以邮件交互为统一范式的多智能体协作平台", + "syncDesktopName": true }, "nsis": { "oneClick": false,