875 lines
22 KiB
Markdown
875 lines
22 KiB
Markdown
# 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：清理并打包**
|
||
|
||
```bash
|
||
cd build
|
||
clean-and-build.bat
|
||
```
|
||
|
||
**打包过程**：
|
||
1. 停止 NPQS9100 进程
|
||
2. 删除 out 目录
|
||
3. 构建前端代码（Vue 3）
|
||
4. 编译 Electron 主进程代码
|
||
5. 复制 MySQL、JRE、Java 资源
|
||
6. 生成 win-unpacked 绿色版目录
|
||
|
||
**等待时间**：约 5-15 分钟
|
||
|
||
---
|
||
|
||
#### **步骤 2：测试运行**
|
||
|
||
```bash
|
||
cd out\win-unpacked
|
||
NPQS9100.exe
|
||
```
|
||
|
||
**观察**：
|
||
- ✅ Loading 界面正常显示（不在任务栏显示）
|
||
- ✅ 启动进度正常更新（9个步骤）
|
||
- ✅ MySQL 自动启动
|
||
- ✅ Spring Boot 连接成功
|
||
- ✅ 顺利进入主界面
|
||
|
||
---
|
||
|
||
#### **步骤 3：压缩发布包**
|
||
|
||
```powershell
|
||
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 步：准备升级包**
|
||
|
||
1. 双击 `upgrade.bat`
|
||
2. 脚本自动创建 `upgrade/` 文件夹并提示
|
||
3. 将升级文件放入 `upgrade/` 目录：
|
||
- `dist/` - 前端升级包（可选）
|
||
- `entrance.jar` - 后端升级包（可选）
|
||
4. 再次双击 `upgrade.bat` 开始升级
|
||
|
||
**第 2 步：自动升级**
|
||
|
||
脚本会自动：
|
||
- ✅ 停止 NPQS9100 进程
|
||
- ✅ **自动备份当前版本到 `backup/` 目录**
|
||
- ✅ 备份数据库到 `mysql/data_backup/`
|
||
- ✅ 替换前端文件（如果有）
|
||
- ✅ 替换后端 JAR（如果有）
|
||
- ✅ 记录升级日志到 `logs/upgrade.log`
|
||
|
||
**第 3 步：重启应用**
|
||
|
||
升级完成后，双击 `NPQS9100.exe` 启动应用。
|
||
|
||
---
|
||
|
||
#### **方法 2：手动升级**
|
||
|
||
如果升级脚本失败，可以手动操作：
|
||
|
||
**升级前端**：
|
||
```batch
|
||
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
|
||
```
|
||
|
||
**升级后端**：
|
||
```batch
|
||
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：手动回滚**
|
||
|
||
```batch
|
||
# 恢复前端
|
||
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/` |
|
||
|
||
---
|
||
|
||
### 🛠️ 开发者升级流程（完整版）
|
||
|
||
#### **前端升级完整流程**
|
||
|
||
```bash
|
||
# ============================================
|
||
# 开发侧操作
|
||
# ============================================
|
||
|
||
# 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
|
||
```
|
||
|
||
#### **后端升级完整流程**
|
||
|
||
```bash
|
||
# ============================================
|
||
# 开发侧操作
|
||
# ============================================
|
||
|
||
# 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
|
||
```
|
||
|
||
#### **前后端同时升级**
|
||
|
||
```bash
|
||
# 开发侧：准备升级包
|
||
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: 显示"无法找到可用端口"错误？
|
||
|
||
**A**:
|
||
- 检查是否有大量端口被占用
|
||
- 尝试关闭其他占用端口的程序
|
||
- 或修改起始端口（见开发者指南）
|
||
|
||
---
|
||
|
||
### Q3: MySQL 连接失败或提示 1130 错误？
|
||
|
||
**A**:
|
||
- 确认 MySQL 已启动（任务管理器查看 mysqld.exe）
|
||
- 确认端口正确（看 Loading 界面显示的端口）
|
||
- 确认密码正确（njcnpqs，已自动配置）
|
||
- 检查是否有杀毒软件拦截
|
||
- 如有问题，重启应用即可（MySQL 会自动重新配置）
|
||
|
||
---
|
||
|
||
### Q4: 后端 API 无法访问？
|
||
|
||
**A**:
|
||
- 确认 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**：
|
||
1. 检查 `upgrade` 文件夹路径是否正确
|
||
2. 手动执行升级步骤
|
||
3. 查看 `logs/upgrade.log` 日志
|
||
|
||
---
|
||
|
||
### Q10: 回滚后还是有问题？
|
||
|
||
**A**：
|
||
1. 检查 `backup/` 目录是否有备份文件
|
||
2. 查看 `backup/version.txt` 确认备份版本
|
||
3. 手动执行回滚步骤（参考本文档）
|
||
|
||
---
|
||
|
||
### Q11: 多次升级后，backup 目录的内容是什么版本？
|
||
|
||
**A**: `backup/` 目录保存的是**最后一次升级前**的版本（每次升级都会覆盖）
|
||
|
||
---
|
||
|
||
### Q12: 点击 X 关闭后，Java 进程还在运行？
|
||
|
||
**A**: 已修复！现在使用精确的进程清理机制：
|
||
- 通过 PID 清理（如果有进程引用）
|
||
- 通过端口号清理（精确定位）
|
||
- **不会误杀 IDEA 等其他 Java 进程** ⭐
|
||
|
||
---
|
||
|
||
### Q13: 如何修改 API 或 WebSocket 地址？
|
||
|
||
**A**:
|
||
1. 修改 `frontend/.env` 文件中的 `VITE_API_URL`
|
||
2. 重新构建前端：`npm run build-frontend`
|
||
3. 将 `public/dist/` 打包为升级包
|
||
4. 使用 `upgrade.bat` 升级
|
||
|
||
**示例**：
|
||
```env
|
||
# frontend/.env
|
||
VITE_API_URL=http://192.168.1.100:18092
|
||
```
|
||
|
||
**注意**：
|
||
- 配置修改需要重新打包前端
|
||
- 使用升级机制保证数据安全
|
||
|
||
---
|
||
|
||
### Q14: MySQL 服务如何卸载？
|
||
|
||
**A**:
|
||
**方法 1：使用卸载脚本（推荐）**
|
||
```batch
|
||
双击: uninstall-mysql-service.bat
|
||
```
|
||
|
||
**方法 2：手动卸载**
|
||
```batch
|
||
# 停止服务
|
||
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*
|
||
*南京灿能电力自动化股份有限公司*
|
||
|