|
|
# SLMS 四端应用打包工具配置指南
|
|
|
|
|
|
**Smart Library Management System - Multi-Application Package Tools Guide**
|
|
|
|
|
|
本文档提供 SLMS 四端应用（CLI、GUI、Web、Android）打包所需工具的详细安装步骤、配置方法和验证流程。
|
|
|
|
|
|
**四端应用说明**:
|
|
|
- **CLI 应用**: 命令行界面，打包为 JAR
|
|
|
- **GUI 应用**: 图形界面（JavaFX），打包为 JAR/EXE/MSI
|
|
|
- **Web 应用**: Spring Boot Web，打包为 WAR
|
|
|
- **Android 应用**: 移动端，打包为 APK
|
|
|
|
|
|
**相关文档**:
|
|
|
- `SLMS_MultiAPP_Package.xml`: Maven 打包配置（CLI/GUI/Web）
|
|
|
- `ATM流水线.md`: CI/CD 流水线配置文档
|
|
|
- `Jenkinsfile`: Jenkins 自动化构建脚本
|
|
|
|
|
|
---
|
|
|
|
|
|
## 一、CLI 应用打包 (JAR)
|
|
|
|
|
|
### 所需工具
|
|
|
- ✅ JDK 21
|
|
|
- ✅ Maven 3.9+
|
|
|
|
|
|
### 验证命令
|
|
|
```bash
|
|
|
java -version
|
|
|
mvn -version
|
|
|
```
|
|
|
|
|
|
### 测试打包
|
|
|
```bash
|
|
|
mvn clean package -P cli -DskipTests
|
|
|
```
|
|
|
|
|
|
**预期输出**: `target/slms-cli.jar`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 二、GUI 应用打包 (EXE/MSI)
|
|
|
|
|
|
### 所需工具
|
|
|
1. **JDK 21** (包含 jpackage)
|
|
|
2. **WiX Toolset 3.11+** (用于生成 MSI)
|
|
|
|
|
|
### 2.1 安装 WiX Toolset
|
|
|
|
|
|
#### 下载
|
|
|
- 官网: https://wixtoolset.org/releases/
|
|
|
- 推荐版本: WiX Toolset 3.11.2
|
|
|
- 下载文件: `wix311.exe`
|
|
|
|
|
|
#### 安装步骤
|
|
|
1. 运行 `wix311.exe`
|
|
|
2. 选择安装路径: `C:\Program Files (x86)\WiX Toolset v3.11`
|
|
|
3. 完成安装
|
|
|
|
|
|
#### 配置环境变量
|
|
|
```bash
|
|
|
# 添加到系统 PATH
|
|
|
C:\Program Files (x86)\WiX Toolset v3.11\bin
|
|
|
```
|
|
|
|
|
|
**重启命令行窗口**使环境变量生效。
|
|
|
|
|
|
### 2.2 验证安装
|
|
|
|
|
|
```bash
|
|
|
# 验证 jpackage
|
|
|
jpackage --version
|
|
|
|
|
|
# 验证 WiX
|
|
|
candle.exe -?
|
|
|
light.exe -?
|
|
|
```
|
|
|
|
|
|
### 2.3 测试打包
|
|
|
|
|
|
#### 打包为 EXE
|
|
|
```bash
|
|
|
# 先打包 JAR
|
|
|
mvn clean package -P gui -DskipTests
|
|
|
|
|
|
# 使用 jpackage 打包为 EXE
|
|
|
jpackage --input target ^
|
|
|
--name SLMS-GUI ^
|
|
|
--main-jar slms-gui.jar ^
|
|
|
--type exe ^
|
|
|
--win-console ^
|
|
|
--dest target
|
|
|
```
|
|
|
|
|
|
**预期输出**: `target/SLMS-GUI.exe`
|
|
|
|
|
|
#### 打包为 MSI
|
|
|
```bash
|
|
|
jpackage --input target ^
|
|
|
--name SLMS-GUI ^
|
|
|
--main-jar slms-gui.jar ^
|
|
|
--type msi ^
|
|
|
--win-console ^
|
|
|
--dest target
|
|
|
```
|
|
|
|
|
|
**预期输出**: `target/SLMS-GUI.msi`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 三、Web 应用打包 (WAR)
|
|
|
|
|
|
### 所需工具
|
|
|
- ✅ JDK 21
|
|
|
- ✅ Maven 3.9+
|
|
|
- ✅ Spring Boot (已在 pom.xml 中配置)
|
|
|
|
|
|
### 验证命令
|
|
|
```bash
|
|
|
mvn -version
|
|
|
```
|
|
|
|
|
|
### 测试打包
|
|
|
```bash
|
|
|
mvn clean package -P web -DskipTests
|
|
|
```
|
|
|
|
|
|
**预期输出**: `target/slms-web.war`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 四、Android 应用打包 (APK)
|
|
|
|
|
|
### 所需工具
|
|
|
1. **JDK 21**
|
|
|
2. **Android SDK**
|
|
|
3. **Gradle 8.5+**
|
|
|
|
|
|
### 4.1 安装 Android SDK
|
|
|
|
|
|
#### 方法一：通过 Android Studio
|
|
|
1. 下载 Android Studio: https://developer.android.com/studio
|
|
|
2. 安装并打开 Android Studio
|
|
|
3. 通过 SDK Manager 安装:
|
|
|
- Android SDK Platform 34
|
|
|
- Android SDK Build-Tools 34.0.0
|
|
|
- Android SDK Command-line Tools
|
|
|
|
|
|
#### 方法二：命令行工具
|
|
|
1. 下载 Command Line Tools: https://developer.android.com/studio#command-tools
|
|
|
2. 解压到: `D:\development\Android\cmdline-tools`
|
|
|
3. 使用 sdkmanager 安装组件:
|
|
|
```bash
|
|
|
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"
|
|
|
```
|
|
|
|
|
|
### 4.2 配置环境变量
|
|
|
|
|
|
```bash
|
|
|
# 设置 ANDROID_HOME
|
|
|
ANDROID_HOME=D:\development\Android
|
|
|
|
|
|
# 添加到 PATH
|
|
|
%ANDROID_HOME%\platform-tools
|
|
|
%ANDROID_HOME%\cmdline-tools\latest\bin
|
|
|
```
|
|
|
|
|
|
### 4.3 生成签名密钥
|
|
|
|
|
|
```bash
|
|
|
# 创建密钥存储目录
|
|
|
mkdir android\keystore
|
|
|
|
|
|
# 生成签名密钥
|
|
|
keytool -genkey -v ^
|
|
|
-keystore android\keystore\slms-release.jks ^
|
|
|
-keyalg RSA ^
|
|
|
-keysize 2048 ^
|
|
|
-validity 10000 ^
|
|
|
-alias slms-key
|
|
|
```
|
|
|
|
|
|
**记录密钥信息**:
|
|
|
- Keystore 密码: `your-store-password`
|
|
|
- Key 别名: `slms-key`
|
|
|
- Key 密码: `your-key-password`
|
|
|
|
|
|
### 4.4 配置 Gradle 签名
|
|
|
|
|
|
编辑 `android/build.gradle`:
|
|
|
|
|
|
```gradle
|
|
|
android {
|
|
|
signingConfigs {
|
|
|
release {
|
|
|
storeFile file("keystore/slms-release.jks")
|
|
|
storePassword "your-store-password"
|
|
|
keyAlias "slms-key"
|
|
|
keyPassword "your-key-password"
|
|
|
}
|
|
|
}
|
|
|
|
|
|
buildTypes {
|
|
|
release {
|
|
|
signingConfig signingConfigs.release
|
|
|
minifyEnabled false
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 4.5 验证安装
|
|
|
|
|
|
```bash
|
|
|
# 验证 Android SDK
|
|
|
echo %ANDROID_HOME%
|
|
|
|
|
|
# 验证 Gradle
|
|
|
cd android
|
|
|
gradlew --version
|
|
|
```
|
|
|
|
|
|
### 4.6 测试打包
|
|
|
|
|
|
```bash
|
|
|
cd android
|
|
|
|
|
|
# 打包 Debug 版本
|
|
|
gradlew assembleDebug
|
|
|
|
|
|
# 打包 Release 版本（需要签名）
|
|
|
gradlew assembleRelease
|
|
|
```
|
|
|
|
|
|
**预期输出**:
|
|
|
- Debug: `android/build/outputs/apk/debug/android-debug.apk`
|
|
|
- Release: `android/build/outputs/apk/release/android-release.apk`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 五、Jenkins 环境配置
|
|
|
|
|
|
### 5.1 配置全局环境变量
|
|
|
|
|
|
1. 进入 Jenkins: `http://localhost:8084`
|
|
|
2. `Manage Jenkins` → `Configure System`
|
|
|
3. 找到 `Global properties`
|
|
|
4. 勾选 `Environment variables`
|
|
|
5. 添加以下变量:
|
|
|
|
|
|
```
|
|
|
JAVA_HOME = E:\2025-2026\GitAIOps\jdk
|
|
|
ANDROID_HOME = D:\development\Android
|
|
|
WIXSHARP_WIXDIR = C:\Program Files (x86)\WiX Toolset v3.11\bin
|
|
|
```
|
|
|
|
|
|
### 5.2 创建验证 Pipeline
|
|
|
|
|
|
在 Jenkins 中创建测试任务验证所有工具：
|
|
|
|
|
|
```groovy
|
|
|
pipeline {
|
|
|
agent any
|
|
|
|
|
|
stages {
|
|
|
stage('验证打包工具') {
|
|
|
steps {
|
|
|
bat '''
|
|
|
echo ========== 验证 Java ==========
|
|
|
java -version
|
|
|
javac -version
|
|
|
|
|
|
echo ========== 验证 Maven ==========
|
|
|
mvn -version
|
|
|
|
|
|
echo ========== 验证 jpackage ==========
|
|
|
jpackage --version
|
|
|
|
|
|
echo ========== 验证 WiX Toolset ==========
|
|
|
candle.exe -?
|
|
|
light.exe -?
|
|
|
|
|
|
echo ========== 验证 Gradle ==========
|
|
|
cd android
|
|
|
gradlew --version
|
|
|
cd ..
|
|
|
|
|
|
echo ========== 验证 Android SDK ==========
|
|
|
echo %ANDROID_HOME%
|
|
|
dir "%ANDROID_HOME%"
|
|
|
|
|
|
echo ========== 所有工具验证完成 ==========
|
|
|
'''
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 六、完整验证清单
|
|
|
|
|
|
### 验证步骤
|
|
|
|
|
|
- [ ] **JDK 21 已安装**
|
|
|
```bash
|
|
|
java -version
|
|
|
# 输出: openjdk version "21.x.x"
|
|
|
```
|
|
|
|
|
|
- [ ] **Maven 已安装**
|
|
|
```bash
|
|
|
mvn -version
|
|
|
# 输出: Apache Maven 3.9.x
|
|
|
```
|
|
|
|
|
|
- [ ] **jpackage 可用**
|
|
|
```bash
|
|
|
jpackage --version
|
|
|
# 输出: 21.x.x
|
|
|
```
|
|
|
|
|
|
- [ ] **WiX Toolset 已安装**
|
|
|
```bash
|
|
|
candle.exe -?
|
|
|
light.exe -?
|
|
|
# 输出: WiX 工具帮助信息
|
|
|
```
|
|
|
|
|
|
- [ ] **Android SDK 已配置**
|
|
|
```bash
|
|
|
echo %ANDROID_HOME%
|
|
|
# 输出: D:\development\Android
|
|
|
```
|
|
|
|
|
|
- [ ] **Gradle 可用**
|
|
|
```bash
|
|
|
cd android
|
|
|
gradlew --version
|
|
|
# 输出: Gradle 8.5
|
|
|
```
|
|
|
|
|
|
- [ ] **Android 签名密钥已生成**
|
|
|
```bash
|
|
|
dir android\keystore\slms-release.jks
|
|
|
# 文件存在
|
|
|
```
|
|
|
|
|
|
- [ ] **Jenkins 环境变量已配置**
|
|
|
- JAVA_HOME
|
|
|
- ANDROID_HOME
|
|
|
- WIXSHARP_WIXDIR
|
|
|
|
|
|
- [ ] **本地测试打包成功**
|
|
|
- CLI JAR: ✅
|
|
|
- GUI JAR: ✅
|
|
|
- GUI EXE: ✅
|
|
|
- Web WAR: ✅
|
|
|
- Android APK: ✅
|
|
|
|
|
|
---
|
|
|
|
|
|
## 七、常见问题
|
|
|
|
|
|
### 问题 1: jpackage 命令找不到
|
|
|
|
|
|
**原因**: JDK 版本低于 14 或 PATH 未配置
|
|
|
|
|
|
**解决**:
|
|
|
```bash
|
|
|
# 确认 JDK 版本
|
|
|
java -version
|
|
|
|
|
|
# 确认 jpackage 路径
|
|
|
where jpackage
|
|
|
|
|
|
# 如果找不到，添加到 PATH
|
|
|
%JAVA_HOME%\bin
|
|
|
```
|
|
|
|
|
|
### 问题 2: WiX 工具找不到
|
|
|
|
|
|
**原因**: WiX 未安装或 PATH 未配置
|
|
|
|
|
|
**解决**:
|
|
|
```bash
|
|
|
# 检查安装路径
|
|
|
dir "C:\Program Files (x86)\WiX Toolset v3.11\bin"
|
|
|
|
|
|
# 添加到 PATH
|
|
|
C:\Program Files (x86)\WiX Toolset v3.11\bin
|
|
|
```
|
|
|
|
|
|
### 问题 3: Android SDK 找不到
|
|
|
|
|
|
**原因**: ANDROID_HOME 未设置
|
|
|
|
|
|
**解决**:
|
|
|
```bash
|
|
|
# 设置环境变量
|
|
|
setx ANDROID_HOME "D:\development\Android"
|
|
|
|
|
|
# 重启命令行窗口
|
|
|
```
|
|
|
|
|
|
### 问题 4: Gradle 构建失败
|
|
|
|
|
|
**原因**: Gradle 版本不兼容或依赖下载失败
|
|
|
|
|
|
**解决**:
|
|
|
```bash
|
|
|
# 清理 Gradle 缓存
|
|
|
cd android
|
|
|
gradlew clean
|
|
|
|
|
|
# 重新构建
|
|
|
gradlew assembleDebug --refresh-dependencies
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 八、下一步
|
|
|
|
|
|
完成所有工具安装和验证后：
|
|
|
|
|
|
1. ✅ 更新 `pom.xml` 添加 profiles 配置
|
|
|
2. ✅ 配置 `android/build.gradle` 签名信息
|
|
|
3. ✅ 提交 `Jenkinsfile` 到仓库
|
|
|
4. ✅ 推送到 Gitea 触发 Jenkins 构建
|
|
|
5. ✅ 查看 Jenkins 构建日志验证四端打包
|
|
|
|
|
|
---
|
|
|
|
|
|
**文档版本**: 1.0
|
|
|
**最后更新**: 2025-11-20
|
|
|
**维护者**: SLMS 开发团队
|
