192 lines
6.2 KiB
Markdown
192 lines
6.2 KiB
Markdown
# TrueGrowth 桌面端商业打包流程
|
||
|
||
本文档用于把 TrueGrowth 桌面端打包给 macOS 和 Windows 客户使用。
|
||
|
||
## 交付原则
|
||
|
||
- 客户电脑不需要安装 Node.js、pnpm、Vite 或开发源码。
|
||
- 安装包内置 TrueGrowth Web Renderer、Electron 桌面壳、Local API Gateway 和轻量运行脚本。
|
||
- 本地模型、ComfyUI、剪辑高级模型包、发布自动化浏览器等重运行时不默认塞进安装包；客户首次使用时从“模型中心”完成检测、下载、安装或登记已有目录。
|
||
- 打包后的应用目录按只读处理，运行状态、模型、缓存、日志和输出写入当前用户目录：
|
||
- macOS: `~/Library/Application Support/TrueGrowth/runtime`
|
||
- Windows: `%APPDATA%/TrueGrowth/runtime`
|
||
|
||
## 本机准备
|
||
|
||
```bash
|
||
corepack enable pnpm
|
||
pnpm install
|
||
```
|
||
|
||
建议使用 Node.js 20.19+。如果本机默认 Node 太旧，可临时使用：
|
||
|
||
```bash
|
||
export PATH="/usr/local/opt/node@20/bin:$PATH"
|
||
```
|
||
|
||
## 常用打包命令
|
||
|
||
生成当前平台可运行目录，适合快速检查：
|
||
|
||
```bash
|
||
pnpm desktop:build:dir
|
||
```
|
||
|
||
生成 macOS 内测安装包：
|
||
|
||
```bash
|
||
pnpm desktop:build:mac
|
||
```
|
||
|
||
默认生成 macOS ZIP。若构建机的 `hdiutil` 可用并且需要 DMG，可执行：
|
||
|
||
```bash
|
||
pnpm desktop:build:mac:dmg
|
||
```
|
||
|
||
生成 macOS 商业客户包：
|
||
|
||
```bash
|
||
pnpm desktop:signing:check
|
||
pnpm desktop:build:mac:signed
|
||
```
|
||
|
||
生成 Windows 安装包：
|
||
|
||
```bash
|
||
pnpm desktop:build:win
|
||
```
|
||
|
||
一条命令会依次执行：
|
||
|
||
1. `pnpm build:web` 构建生产 Web Renderer。
|
||
2. `pnpm desktop:prepare` 生成图标并把运行所需文件 staged 到 `dist/desktop/app`。
|
||
3. `electron-builder --config electron-builder.yml` 生成桌面端产物。
|
||
|
||
产物输出目录：
|
||
|
||
```text
|
||
dist/desktop/release/
|
||
```
|
||
|
||
## macOS 商业分发
|
||
|
||
macOS 可在 Mac 上构建。未签名包只适合内部测试，商业交付必须使用 Developer ID Application 证书完成签名，并通过 Apple 公证。
|
||
|
||
### 证书判断
|
||
|
||
本机证书目录中的常见文件含义：
|
||
|
||
- `distribution.cer`: 如果证书类型是 `Apple Distribution`，它不适合作为官网、网盘或私有下载链接直接分发给客户的 macOS 桌面包证书。
|
||
- `*.p12`: 需要证书密码才能确认里面的证书类型。商业客户包必须使用 `Developer ID Application` 类型的私钥证书包。
|
||
- `AuthKey_<KEY_ID>.p8`: App Store Connect API Key，只用于公证上传认证，不用于代码签名。
|
||
- `*.certSigningRequest`: 证书申请文件，不参与打包。
|
||
|
||
当前本机钥匙串检查结果是 `0 valid identities found`，说明还没有可用的代码签名身份。客户分发前需要在 Apple Developer 后台创建并导出：
|
||
|
||
```text
|
||
Developer ID Application: <Company Name> (<TEAM_ID>)
|
||
```
|
||
|
||
把该证书导出为 `.p12` 后，再配置签名环境。
|
||
|
||
### 本机签名配置
|
||
|
||
复制模板：
|
||
|
||
```bash
|
||
cp .env.desktop-signing.example .env.desktop-signing.local
|
||
```
|
||
|
||
填写 `.env.desktop-signing.local`：
|
||
|
||
```bash
|
||
CSC_LINK=/path/to/DeveloperIDApplication.p12
|
||
CSC_KEY_PASSWORD=证书密码
|
||
APPLE_API_KEY=/path/to/AuthKey_KEYID.p8
|
||
APPLE_API_KEY_ID=KEYID
|
||
APPLE_API_ISSUER=App Store Connect Issuer ID
|
||
APPLE_TEAM_ID=TEAMID
|
||
TRUEGROWTH_MAC_TARGETS=zip
|
||
TRUEGROWTH_NOTARIZE=true
|
||
```
|
||
|
||
`.env.desktop-signing.local` 已被 `.gitignore` 忽略，不要提交。`APPLE_API_ISSUER` 在 App Store Connect 的 Users and Access / Integrations / App Store Connect API 页面查看。
|
||
|
||
检查配置：
|
||
|
||
```bash
|
||
pnpm desktop:signing:check
|
||
```
|
||
|
||
检查通过后生成商业客户包：
|
||
|
||
```bash
|
||
pnpm desktop:build:mac:signed
|
||
```
|
||
|
||
这条命令会自动执行 Web 构建、桌面 staging、Electron Builder 签名、公证和更新清单生成。签名检查不通过时会直接失败，避免误把未签名包发给客户。
|
||
|
||
当前构建机创建 DMG 曾出现 `hdiutil` `设备未配置`，所以默认商业配置建议先用 ZIP。macOS 自动更新也需要 ZIP 和 `.blockmap`。如果换到 DMG 正常的构建机，可把 `.env.desktop-signing.local` 改为：
|
||
|
||
```bash
|
||
TRUEGROWTH_MAC_TARGETS=zip dmg
|
||
```
|
||
|
||
### 验证签名和公证
|
||
|
||
打包后至少执行：
|
||
|
||
```bash
|
||
codesign --verify --deep --strict dist/desktop/release/mac-arm64/TrueGrowth.app
|
||
spctl --assess --type execute --verbose dist/desktop/release/mac-arm64/TrueGrowth.app
|
||
xcrun stapler validate dist/desktop/release/mac-arm64/TrueGrowth.app
|
||
```
|
||
|
||
若 Electron Builder 输出路径随版本或架构变化，以实际 `dist/desktop/release/` 下的 `.app` 路径为准。
|
||
|
||
## Windows 商业分发
|
||
|
||
Windows 正式安装包建议在 Windows 电脑或 Windows CI runner 上构建：
|
||
|
||
```bash
|
||
corepack enable pnpm
|
||
pnpm install
|
||
pnpm desktop:build:win
|
||
```
|
||
|
||
商业分发建议准备 Authenticode 代码签名证书。macOS 上可以尝试交叉构建 Windows 包，但不建议把 macOS 交叉构建结果作为最终商业交付包，尤其是签名、杀软信誉和安装体验都应在 Windows 环境验证。
|
||
|
||
## 客户首次运行
|
||
|
||
客户安装并打开 TrueGrowth 后，基础工作台、素材、任务、画布和 Local API 会随应用启动。需要本地模型或重运行时的功能，从“模型中心”完成：
|
||
|
||
- 系统环境检测
|
||
- ComfyUI 安装或登记已有目录
|
||
- Hugging Face 下载源选择
|
||
- FLUX / Qwen-Image 等模型下载
|
||
- VideoAgent 剪辑 / ASR / 发布自动化能力检查
|
||
|
||
客户不需要手动运行仓库命令。需要管理员权限或外部安装器的步骤，会在模型中心以客户可理解的引导呈现。
|
||
|
||
## 验证清单
|
||
|
||
每次发客户包前至少检查：
|
||
|
||
- `pnpm build:web` 成功。
|
||
- `pnpm desktop:prepare` 成功，并生成 `dist/desktop/app`。
|
||
- `pnpm desktop:build:dir` 或目标平台打包命令成功。
|
||
- 启动打包后的应用，确认不是加载 `127.0.0.1:7200` 开发服务。
|
||
- 打开模型中心，确认运行目录显示为用户目录，不是应用安装目录。
|
||
- 打开 `/local-api/health` 或模型中心状态，确认 Local API 已启动。
|
||
- macOS 商业包完成签名/公证；Windows 商业包完成签名并在真实 Windows 电脑安装测试。
|
||
|
||
## 空间建议
|
||
|
||
构建机至少预留：
|
||
|
||
- Web + Electron 打包临时空间：10GB+
|
||
- 如果要本机测试下载模型：额外 80GB+
|
||
|
||
仓库中的 `vendor/ComfyUI/models`、Python `.venv`、缓存和运行输出不会被默认复制进安装包。它们应由客户首次运行后在模型中心按需准备。
|