ele-HeiXiu/UpdateA.md

HeiXiu 构建 & 发布手册

面向前端发版 + 后端 API 对接

---

一、整体架构

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│   客户端 (Electron)│         │   ECS (API 服务)   │         │   OSS (阿里云)    │
│                  │  GET    │                  │         │                  │
│ 版本检查 ─────────┼────────▶│ /api/v1/update/  │         │                  │
│                  │         │    check         │         │                  │
│                  │◀────────│ 返回 JSON        │         │                  │
│                  │         │                  │         │                  │
│ 下载安装包 ───────┼─────────┼──────────────────┼────────▶│ 静态文件托管      │
│                  │◀────────┼──────────────────┼─────────│ .exe / .dmg       │
│                  │         │                  │         │                  │
│ 安装 (spawn)     │         │                  │         │                  │
│ → app.quit()     │         │                  │         │                  │
└──────────────────┘         └──────────────────┘         └──────────────────┘

角色	技术	职责
客户端	Electron + net.request()	调用 API → 下载安装包 → 校验 SHA512 → 安装
ECS	任意后端语言	提供版本检查 API
OSS	阿里云对象存储	托管 .exe / .dmg / .AppImage

---

二、项目脚本速查

总入口：build.mjs

node build.mjs --help                 # 查看完整帮助
npm run build:win                     # 打包 Windows 个人版（快捷命令）

npm 命令速查

# 构建（仅打包，不上传/发布）
npm run build:win                     # Windows 个人版
npm run build:win:enterprise          # Windows 企业版
npm run build:mac                     # macOS 个人版
npm run build:linux                   # Linux 个人版

# 工具
npm run build:clean                   # 清理 release/ + dist/ + dist-electron/
node build.mjs --win --personal --help  # 查看完整 CLI 指南

# 独立脚本（需传参数）
node scripts/generate-update-info.mjs <平台> <版本类型> [版本号] [--url <url>]
node scripts/upload-oss.mjs <平台> <版本类型> [版本号]
node scripts/publish-release.mjs <平台> <版本类型> [版本号] [--url <url>]

build.mjs 操作组合

操作	说明
--build	构建（tsc + vite + electron-builder + update-info.json）
--clean	清理旧产物
--sign	代码签名（配合 --cert 或环境变量）
--upload	上传 OSS
--publish	POST 版本信息到后端 API
--all	全流程 = clean + build + sign + upload + publish

---

三、发版工作流

路径 A：快速打包（日常开发 / 内部测试）

# 1. 修改版本号
#    package.json → "version": "0.1.0"

# 2. 写更新日志
#    CHANGELOG.md → 顶部新增 ## 0.1.0（2026-xx-xx）...

# 3. 打包
npm run build:win && npm run build:win:enterprise

# 4. 产物在 release/0.1.0/ 下：
#    - xxx-Setup.exe（安装包）
#    - xxx-update-info.json（所有 API 字段，downloadUrl 为预判 URL）

# 5. 手动上传 exe 到 OSS releases/0.1.0/
# 6. 将 update-info.json 内容录入数据库 releases 表

路径 B：先上传再确定 URL

# 打包
npm run build:win

# 上传到 OSS（自动打印实际 URL）
node scripts/upload-oss.mjs win32 personal 0.1.0

# 用实际 URL 重新生成 update-info.json
node scripts/generate-update-info.mjs win32 personal 0.1.0 \
  --url "https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases/0.1.0/xxx.exe"

# 将 update-info.json 录入数据库

路径 C：全自动（上传 + 发布一条龙）

# 一步到位（需先配置环境变量）
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com \
OSS_BUCKET=heixiu \
OSS_ACCESS_KEY_ID=xxx \
OSS_ACCESS_KEY_SECRET=xxx \
UPDATE_API_KEY=xxx \
node build.mjs --win --personal --upload --publish

---

四、代码签名

证书获取

平台	格式	渠道	年费
Windows	.pfx / .p12	DigiCert / Sectigo / GlobalSign	$200-700
macOS	.p12 / Keychain	Apple Developer Program	$99

EV 证书立即消除 SmartScreen 警告；OV 证书需积累下载量。

签名方式

# 方式 1：build.mjs 参数
node build.mjs --win --personal --sign --cert ./cert.pfx --cert-password xxx

# 方式 2：环境变量（CI/CD 友好）
CSC_LINK=/path/to/cert.pfx CSC_KEY_PASSWORD=xxx npm run build:win

SHA512 校验值会在签名后自动计算（签名改变文件字节，必须先签后校）。

---

五、API 接口

GET /api/v1/update/check

参数：platform（win32/darwin/linux）、version（三段式 semver）、edition（personal/enterprise）

有更新：

{
   "code": 0,
   "data": {
      "hasUpdate": true,
      "latestVersion": "0.1.0",
      "downloadUrl": "https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases/0.1.0/xxx.exe",
      "fileSize": 98765432,
      "sha512": "Base64...",
      "changelog": "更新日志...",
      "releaseDate": "2026-06-03",
      "forceUpdate": false,
      "minimumVersion": "0.0.0"
   }
}

无更新：

{ "code": 0, "data": { "hasUpdate": false } }

POST /api/v1/releases（发布用）

{
   "platform": "win32",
   "edition": "personal",
   "latestVersion": "0.1.0",
   "downloadUrl": "https://...",
   "fileSize": 112910987,
   "sha512": "Base64...",
   "changelog": "...",
   "releaseDate": "2026-06-03",
   "forceUpdate": false,
   "minimumVersion": "0.0.0"
}

Header: Authorization: Bearer <UPDATE_API_KEY>

---

六、数据库

CREATE TABLE releases (
    id             BIGINT PRIMARY KEY AUTO_INCREMENT,
    platform       VARCHAR(10)  NOT NULL COMMENT 'win32 / darwin / linux',
    edition        VARCHAR(10)  NOT NULL COMMENT 'personal / enterprise',
    version        VARCHAR(20)  NOT NULL COMMENT '三段式 semver',
    file_url       VARCHAR(500) NOT NULL COMMENT 'OSS HTTPS 地址',
    file_size      BIGINT       NOT NULL COMMENT '字节数',
    sha512         VARCHAR(128) NOT NULL COMMENT 'Base64 编码',
    changelog      TEXT,
    force_update   TINYINT(1)   DEFAULT 0,
    min_version    VARCHAR(20)  DEFAULT '',
    release_date   DATE         NOT NULL,
    status         VARCHAR(10)  DEFAULT 'draft' COMMENT 'draft / published / deprecated',
    created_at     DATETIME     DEFAULT CURRENT_TIMESTAMP,
    updated_at     DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    UNIQUE KEY uk_platform_edition_version (platform, edition, version),
    INDEX idx_platform_edition_status (platform, edition, status)
);

---

七、客户端行为

场景	行为
启动	5 秒后静默检查更新（仅生产环境）
手动检查	点击按钮 → 调用 API → 反馈结果
下载	流式写入临时目录，SHA512 实时校验，每 250ms 推送进度
安装	用户确认 → spawn NSIS /S → app.quit()
强制更新	forceUpdate=true 时不可跳过
开发模式	跳过所有更新检查

---

八、环境变量速查

变量	默认值	用途
UPDATE_API_URL	https://www.heixiu.com	版本检查 API 基地址
UPDATE_API_KEY	—	发布 API 鉴权 Key
UPDATE_DOWNLOAD_BASE	https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases	预判 URL 基地址
OSS_ENDPOINT	—	阿里云 OSS endpoint
OSS_BUCKET	—	阿里云 OSS bucket
OSS_ACCESS_KEY_ID	—	阿里云 AccessKey ID
OSS_ACCESS_KEY_SECRET	—	阿里云 AccessKey Secret
OSS_BASE_PATH	releases	OSS 内基路径
CSC_LINK	—	签名证书路径
CSC_KEY_PASSWORD	—	签名证书密码
UPDATE_FORCE	false	强制更新标记（打包时）
UPDATE_CHANGELOG	读取 CHANGELOG.md	覆盖更新日志（CI/CD）

---

九、文件结构

ele-heixiu/
├ build.mjs                  ← 构建总管（npm run build 入口）
├ CHANGELOG.md               ← 更新日志（打包时自动提取）
├ UpdateA.md                 ← 本文档
├ package.json               ← 仅保留简短的 npm 快捷命令
├ scripts/
│ ├ clean.mjs                ← 清理产物
│ ├ generate-update-info.mjs ← 生成 API 信息 JSON
│ ├ upload-oss.mjs           ← 上传 OSS
│ └ publish-release.mjs      ← 发布到 API（axios）
├ release/                   ← 构建产物目录（按版本分）
│ └ 0.1.0/
│     ├ xxx-Setup.exe
│     └ xxx-update-info.json
├ dist/                      ← Vite 前端产物（构建输入）
└ dist-electron/             ← Electron 主进程产物（构建输入）

---

如有接口或流程变更，请同步更新此文档。