Yang-RuiQi/ele-HeiXiu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 初始化船长·HeiXiu 桌面应用项目（错误是svg的问题）

Browse Source 
Electron + React 19 + TypeScript + Ant Design 6 + Tailwind CSS 4

  【核心架构】
  - Electron 主进程（窗口管理、平台检测、图标适配）
  - Vite 构建链（双产物 dist/ + dist-electron/）
  - 共享层 shared/（类型、常量、工具函数）
  - IPC 通信框架 + 安全守卫

  【主题系统】
  - 蓝紫渐变主题（亮色/暗色双模式）
  - Ant Design ConfigProvider 适配（lightAlgorithm / darkAlgorithm）
  - Tailwind CSS 4 @theme 指令 + CSS 变量
  - 设计令牌三处同步（tokens.ts / globals.css / antd-theme.ts）

  【导航栏】
  - 自定义 H5 导航栏替代系统菜单
  - 个人版/企业版双布局
  - 未登录拦截 + 事件总线驱动登录弹窗

  【登录注册】
  - Modal 弹层（Portal）+ Tabs 切换
  - 登录/注册表单动态字段渲染
  - 记住密码 / 自动登录 / 用户协议

  【更新系统】
  - 自定义 API 版本检查（替代 electron-updater generic provider）
  - 手动下载 + SHA512 校验 + spawn NSIS 安装
  - 渲染进程更新状态机 Hook（useUpdater）
  - 检查更新按钮 + 下载进度展示

  【构建工具链】
  - build.mjs 构建总管（--win/--mac/--linux --personal/--enterprise --build/--clean/--sign/--upload/--publish）
  - scripts/ 自动化脚本（clean / generate-update-info / upload-oss / publish-release）
  - electron-builder NSIS 安装器（可选路径、多版本打包）
  - update-info.json 自动生成（fileSize/sha512/changelog/releaseDate）

  【代码质量】
  - ESLint + TypeScript strict + Prettier
  - husky + lint-staged（提交前自动检查）
  - commitlint（规范提交信息）
  - Playwright E2E + Vitest 单元测试框架
  - rollup-plugin-visualizer 打包体积分析

  【文档】
  - README.md（快速开始 + 目录结构 + 命令速查）
  - UpdateA.md（发布手册：API/签名/发版流程/数据库）
  - CHANGELOG.md（更新日志）
  - .env.example（构建环境变量模板）
This commit is contained in:
YoungestSongMo
2026-06-03 15:00:51 +08:00
commit 767bb8b297
95 changed files with 20814 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

284
UpdateA.md Normal file
View File

@@ -0,0 +1,284 @@
# 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`
```bash
node build.mjs --help # 查看完整帮助
npm run build:win # 打包 Windows 个人版（快捷命令）
```
### npm 命令速查
```bash
# 构建（仅打包，不上传/发布）
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：快速打包（日常开发 / 内部测试）
```bash
# 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
```bash
# 打包
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：全自动（上传 + 发布一条龙）
```bash
# 一步到位（需先配置环境变量）
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 证书需积累下载量。
### 签名方式
```bash
# 方式 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）
**有更新**：
```json
{
"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"
}
}
```
**无更新**：
```json
{ "code": 0, "data": { "hasUpdate": false } }
```
### `POST /api/v1/releases`（发布用）
```json
{
"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>`
---
## 六、数据库
```sql
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 主进程产物（构建输入）
```
---
_如有接口或流程变更，请同步更新此文档。_