slms/docs/DEPLOYMENT_GUIDE.md

SLMS 四端应用部署指南

制品下载

从 Jenkins 下载

访问：http://localhost:8084/job/slms/lastSuccessfulBuild/artifact/

从头歌下载

访问：https://bdgit.educoder.net/pu6zrsfoy/CHZU_CS231_SEB_lab/tree/release/artifacts

一、CLI 应用部署 (slms-cli.jar)

运行要求

• Java 21 或更高版本
• 命令行终端

部署步骤

1. 下载制品

   # 从 Jenkins 下载或从 release 分支获取
   slms-cli.jar
   

2. 运行应用

   java -jar slms-cli.jar
   

3. 使用示例

   # 查看帮助
   java -jar slms-cli.jar --help
   
   # 添加图书
   java -jar slms-cli.jar add-book --title "Java编程思想" --author "Bruce Eckel"
   
   # 查询图书
   java -jar slms-cli.jar list-books
   
   # 借阅图书
   java -jar slms-cli.jar borrow --book-id 1 --user "张三"
   

配置文件

创建 application.properties：

# 数据库配置
spring.datasource.url=jdbc:sqlite:library.db
spring.datasource.driver-class-name=org.sqlite.JDBC

# 日志配置
logging.level.root=INFO
logging.file.name=slms-cli.log

---

二、GUI 应用部署 (slms-gui.jar)

运行要求

• Java 21 或更高版本（包含 JavaFX）
• 图形界面环境

部署步骤

1. 下载制品

   slms-gui.jar
   

2. 运行应用

   # Windows
   java -jar slms-gui.jar
   
   # 或双击 slms-gui.jar 文件
   

3. 创建桌面快捷方式（Windows）

   • 右键 slms-gui.jar
   • 发送到 → 桌面快捷方式
   • 右键快捷方式 → 属性
   • 目标："C:\Program Files\Java\jdk-21\bin\javaw.exe" -jar "路径\slms-gui.jar"
   • 图标：可以自定义

配置文件

创建 application.properties（与 JAR 同目录）：

# 数据库配置
spring.datasource.url=jdbc:sqlite:library.db

# GUI 配置
gui.theme=light
gui.language=zh_CN

常见问题

问题：JavaFX 运行时错误

# 解决方案：使用包含 JavaFX 的 JDK
# 或添加 JavaFX 模块
java --module-path /path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.fxml -jar slms-gui.jar

---

三、Web 应用部署 (slms-web.war)

运行要求

• Java 21 或更高版本
• Tomcat 10.x 或 Jetty 11.x

方案 A：使用 Tomcat 部署

1. 安装 Tomcat

# 下载 Tomcat 10.1
https://tomcat.apache.org/download-10.cgi

# 解压到目录
C:\tomcat\apache-tomcat-10.1.x

2. 部署 WAR 文件

# 方法 1：复制到 webapps 目录
copy slms-web.war C:\tomcat\apache-tomcat-10.1.x\webapps\

# 方法 2：使用 Tomcat Manager
# 访问 http://localhost:8080/manager/html
# 上传 slms-web.war

3. 启动 Tomcat

# Windows
C:\tomcat\apache-tomcat-10.1.x\bin\startup.bat

# Linux
/opt/tomcat/bin/startup.sh

4. 访问应用

http://localhost:8080/slms-web/

方案 B：使用内嵌 Tomcat 运行

如果 WAR 包含 Spring Boot，可以直接运行：

java -jar slms-web.war

访问：http://localhost:8080

配置文件

创建 application.properties（放在 Tomcat 的 conf 目录或 WAR 的 WEB-INF/classes）：

# 服务器配置
server.port=8080
server.servlet.context-path=/slms-web

# 数据库配置
spring.datasource.url=jdbc:sqlite:/var/lib/slms/library.db
spring.datasource.driver-class-name=org.sqlite.JDBC

# 日志配置
logging.level.root=INFO
logging.file.name=/var/log/slms/slms-web.log

# 会话配置
server.servlet.session.timeout=30m

生产环境配置

1. 配置数据库连接池

spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000

2. 配置 HTTPS（推荐）

server.ssl.enabled=true
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=your-password
server.ssl.key-store-type=PKCS12

3. 配置反向代理（Nginx）

server {
    listen 80;
    server_name slms.example.com;
    
    location /slms-web/ {
        proxy_pass http://localhost:8080/slms-web/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

监控和维护

查看日志

# Tomcat 日志
tail -f C:\tomcat\apache-tomcat-10.1.x\logs\catalina.out

# 应用日志
tail -f /var/log/slms/slms-web.log

重启应用

# 重启 Tomcat
C:\tomcat\apache-tomcat-10.1.x\bin\shutdown.bat
C:\tomcat\apache-tomcat-10.1.x\bin\startup.bat

---

四、Android 应用部署 (app-debug.apk)

运行要求

• Android 5.0 (API 21) 或更高版本
• 允许安装未知来源应用

部署步骤

1. 下载 APK

# 从 Jenkins 或 release 分支下载
app-debug.apk

2. 安装到手机

方法 A：通过 USB 连接

# 启用 USB 调试
# 设置 → 开发者选项 → USB 调试

# 使用 ADB 安装
adb install app-debug.apk

# 或使用 ADB 无线连接
adb connect 192.168.1.100:5555
adb install app-debug.apk

方法 B：直接安装

1. 将 APK 传输到手机（通过 USB、蓝牙、网络）
2. 在手机上找到 APK 文件
3. 点击安装
4. 允许安装未知来源应用
5. 完成安装

方法 C：通过二维码

1. 将 APK 上传到服务器
2. 生成下载链接的二维码
3. 手机扫码下载安装

配置

应用权限

首次运行时需要授予以下权限：

• 存储权限（读写图书数据）
• 网络权限（同步数据）
• 相机权限（扫描图书条形码）

服务器配置

在应用设置中配置后端服务器：

设置 → 服务器配置
服务器地址: http://your-server:8080/slms-web/api

发布到应用商店

生成签名 APK

# 1. 生成密钥库
keytool -genkey -v -keystore slms-release.keystore -alias slms -keyalg RSA -keysize 2048 -validity 10000

# 2. 签名 APK
jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 -keystore slms-release.keystore app-release-unsigned.apk slms

# 3. 对齐 APK
zipalign -v 4 app-release-unsigned.apk slms-release.apk

上传到应用商店

• Google Play Store
• 华为应用市场
• 小米应用商店
• 应用宝

---

五、数据库初始化

所有应用共享同一个 SQLite 数据库。

自动初始化

首次运行时，应用会自动创建数据库和表结构。

手动初始化

# 运行初始化脚本
java -cp slms-cli.jar com.smartlibrary.InitDatabase

数据库位置

• CLI/GUI: 当前目录下的 library.db
• Web: /var/lib/slms/library.db
• Android: /data/data/com.smartlibrary.android/databases/library.db

备份数据库

# 备份
copy library.db library-backup-20251121.db

# 恢复
copy library-backup-20251121.db library.db

---

六、系统要求总结

应用	最低要求	推荐配置
CLI	Java 21, 512MB RAM	Java 21, 1GB RAM
GUI	Java 21 + JavaFX, 1GB RAM	Java 21, 2GB RAM, 独立显卡
Web	Java 21, Tomcat 10, 2GB RAM	Java 21, Tomcat 10, 4GB RAM, SSD
Android	Android 5.0, 1GB RAM	Android 8.0+, 2GB RAM

---

七、故障排查

CLI/GUI 无法启动

# 检查 Java 版本
java -version

# 查看详细错误
java -jar slms-cli.jar --debug

Web 应用 404 错误

• 检查 WAR 是否正确部署到 webapps
• 检查 Tomcat 是否启动
• 查看 Tomcat 日志

Android 应用闪退

• 检查权限是否授予
• 查看 Logcat 日志
• 检查服务器连接

数据库锁定

# 关闭所有应用
# 删除锁文件
del library.db-journal

---

八、更新升级

自动更新（推荐）

应用内置自动更新功能，检测到新版本时会提示更新。

手动更新

1. 备份数据库
2. 下载新版本制品
3. 替换旧版本
4. 重启应用

版本兼容性

• 向后兼容：新版本可以读取旧版本数据
• 数据迁移：自动执行数据库迁移脚本

---

九、技术支持

• 文档: docs/ 目录
• 问题反馈: Gitea Issues
• CI/CD: Jenkins http://localhost:8084/job/slms
• 代码质量: SonarQube http://localhost:9000/dashboard?id=slms:slms

---

十、快速开始

开发环境

# 1. 克隆代码
git clone http://localhost:3000/gitea/SLMS.git

# 2. 编译项目
cd SLMS
mvn clean package

# 3. 运行 CLI
java -jar target/slms-cli.jar

# 4. 运行 GUI
java -jar target/slms-gui.jar

# 5. 运行 Web
java -jar target/slms-web.war

生产环境

# 1. 从 release 分支下载制品
git clone -b release https://bdgit.educoder.net/pu6zrsfoy/CHZU_CS231_SEB_lab.git

# 2. 部署到服务器
# 按照上述各端部署步骤操作

---

部署完成！享受 SLMS 四端应用带来的便利！ 📚✨