幻的小屋

【AI生成】HomeInventory 项目DEPLOYMENT

蛋蛋 2026年04月23日 3 0

DEPLOYMENT

1. 文档说明

本文档用于说明 HomeInventory 项目的打包、交付、部署与运行流程。

当前前提：

  • 项目当前尚未在本机具备 Docker 环境
  • 需要先明确如何完成项目打包
  • 需要为未来在 Manjaro 上以 Docker 方式部署做好准备
  • 同时保留非 Docker 模式下的运行方案，便于联调和验证

本文档包含两类方案：

  1. 无 Docker 环境时的打包方案
  2. 未来在 Manjaro 上的部署方案
    • Jar 部署
    • Docker 部署

2. 目标说明

本项目最终希望达到以下交付效果之一：

目标 A：Jar 包部署

将项目打包为一个可运行的 Spring Boot Jar 包，在目标机器上通过 Java 直接运行。

目标 B：Docker 部署

将项目构建为 Docker 镜像，并在 Manjaro 上通过 Docker / Docker Compose 启动。

当前建议

由于当前没有 Docker 环境，建议先完成：

  1. 项目源码校验
  2. Maven 打包校验
  3. Jar 运行校验
  4. 再准备 Docker 化文件
  5. 最后在 Manjaro 上进行 Docker 部署

3. 部署方式总览

方式 当前是否可做 适用场景 说明
Maven 打包 可准备 本地/CI 构建 生成 jar
Jar 运行 可准备 无 Docker 环境测试 直接运行 Spring Boot
Docker 镜像构建 当前不可执行 Docker 部署 需未来在有 Docker 环境时执行
Docker Compose 部署 当前不可执行 Manjaro 生产/测试部署 推荐最终方案

4. 当前无 Docker 环境时的建议流程

当前没有 Docker 环境时，建议按下面顺序推进：

第一步：确认项目满足可打包条件

需要确认以下内容：

  • pom.xml 完整且可用
  • 存在 Spring Boot 主启动类
  • 依赖可正常下载
  • application.yml 配置完整
  • 数据源配置可外部化
  • schema.sql / data.sql 可执行
  • 安全配置不阻塞启动
  • 项目能够执行 mvn clean package

第二步：打包为 Jar

最终目标是得到：

  • target/*.jar

第三步：在非 Docker 环境下运行 Jar 验证

通过 java -jar 先验证：

  • 应用是否能启动
  • 数据库是否能连接
  • SQL 初始化是否能成功
  • 核心接口是否可访问

第四步：为未来 Docker 部署预留配置

包括：

  • 环境变量配置
  • Dockerfile
  • docker-compose.yml
  • 数据卷与端口规划

5. 打包前检查清单

在执行 Maven 打包前，建议检查以下项目内容。

5.1 必备文件

  • pom.xml
  • src/main/java/.../HomeInventoryApplication.java
  • src/main/resources/application.yml
  • src/main/resources/schema.sql
  • src/main/resources/data.sql

5.2 代码结构检查

  • Controller、Service、Repository 分层完整
  • 实体类与数据库字段基本一致
  • DTO 与 Entity 职责清晰
  • Security 配置存在并可控
  • 全局异常处理存在

5.3 构建配置检查

  • spring-boot-maven-plugin 已配置
  • Java 版本已指定
  • Maven 依赖版本无明显冲突
  • Lombok 等注解处理依赖已补充

5.4 数据库配置检查

  • 数据源地址正确
  • 用户名密码正确
  • 驱动依赖存在
  • SQL 初始化策略明确

6. Maven 打包说明

6.1 环境要求

建议环境：

  • JDK 17 或以上
  • Maven 3.8+
  • 可访问 Maven 中央仓库
  • 数据库环境可选（仅编译通常不依赖数据库）

6.2 常用命令

仅编译

mvn clean compile

打包

mvn clean package

跳过测试打包

mvn clean package -DskipTests

6.3 打包产物

打包成功后，通常会在以下目录生成 jar：

target/

例如：

target/homeinventory-0.0.1-SNAPSHOT.jar

7. 非 Docker 模式运行说明

当前没有 Docker 环境时，可以先使用 Jar 运行。

7.1 运行命令

java -jar target/homeinventory-0.0.1-SNAPSHOT.jar

7.2 指定配置运行

如果希望在启动时指定数据库配置，可通过环境变量或启动参数。

例如：

java \
  -Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/home_inventory?useUnicode=true\&characterEncoding=utf8\&serverTimezone=Asia/Shanghai \
  -Dspring.datasource.username=root \
  -Dspring.datasource.password=root \
  -jar target/homeinventory-0.0.1-SNAPSHOT.jar

7.3 后台运行

在 Linux / Manjaro 环境中：

nohup java -jar target/homeinventory-0.0.1-SNAPSHOT.jar > app.log 2>&1 &

查看日志：

tail -f app.log

查看进程：

ps -ef | grep homeinventory

停止进程：

kill -9 <PID>

8. application.yml 配置建议

为了未来部署更方便，建议数据库配置支持环境变量覆盖。

推荐写法

server:
  port: ${SERVER_PORT:8080}

spring:
  datasource:
    url: ${SPRING_DATASOURCE_URL:jdbc:mysql://localhost:3306/home_inventory?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai}
    username: ${SPRING_DATASOURCE_USERNAME:root}
    password: ${SPRING_DATASOURCE_PASSWORD:root}
    driver-class-name: com.mysql.cj.jdbc.Driver

  jpa:
    hibernate:
      ddl-auto: ${SPRING_JPA_HIBERNATE_DDL_AUTO:update}
    show-sql: ${SPRING_JPA_SHOW_SQL:true}

  sql:
    init:
      mode: ${SPRING_SQL_INIT_MODE:always}

好处

  • 本地运行方便
  • Jar 运行可通过环境变量覆盖
  • Docker 部署时可直接注入变量
  • 无需修改代码即可切换环境

9. 推荐交付物

当前没有 Docker 环境时，建议至少整理以下交付物：

9.1 面向源码交付

适用于未来由目标机器自己构建。

建议交付内容：

  • 完整源码目录
  • README.md
  • DEPLOYMENT.md
  • API_LIST.md
  • DB_DESIGN.md
  • BUSINESS_RULES.md
  • TODO.md

9.2 面向 Jar 交付

适用于目标机器已具备 Java 环境。

建议交付内容：

  • homeinventory-xxx.jar
  • application.yml（可选外置）
  • schema.sql
  • data.sql
  • DEPLOYMENT.md

9.3 面向未来 Docker 交付

适用于后续补充 Docker 环境后使用。

建议交付内容：

  • 完整源码
  • Dockerfile
  • docker-compose.yml
  • .dockerignore
  • 部署文档

10. Jar 部署目录建议

建议在服务器或目标机器上采用如下目录结构：

/home/<user>/homeinventory/
├── app/
│   └── homeinventory.jar
├── config/
│   └── application.yml
├── logs/
│   └── app.log
├── sql/
│   ├── schema.sql
│   └── data.sql
└── scripts/
    ├── start.sh
    ├── stop.sh
    └── status.sh

11. 启停脚本建议

11.1 start.sh

#!/bin/bash

APP_NAME="homeinventory.jar"
BASE_DIR=$(cd "$(dirname "$0")"/..; pwd)
APP_DIR="$BASE_DIR/app"
LOG_DIR="$BASE_DIR/logs"
CONFIG_DIR="$BASE_DIR/config"

mkdir -p "$LOG_DIR"

nohup java \
  -jar "$APP_DIR/$APP_NAME" \
  --spring.config.location="$CONFIG_DIR/application.yml" \
  > "$LOG_DIR/app.log" 2>&1 &

echo "HomeInventory started."

11.2 stop.sh

#!/bin/bash

PID=$(ps -ef | grep homeinventory.jar | grep -v grep | awk '{print $2}')

if [ -z "$PID" ]; then
  echo "HomeInventory is not running."
else
  kill -9 "$PID"
  echo "HomeInventory stopped."
fi

11.3 status.sh

#!/bin/bash

PID=$(ps -ef | grep homeinventory.jar | grep -v grep | awk '{print $2}')

if [ -z "$PID" ]; then
  echo "HomeInventory is not running."
else
  echo "HomeInventory is running. PID=$PID"
fi

11.4 赋权

chmod +x scripts/start.sh
chmod +x scripts/stop.sh
chmod +x scripts/status.sh

12. 未来 Docker 化部署方案说明

虽然当前没有 Docker 环境，但建议提前规划后续部署方式。

12.1 推荐 Docker 部署方式

建议未来采用以下结构：

  • 一个应用容器：homeinventory-app
  • 一个数据库容器：mysql
  • 使用 docker-compose.yml 管理
  • 数据库存储使用 volume 持久化

12.2 推荐容器端口

  • 应用端口：8080
  • MySQL 端口：3306

12.3 推荐环境变量

应用容器建议支持以下变量：

  • SERVER_PORT
  • SPRING_DATASOURCE_URL
  • SPRING_DATASOURCE_USERNAME
  • SPRING_DATASOURCE_PASSWORD
  • SPRING_JPA_HIBERNATE_DDL_AUTO
  • SPRING_SQL_INIT_MODE

13. 未来 Docker 文件准备建议

当前可先准备文档，不执行构建。后续有 Docker 环境时再落地。

13.1 需要准备的文件

  • Dockerfile
  • docker-compose.yml
  • .dockerignore

13.2 Dockerfile 作用

用于将 Spring Boot 项目打成镜像，典型步骤：

  1. 基于 Maven 镜像构建 jar
  2. 基于 JRE 镜像运行 jar

13.3 docker-compose.yml 作用

用于一次性启动：

  • Spring Boot 应用
  • MySQL 数据库

14. Manjaro 部署说明

未来如果目标机器是 Manjaro，部署前建议按以下步骤准备。

14.1 Jar 运行模式

如果先不装 Docker，可以直接安装 Java：

sudo pacman -S jdk17-openjdk

验证：

java -version

运行方式：

java -jar homeinventory.jar

14.2 Docker 模式

未来如果 Manjaro 上启用 Docker，需要安装：

sudo pacman -S docker docker-compose

或：

sudo pacman -S docker docker-compose-plugin

启动服务：

sudo systemctl enable --now docker

将用户加入 docker 组：

sudo usermod -aG docker $USER

重新登录后验证：

docker --version
docker compose version

15. 打包与部署的推荐路线

阶段 1：当前阶段

由于当前无 Docker 环境，建议先完成：

  1. 代码结构检查
  2. Maven 编译检查
  3. Maven 打包
  4. Jar 启动验证
  5. 数据库初始化验证

阶段 2：部署准备阶段

在项目可稳定运行后：

  1. 调整 application.yml
  2. 支持环境变量
  3. 准备 Dockerfile
  4. 准备 docker-compose.yml
  5. 编写 Docker 启动文档

阶段 3：Manjaro Docker 部署阶段

在 Manjaro 上：

  1. 安装 Docker
  2. 拷贝项目
  3. 构建镜像
  4. 启动容器
  5. 验证接口

16. 常见问题

16.1 Maven 打包失败

可能原因：

  • JDK 版本不匹配
  • 依赖下载失败
  • 代码存在编译错误
  • Lombok 未生效
  • Spring Boot 插件配置不完整

16.2 Jar 启动失败

可能原因：

  • 数据源配置错误
  • 数据库未启动
  • 端口冲突
  • SQL 初始化脚本错误
  • Bean 注入失败
  • Security 配置异常

16.3 数据库初始化失败

可能原因：

  • schema.sql 语法与数据库版本不兼容
  • data.sql 与表结构不匹配
  • 执行顺序不正确
  • 用户权限不足

16.4 未来 Docker 启动失败

可能原因：

  • 镜像未构建成功
  • 环境变量未注入
  • 应用无法连接 MySQL
  • 端口映射冲突
  • Compose 文件路径错误

17. 最小可交付建议

在当前没有 Docker 环境的情况下，建议最少输出以下可交付物：

必需

  • README.md
  • DEPLOYMENT.md
  • API_LIST.md
  • BUSINESS_RULES.md
  • DB_DESIGN.md
  • TODO.md

代码层面

  • 完整源码
  • 可用 pom.xml
  • 可用 application.yml
  • 可用 schema.sql
  • 可用 data.sql

构建产物

  • target/homeinventory-xxx.jar（条件允许时生成）

18. 当前结论

当前项目在没有 Docker 环境时，正确的推进方式不是直接做 Docker 安装，而是：

  1. 先确保项目可编译
  2. 先确保项目可打包为 Jar
  3. 先确保 Jar 可运行
  4. 再为未来 Docker 部署补齐容器化文件
  5. 最终在 Manjaro 上用 Docker 模式部署

也就是说，当前最务实的部署路径是：

源码 -> Maven 打包 -> Jar 验证 -> Docker 化准备 -> Manjaro Docker 部署

Last Updated: 2026/04/23 21:46:40
【AI生成】HomeInventory 项目INITIAL_REQUIREMENTS_V2 【AI生成】HomeInventory 项目DB_DESIGN