# hwelectron-platform

**Repository Path**: yukehang_admin/hwelectron-platform

## Basic Information

- **Project Name**: hwelectron-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hwelectron-platform

Electron 桌面应用脚手架。

## 技术栈

| 模块 | 选型 | 说明 |
| --- | --- | --- |
| 运行时 | Electron `35.0.3` | 固定版本 |
| UI 框架 | Vue 3 | **Options API** 语法 |
| UI 组件库 | Element Plus | 中文 locale |
| 自动更新 | electron-updater | 检查更新 / 手动下载 / 安装重启 |
| 更新源 | minio `192.168.234.1:9000` | 桶 `demo`，public 访问 |
| 构建 | electron-vite + electron-builder | 输出 NSIS 安装包 |

## 目录结构

```
hwelectron-platform/
├── electron-builder.yml        # 打包 + 发布配置（generic → minio）
├── electron.vite.config.mjs    # 三端构建配置
├── src/
│   ├── main/                   # 主进程（窗口/更新/SSO）
│   │   ├── index.js            # 窗口创建、应用生命周期
│   │   ├── sso.js              # SSO 客户端（回调服务器/认证窗口/ticket 换 token/注销）
│   │   ├── updater.js          # electron-updater 封装（手动更新模式）
│   │   └── index.js              # IPC 注册：update:* / sso:* / app:version
│   ├── preload/
│   │   └── index.js            # contextBridge 暴露 window.electronAPI（send/invoke/on 通用 IPC 桥）
│   └── renderer/               # 渲染进程（Vue3 Options API + Element Plus）
│       └── src/
│           ├── App.vue         # 主布局（左侧菜单 + 内容区）
│           └── views/
│               ├── SsoLogin.vue    # SSO 登录页
│               ├── UpdatePanel.vue  # 更新管理页
│               └── About.vue        # 关于页
└── package.json
```

## 快速开始

```bash
npm install
npm run dev          # 开发模式（热更新，加载 .env.development）
```

> 国内网络安装 electron 慢时，可配置镜像后重装：
> `npm config set electron_mirror https://npmmirror.com/mirrors/electron/`

## 环境变量（.env 文件）

项目按环境区分配置，通过 `MAIN_VITE_` 前缀暴露给主进程（`import.meta.env`）：

| 文件 | 加载时机 | 说明 |
| --- | --- | --- |
| `.env.development` | `npm run dev` | 开发环境 |
| `.env.test` | `npm run build:test` / `build:test:win` | 测试环境 |
| `.env.production` | `npm run build` / `build:prod:win` 等 | 生产环境（electron-vite 默认 mode） |

> `.env.*` 已加入 `.gitignore`。按环境创建
> `.env.development` / `.env.test` / `.env.production` 并填写真实配置即可。

当前变量：

- `MAIN_VITE_APP_BASE_API` — 业务 API 基础地址（`src/main/utils/request.js`
  的 baseURL，SSO/登录等接口均走此地址，相对路径接口依赖它）

按环境修改对应文件即可，例如测试环境把 `.env.test` 里的地址换成测试服务器。

## 打包

```bash
npm run build          # 生产构建（加载 .env.production）
npm run build:test     # 测试构建（加载 .env.test）
npm run build:prod:win # Windows NSIS 安装包（生产，输出到 dist/）
npm run build:test:win # Windows NSIS 安装包（测试环境配置）
npm run build:mac      # macOS dmg（需在 macOS 上执行）
npm run build:linux    # Linux AppImage
```

打包产物（`dist/`）包含：

- `hwelectron-platform Setup x.y.z.exe` — 安装包
- `latest.yml` — 更新元数据（sha512、版本、文件列表）
- `*.blockmap` — 增量更新用

## 内嵌 Spring Boot 后端

应用内置一个极简 Spring Boot 3.5.5 服务（`backend/`），随安装包一起分发，
由 Electron 主进程（`src/main/backend.js`）在应用启动时自动拉起，退出时关闭。

- 后端端口：`18080`（只监听 `127.0.0.1`），改端口需同步改
  `backend/src/main/resources/application.yml` 与 `src/main/backend.js` 的 `PORT`。
- 打包位置：jar 与精简 jre 经 `extraResources` 装入安装包的 `resources/backend/`，
  运行时由 `process.resourcesPath` 定位。
- 后端日志：写在用户数据目录的 `backend.log`，便于排查启动问题。

### 修改后端代码

后端源码在 `backend/src`，改完后重新构建：

```bash
cd backend && mvn -DskipTests package
```

### 重新生成精简 JRE（可选）

> 平时无需重跑，`backend/jre` 已生成且不进版本库。仅在更换 JDK 大版本时按需执行：

```bash
cd backend && mvn -DskipTests package
rm -rf jre
jlink --add-modules \
  java.base,java.logging,java.sql,java.naming,java.management, \
  java.instrument,jdk.unsupported,jdk.crypto.ec,java.xml, \
  java.desktop,java.security.jgss,java.security.sasl, \
  java.management.rmi,java.rmi,java.transaction.xa,java.compiler,jdk.management \
  --strip-debug --no-header-files --no-man-pages --compress=zip-6 --output jre
```

### 打包发布

先构建后端与前端，再打包：

```bash
npm run build        # 前端（含主进程集成的后端启停逻辑）
npm run build:prod:win
```

## 发布更新（上传 minio）

打包后把以下文件上传到 minio 的 `demo` 桶根目录：

- `hwelectron-platform Setup x.y.z.exe`
- `hwelectron-platform Setup x.y.z.exe.blockmap`
- `latest.yml`

因为 `demo` 桶是 public 访问，上传后即可通过
`http://192.168.234.1:9000/demo/latest.yml` 公开读取，electron-updater
的 generic provider 无需任何凭证。

上传方式任选其一：

```bash
# 方式一：一键脚本（推荐）—— 双击项目根目录 upload.bat
#   自动查找 mc → 连接 minio → 上传三件套，无需记命令
#   mc 下载: https://dl.minio.org.cn/client/mc/release/windows-amd64/mc.exe
#   (官方: https://dl.minio.io/client/mc/release/windows-amd64/mc.exe)

# 方式二：minio client (mc)
mc alias set myminio http://192.168.234.1:9000 minioadmin minioadmin
mc cp dist/*.exe dist/*.blockmap dist/latest.yml myminio/demo/

# 方式三：aws cli（S3 兼容接口）
aws --endpoint-url http://192.168.234.1:9000 s3 cp dist/ s3://demo/ \
    --recursive --exclude "*" \
    --include "*.exe" --include "*.blockmap" --include "latest.yml" \
    --profile minio-admin   # profile 配置 access-key=minioadmin, secret-key=minioadmin

# 方式四：minio Web 控制台 http://192.168.234.1:9000 手动上传
```

> 每次发布新版本前记得把 `package.json` 的 `version` 提升（如 `1.0.0` → `1.0.1`），
> electron-updater 依据版本号比较判断是否有更新。

## 更新流程说明

脚手架采用**手动更新**模式（`autoUpdater.autoDownload = false`），完整流程：

1. 用户点击「检查更新」→ 主进程读取 `app-update.yml` 中的发布地址，请求
   `http://192.168.234.1:9000/demo/latest.yml` 比对版本；
2. 发现新版本 → 界面提示，用户点击「下载更新」→ 主进程下载安装包并推送进度；
3. 下载完成 → 用户点击「安装并重启」→ `quitAndInstall()` 退出并安装重启。

> ⚠️ 开发模式（`npm run dev`）下没有 `app-update.yml`，electron-updater
> 会报错，因此脚手架只在 `app.isPackaged` 为 true 时初始化更新模块；
> 更新功能请用打包后的安装包验证。

## 架构约定

1. **Options API**：所有 Vue 组件均使用 `data / computed / methods / mounted`
   的 Options API 写法，不使用 `<script setup>`。
2. **安全基线**：`contextIsolation: true`、`nodeIntegration: false`、
   `sandbox: true`、CSP 已限制 `script-src 'self'` / `object-src 'none'` /
   `base-uri 'none'`；`update:install` 主进程侧校验"已下载完成"状态。
3. **通用 IPC 桥**：preload 暴露 `window.electronAPI.send / invoke / on`
   三个通用方法，未注册的 channel 调用会被主进程拒绝
   （`ipcMain.handle` 未注册时 invoke 报错）。

## 安全注意事项（重要）

⚠️ **更新源为明文 HTTP，存在 MITM 风险**：当前更新源
`http://192.168.234.1:9000/demo` 是内网 public 桶。攻击者若能在网络中劫持
该地址（ARP 欺骗 / DNS 劫持 / 网关被控），可替换 `latest.yml` 与安装包，
配合「安装并重启」实现任意代码执行（electron-updater 的 sha512 校验依赖
`latest.yml` 本身，明文下可被整体替换）。**正式环境务必**：

1. 更新源改为 HTTPS（minio 启用 TLS），并确保证书受信（electron-updater
   对 generic 源不做证书固定，依赖系统信任链）；
2. 或将桶改为私有 + 预签名 URL 方案，避免公开可读可替换；
3. 可选增强：对安装包做 Authenticode 代码签名，并配合
   `electron-updater` 的 Windows 签名校验（`latest.yml` 中声明
   `publisherName`），降低被伪造的概率。

## SSO 单点登录（后端整合模式）

后端服务已整合 SSO，客户端流程：

1. 点击「SSO 登录」→ 主进程启动本地回调服务器（127.0.0.1:41888，
   端口被占用时自动退回随机端口），得到回调地址
   `http://127.0.0.1:<port>/callback`；
2. 调业务后端 `/ssoLogin?redirect=<回调地址>` 获取 SSO 认证页地址；
3. 弹出认证窗口加载认证页（默认持久 session，认证域 cookie 保留 token，
   **下次登录免认证**直接带 ticket 回调）；
4. 认证成功后服务端重定向到回调地址并携带 ticket，主进程关闭认证窗口；
5. 主进程用 ticket 调 `/loginBySso` 换取 **token**（与普通登录一致），
   渲染层保存 token 后调 `/getInfo` 获取用户信息保存；
6. 「退出登录」→ 调 `/ssoLogout?userCode=<userCode>` 注销并清空本地状态。

相关接口定义在 `src/main/api/login.js`（`ssoLogin` / `loginBySso` /
`ssoLogout`），业务地址由 `.env` 的 `MAIN_VITE_APP_BASE_API` 提供。

安全说明：
- 回调只认 `ticket` 参数；回调缺少 ticket 时会立即报错并关闭窗口，不会白屏挂起。

## 自定义

- 应用图标：把 `icon.ico`（Windows）/ `icon.icns`（macOS）放入 `build/`，
  并取消 `electron-builder.yml` 中对应 `icon` 注释。
- 更新源变更：修改 `electron-builder.yml` 的 `publish.url` 后重新打包。
- 新增 IPC：在 `src/main/index.js` 注册 handler，并在
  `src/preload/index.js` 中暴露给渲染进程。