ClientApps/pqs-9100_client

Fork 0

Files

hongawen 2322858bc4 绿色包保存

2025-11-27 20:50:59 +08:00

22 KiB

Raw Blame History

NPQS-9100 绿色包完整指南

本指南包含绿色包的打包、使用、升级和维护的完整说明。

📋 目录

一、产品说明
七、用户关心的文件⭐
二、打包指南
三、启动流程
四、升级指南
五、测试清单
六、常见问题

一、产品说明

📦 产品特性

绿色包是一个免安装便携版，包含：

✅ 应用本体（Electron + Vue 3）
✅ MySQL 数据库（免安装版，支持动态端口）
✅ Java 运行环境（JRE 8）
✅ Spring Boot 后端服务（entrance.jar）
✅ 智能启动流程（端口检测、Loading界面）
✅ 一键升级回滚机制 ⭐

用户体验：解压即用，双击启动，无需任何配置

🎯 核心功能

1. 智能端口检测

MySQL 端口：从 3306 开始自动检测（最多 100 个）
Java 端口：从 18092 开始自动检测（最多 100 个）
自动更新配置文件

2. 盘符自动识别

应用在 C 盘 → 数据目录：C:\NPQS9100_Data\
应用在 D 盘 → 数据目录：D:\NPQS9100_Data\
自动创建所有必要的子目录

3. Loading 界面

紫色渐变背景
流畅的进度条动画（0% → 100%）
实时状态文字更新
显示检测到的端口号和数据目录路径

4. 热更新机制 ⭐

前端可独立升级
后端可独立升级
自动备份，支持一键回滚
数据库数据完全保留

5. 简化配置管理

基于环境变量的配置方案
需要修改配置时重新打包前端（upgrade.bat 升级）
保证稳定性和可靠性

📁 目录结构

win-unpacked/                           # 绿色版目录（约 650-800 MB）
├── NPQS9100.exe                        # 主程序（双击运行）⭐
├── NPQS9100-启动器.bat                  # 管理员启动器（备用）
├── upgrade.bat                         # 升级工具 ⭐
├── rollback.bat                        # 回滚工具 ⭐
├── uninstall-mysql-service.bat         # MySQL 服务卸载工具
├── 使用说明.txt                         # 使用手册
├── README-升级回滚.txt                  # 升级说明
├── upgrade/                            # 升级包目录（首次使用自动创建）
├── backup/                             # 自动备份目录
│   ├── dist/                          # 前端备份
│   ├── entrance.jar                   # 后端备份
│   └── version.txt                    # 版本记录
├── resources/
│   ├── app.asar                       # Electron 主代码（加密）
│   ├── app.asar.unpacked/
│   │   └── public/
│   │       └── dist/                  # 前端代码 ⭐ 可替换
│   └── extraResources/
│       ├── dll/
│       └── java/
│           ├── entrance.jar           # 后端 JAR ⭐ 可替换
│           ├── application.yml.template
│           └── application.yml        # 运行时生成
├── scripts/                           # 启动管理脚本（⚠️ 不要修改）
│   ├── config-generator.js
│   ├── java-runner.js
│   ├── mysql-service-manager.js
│   ├── port-checker.js
│   └── startup-manager.js
├── mysql/                             # MySQL 数据库
│   ├── bin/
│   ├── data/                          # 数据库数据 ⚠️ 不要动
│   ├── data_backup/                   # 自动备份
│   ├── my.ini                         # 运行时生成
│   └── README.txt
├── jre/                               # Java 运行环境（⚠️ 不要修改）
│   ├── bin/
│   └── lib/
└── logs/                              # 应用日志
    ├── startup-YYYYMMDD.log
    └── upgrade.log

用户数据目录（首次运行自动创建）：
X:\NPQS9100_Data\                      (X 是应用所在盘符)
├── logs/                              # Spring Boot 日志
├── template/                          # 报告模板
├── report/                            # 生成的报告
└── data/                              # 应用数据

七、用户关心的文件（重要！）⭐

📌 可以使用的工具

文件	功能	使用场景
NPQS9100.exe	主程序	日常启动
NPQS9100-启动器.bat	管理员启动器	首次运行或权限问题时
upgrade.bat	升级工具	收到升级包时使用
rollback.bat	回滚工具	升级后出问题时使用
uninstall-mysql-service.bat	MySQL 服务卸载	完全卸载应用时使用
使用说明.txt	使用手册	遇到问题时参考
README-升级回滚.txt	升级说明	升级前阅读

⚠️ 不要修改的文件/目录

路径	说明	误修改后果
resources/	应用核心代码	应用无法启动
scripts/	启动管理脚本	启动流程失败
jre/	Java 运行环境	Java 服务无法启动
mysql/bin/	MySQL 可执行文件	数据库无法启动
mysql/my.ini	MySQL 配置	运行时自动生成，手动修改会被覆盖

📂 需要保护的数据

路径	说明	备份建议
mysql/data/	数据库数据	⚠️ 定期备份！
backup/	升级备份	自动管理，无需手动操作
X:\NPQS9100_Data/	用户数据目录	包含日志、模板、报告

二、打包指南

🏗️ 打包步骤

步骤 1：清理并打包

cd build
clean-and-build.bat

打包过程：

停止 NPQS9100 进程
删除 out 目录
构建前端代码（Vue 3）
编译 Electron 主进程代码
复制 MySQL、JRE、Java 资源
生成 win-unpacked 绿色版目录

等待时间：约 5-15 分钟

步骤 2：测试运行

cd out\win-unpacked
NPQS9100.exe

观察：

✅ Loading 界面正常显示（不在任务栏显示）
✅ 启动进度正常更新（9个步骤）
✅ MySQL 自动启动
✅ Spring Boot 连接成功
✅ 顺利进入主界面

步骤 3：压缩发布包

cd out
Compress-Archive -Path win-unpacked -DestinationPath "NPQS9100-v1.0.0-绿色版.zip" -Force

压缩后大小：约 350-450 MB

三、启动流程

🔄 完整启动流程

用户解压 zip 并双击 NPQS9100.exe
    ↓
显示 Loading 界面（不在任务栏显示）
    ↓
[0%] 正在初始化应用...
    ↓
[15%] 检测 MySQL 端口 (3306 → 3307 → ...)
    ├─ 找到可用端口（如 3307）
    ↓
[30%] 启动 MySQL 数据库（端口 3307）
    ├─ 首次运行：自动初始化数据库
    ├─ 自动设置 root 密码：njcnpqs
    ├─ 自动授权 127.0.0.1 访问
    ↓
[45%] 等待 MySQL 就绪
    ├─ 监听端口是否打开
    ├─ 超时时间：30 秒
    ↓
[60%] 检测 Java 端口 (18092 → 18093 → ...)
    ├─ 找到可用端口（如 18093）
    ↓
[70%] 检测应用所在盘符并生成配置文件
    ├─ MySQL 连接：localhost:3307
    ├─ MySQL 密码：njcnpqs  ⭐ 自动写入
    ├─ Java 端口：18093
    ├─ 数据路径：C:\NPQS9100_Data\
    ├─ 创建所有必要目录（logs、template、report、data）
    ↓
[80%] 启动 Spring Boot 后端
    ├─ 使用内置 JRE 8
    ├─ 加载生成的配置文件
    ├─ 连接 MySQL 数据库
    ↓
[90%] 等待 Spring Boot 就绪
    ├─ 监听 18093 端口
    ├─ 超时时间：60 秒
    ↓
[100%] 启动完成！
    ├─ 等待 1.5 秒显示完成状态
    ↓
销毁 Loading 窗口（使用 destroy() 确保完全释放）
    ↓
显示主应用界面（任务栏只显示1个图标）

预计启动时间：

首次运行：30-45 秒（需初始化 MySQL）
后续启动：15-25 秒

🚪 关闭流程

用户关闭应用（点击X或托盘退出）
    ↓
显示退出确认对话框
    ↓
用户确认退出
    ↓
停止 Spring Boot 进程（通过PID和端口精确清理）
    ↓
停止 MySQL 服务（如果是服务模式）
    ↓
清理资源
    ↓
应用退出

四、升级指南

🎯 升级流程概览

升级流程

1. 双击 upgrade.bat（首次自动创建 upgrade/ 目录）
2. 将升级包放入 upgrade/ 目录
3. 再次运行 upgrade.bat（自动备份 + 升级）
4. 重启应用测试

回滚流程

1. 双击 rollback.bat
2. 自动从 backup/ 恢复旧版本
3. 重启应用

🔧 升级操作步骤

方法 1：使用升级脚本（推荐）⭐

第 1 步：准备升级包

双击 upgrade.bat
脚本自动创建 upgrade/ 文件夹并提示
将升级文件放入 upgrade/ 目录：
- dist/ - 前端升级包（可选）
- entrance.jar - 后端升级包（可选）
再次双击 upgrade.bat 开始升级

第 2 步：自动升级

脚本会自动：

✅ 停止 NPQS9100 进程
✅ 自动备份当前版本到 backup/ 目录
✅ 备份数据库到 mysql/data_backup/
✅ 替换前端文件（如果有）
✅ 替换后端 JAR（如果有）
✅ 记录升级日志到 logs/upgrade.log

第 3 步：重启应用

升级完成后，双击 NPQS9100.exe 启动应用。

方法 2：手动升级

如果升级脚本失败，可以手动操作：

升级前端：

taskkill /F /IM NPQS9100.exe
rmdir /s /q resources\app.asar.unpacked\public\dist
xcopy upgrade\dist resources\app.asar.unpacked\public\dist\ /E /I /Y

升级后端：

taskkill /F /IM NPQS9100.exe
copy /Y upgrade\entrance.jar resources\extraResources\java\entrance.jar

🔄 回滚操作

方法 1：使用回滚脚本（推荐）⭐

如果升级后出现问题，直接双击 rollback.bat：

脚本会自动：

✅ 停止 NPQS9100
✅ 恢复前端（从 backup/dist/）
✅ 恢复后端（从 backup/entrance.jar）
✅ 询问是否恢复数据库（⚠️ 会丢失升级后的数据）

方法 2：手动回滚

# 恢复前端
rmdir /s /q resources\app.asar.unpacked\public\dist
xcopy backup\dist resources\app.asar.unpacked\public\dist\ /E /I /Y

# 恢复后端
copy /Y backup\entrance.jar resources\extraResources\java\entrance.jar

# 恢复数据库（⚠️ 谨慎！）
rmdir /s /q mysql\data
xcopy mysql\data_backup mysql\data\ /E /I /Y

📋 升级清单

升级类型	升级包来源	客户放置位置	最终替换位置
前端	`out/win-unpacked/resources/app.asar` + `app.asar.unpacked/`	`upgrade/app.asar` + `upgrade/app.asar.unpacked/`	`resources/app.asar` + `resources/app.asar.unpacked/`
后端	`out/win-unpacked/resources/extraResources/java/entrance.jar`	`upgrade/entrance.jar`	`resources/extraResources/java/entrance.jar`
数据库	⚠️ 不升级，自动保留	-	`mysql/data/`

🛠️ 开发者升级流程（完整版）

前端升级完整流程

# ============================================
# 开发侧操作
# ============================================

# 1️⃣ 修改前端代码
# 编辑 frontend/src/ 下的任何文件

# 2️⃣ 如需修改配置（可选）
# 编辑 frontend/.env
VITE_API_URL=http://192.168.1.100:18092  # 修改 API 地址

# 3️⃣ 构建前端
npm run build-frontend

# 4️⃣ 打包应用
npm run build-w
# 输出: out/win-unpacked/

# 5️⃣ 准备升级包
# 从 out/win-unpacked/resources/ 复制以下文件：
#   - app.asar （文件）
#   - app.asar.unpacked/ （整个文件夹）
# 
# 压缩成: NPQS9100-前端-v1.0.1.zip

# 6️⃣ 发给客户


# ============================================
# 客户侧操作
# ============================================

# 1️⃣ 解压升级包
# 解压 NPQS9100-前端-v1.0.1.zip
# 得到:
#   - app.asar
#   - app.asar.unpacked/

# 2️⃣ 复制到升级目录
# 将两个文件都放到：win-unpacked/upgrade/
#   - upgrade/app.asar
#   - upgrade/app.asar.unpacked/

# 3️⃣ 运行升级脚本
# 双击: upgrade.bat

# 4️⃣ 重启应用
# 双击: NPQS9100.exe

后端升级完整流程

# ============================================
# 开发侧操作
# ============================================

# 1️⃣ 获取新的 JAR 文件
# 从后端开发人员获取新版本的 entrance.jar

# 2️⃣ 替换 JAR 文件
# 将新的 entrance.jar 复制到:
# build/extraResources/java/entrance.jar

# 3️⃣ 打包升级包
# 直接压缩 entrance.jar 文件
# 重命名为: NPQS9100-后端-v1.0.1.zip

# 4️⃣ 发给客户
# 发送 NPQS9100-后端-v1.0.1.zip


# ============================================
# 客户侧操作
# ============================================

# 1️⃣ 解压升级包
# 解压 NPQS9100-后端-v1.0.1.zip
# 得到 entrance.jar 文件

# 2️⃣ 复制到升级目录
# 将 entrance.jar 复制到:
# win-unpacked/upgrade/entrance.jar

# 3️⃣ 运行升级脚本
# 双击: upgrade.bat

# 4️⃣ 重启应用
# 双击: NPQS9100.exe

前后端同时升级

# 开发侧：准备升级包
NPQS9100-升级-v1.1.0.zip
├── app.asar              # 前端升级包（文件）
├── app.asar.unpacked/    # 前端升级包（文件夹）
└── entrance.jar          # 后端升级包

# 客户侧：复制到
win-unpacked/upgrade/
├── app.asar
├── app.asar.unpacked/
└── entrance.jar

# 运行 upgrade.bat 即可一次性升级前后端

五、测试清单

✅ 打包验证

out/win-unpacked 目录存在
目录大小约 650-800 MB
NPQS9100.exe 存在
NPQS9100-启动器.bat 存在
upgrade.bat 存在
rollback.bat 存在
uninstall-mysql-service.bat 存在
使用说明.txt 存在
README-升级回滚.txt 存在
mysql/ 目录完整
jre/ 目录完整

✅ 基础功能测试

双击 NPQS9100.exe 能正常启动
Loading 界面正常显示
Loading 窗口不在任务栏显示 ⭐
进度条流畅更新（0% → 100%）
状态文字正确显示
主界面正常显示
任务栏只有1个窗口预览 ⭐

✅ 端口检测测试

手动占用 3306，应用自动使用 3307
手动占用 18092，应用自动使用 18093
Loading 界面显示检测到的端口号
日志中显示正确的端口信息

✅ MySQL 测试

MySQL 自动启动成功
首次运行自动初始化数据库 ⭐
可以用 Navicat 连接（密码：njcnpqs）
可以从 127.0.0.1 连接（不报 1130 错误）⭐
数据库操作正常
关闭应用后 MySQL 自动停止

✅ Spring Boot 测试

后端服务自动启动
能连接到 MySQL（不报密码错误） ⭐
日志无错误："HikariPool-1 - Start completed"
API 接口正常响应
关闭应用后 Java 进程停止

✅ 配置生成测试

application.yml 自动生成
MySQL 密码正确写入（njcnpqs） ⭐
MySQL 端口正确
Java 端口正确
数据路径正确（对应盘符）

✅ 数据目录测试

数据目录在正确的盘符下创建
所有子目录都自动创建
配置文件路径正确
日志文件正常写入

✅ 便携性测试

可以解压到任意目录运行
可以移动到其他目录运行
可以在不同电脑上运行
可以在不同盘符上运行（C/D/E...）
删除目录即可完全卸载
压缩成 zip 后用户可正常解压使用 ⭐

✅ 升级回滚测试

upgrade.bat 首次运行自动创建 upgrade/ 目录
upgrade.bat 检测到升级文件后正常升级
升级前自动备份到 backup/ 目录
升级后应用正常运行
升级后数据库数据保留
rollback.bat 能正确回滚前端
rollback.bat 能正确回滚后端
回滚后应用恢复正常

✅ 性能测试

首次启动 < 45 秒
后续启动 < 30 秒
Loading 界面流畅无卡顿
内存占用合理（< 1GB）
CPU 占用正常

✅ 错误处理测试

端口全部占用时显示友好错误
MySQL 启动失败时显示错误信息
Spring Boot 启动失败时不崩溃
升级失败时自动回滚
托盘图标显示正常
退出确认对话框正常工作

六、常见问题

Q1: Loading 界面一直卡在某个步骤？

A: 查看日志定位问题：

C:\Users\[用户名]\AppData\Roaming\NQPS9100\logs\
├── 9100-YYYYMMDD.log          # 应用日志
├── 9100-core-YYYYMMDD.log     # 核心日志
└── 9100-error-YYYYMMDD.log    # 错误日志

常见原因：

MySQL 启动失败 → 检查端口是否可用
Java 启动失败 → 检查 JRE 是否完整
配置生成失败 → 检查磁盘权限

Q2: 显示"无法找到可用端口"错误？

检查是否有大量端口被占用
尝试关闭其他占用端口的程序
或修改起始端口（见开发者指南）

Q3: MySQL 连接失败或提示 1130 错误？

确认 MySQL 已启动（任务管理器查看 mysqld.exe）
确认端口正确（看 Loading 界面显示的端口）
确认密码正确（njcnpqs，已自动配置）
检查是否有杀毒软件拦截
如有问题，重启应用即可（MySQL 会自动重新配置）

Q4: 后端 API 无法访问？

确认 Spring Boot 已启动
确认端口正确（看 Loading 界面）
检查防火墙设置

Q5: 打包后体积太大？

A: 预期体积：

解压后：650-800 MB
压缩后 (zip)：350-450 MB

主要组成：

应用本体：~150 MB
MySQL 8.0：~400 MB
JRE 8：~100 MB

优化建议：

考虑使用 7z 格式（压缩率更高）
可以精简 MySQL 的不必要组件

Q6: 任务栏显示2个窗口预览？

A: 已修复！现在 Loading 窗口使用 skipTaskbar: true，不会在任务栏显示。

Q7: 升级后前端显示旧版本？

A: 清除浏览器缓存，或强制刷新（Ctrl + F5）

Q8: 升级后数据丢失？

A: 检查 mysql/data/ 目录是否完整，如有备份，从 mysql/data_backup/ 恢复

Q9: 升级脚本报错？

A：

检查 upgrade 文件夹路径是否正确
手动执行升级步骤
查看 logs/upgrade.log 日志

Q10: 回滚后还是有问题？

A：

检查 backup/ 目录是否有备份文件
查看 backup/version.txt 确认备份版本
手动执行回滚步骤（参考本文档）

Q11: 多次升级后，backup 目录的内容是什么版本？

A: backup/ 目录保存的是最后一次升级前的版本（每次升级都会覆盖）

Q12: 点击 X 关闭后，Java 进程还在运行？

A: 已修复！现在使用精确的进程清理机制：

通过 PID 清理（如果有进程引用）
通过端口号清理（精确定位）
不会误杀 IDEA 等其他 Java 进程 ⭐

Q13: 如何修改 API 或 WebSocket 地址？

修改 frontend/.env 文件中的 VITE_API_URL
重新构建前端：npm run build-frontend
将 public/dist/ 打包为升级包
使用 upgrade.bat 升级

示例：

# frontend/.env
VITE_API_URL=http://192.168.1.100:18092

注意：

配置修改需要重新打包前端
使用升级机制保证数据安全

Q14: MySQL 服务如何卸载？

A: 方法 1：使用卸载脚本（推荐）

双击: uninstall-mysql-service.bat

方法 2：手动卸载

# 停止服务
net stop mysql9100

# 删除服务
sc delete mysql9100

注意：

卸载服务不会删除数据库数据
数据保存在 mysql/data/ 目录
下次启动应用会重新安装服务

📚 相关文档

用户文档（随应用发布）：

使用说明.txt - 用户使用手册
README-升级回滚.txt - 简明升级说明

开发者文档（doc/ 目录）：

doc/NPQS-9100绿色包完整指南.md - 本文档（完整指南）
doc/打包前检查清单.md - 逐项检查
doc/管理员权限说明.md - 权限问题处理
doc/MySQL服务化方案说明.md - MySQL 服务管理

📊 技术架构

核心模块

scripts/port-checker.js - 端口检测工具
scripts/startup-manager.js - 启动状态管理
scripts/config-generator.js - 配置文件生成
scripts/mysql-service-manager.js - MySQL 服务管理器
scripts/java-runner.js - Java 运行器
scripts/log-window-manager.js - 日志窗口管理
electron/preload/lifecycle.js - 生命周期管理
public/html/loading.html - Loading 界面

启动流程架构

lifecycle.js (入口)
    ↓ 创建
StartupManager (显示 Loading)
    ↓ 调用
PortChecker (检测端口)
    ↓ 调用
MySQLServiceManager (管理 MySQL 服务)
    ↓ 调用
ConfigGenerator (生成配置)
    ↓ 调用
JavaRunner (启动 Spring Boot)

🎉 最新改进

用户体验提升

✅ 任务栏只显示1个图标 - Loading 窗口不在任务栏显示
✅ 纯绿色版 - 只生成 win-unpacked 目录，压缩成 zip 即可发布
✅ 一键解压即用 - 用户解压后双击即可运行
✅ 热更新机制 - 前后端可独立升级，支持一键回滚

技术改进

✅ MySQL 密码自动配置 - 配置生成器自动写入密码
✅ 权限自动授权 - 支持 localhost 和 127.0.0.1 访问
✅ MySQL 服务化 - 使用 Windows 服务管理，开机自启
✅ 窗口管理优化 - 使用 destroy() 确保窗口完全释放
✅ 精确进程清理 - 不会误杀其他 Java 进程
✅ 自动备份机制 - 升级前自动备份，支持回滚
✅ 热更新机制 - 前后端独立升级，无需重装

文档完善

✅ 使用说明.txt - 为用户提供详细的使用指南
✅ README-升级回滚.txt - 简明升级操作说明
✅ 完整指南 - 打包、启动、升级三合一文档

📞 技术支持

如遇问题，请联系技术支持并提供：

应用版本号
错误日志（logs/ 目录）
操作步骤截图

文档更新时间: 2025-10-23
南京灿能电力自动化股份有限公司

22 KiB Raw Blame History Unescape Escape