构建与部署手册 - xych5q/online-shop GitHub Wiki

构建与部署手册

第 1 组 · 在线购物系统　|　负责人：陈星宇（组长/DevOps） 目标：让读者在一台全新的机器上，按本手册从源码构建出可运行的产物并完成部署。

一、环境依赖

依赖 版本要求 获取方式 是否必需
JDK 17 及以上（本项目在 JDK 21 上实测通过） https://adoptium.net/ 必需
Maven 3.9.x（本项目在 3.9.16 上实测通过） https://maven.apache.org/ 必需
Docker 24+ https://www.docker.com/ 仅容器化部署时需要
MySQL — — 不需要，本项目使用 H2 文件库，数据落盘 ./data/，零安装

验证环境：

java -version
mvn -version

二、获取源码

git clone https://github.com/xych5q/online-shop.git
cd online-shop/server          # 后端工程根目录（pom.xml 在此）

三、构建步骤（源码 → 可执行 jar）

cd server

mvn clean          # 清理 target/
mvn compile        # 编译 src/main/java
mvn test           # 执行 JUnit 用例，失败则中断
mvn package        # 打包为可执行 jar

一键等价：cd server && mvn clean package

实测结果（2026-10-07，组长本地执行）：

  • mvn package → BUILD SUCCESS，产出 server/target/online-shop.jar（约 49 MB，含全部依赖的 Spring Boot fat jar）。
  • mvn test → 迭代 1 首版 Tests run: 16；2026-10-13 整改后为 Tests run: 18, Failures: 0, Errors: 0, Skipped: 0（新增 TC-A17 交易中撤销且递补、TC-A18 交易中撤销且队列空恢复在售，见 测试用例清单）。BUILD SUCCESS。

每一步发生了什么（验收会问）：

  1. clean 删除 target/，保证无历史残留。
  2. compile 把 src/main/java 编译为 target/classes 下的 .class。
  3. test 执行 src/test/java 的 JUnit 5 用例（MockMvc 集成流程），失败则构建中断。
  4. package 把 class + src/main/resources（含 static/ 前端页面）+ 依赖打成可执行 jar。
  5. 依赖由 pom.xml 声明，Maven 自动解析，不需要手动拷贝 jar。

四、运行

cd server
java -jar target/online-shop.jar
  • 默认端口 8080；若被占用，加参数 --server.port=8090。
  • 首次启动会自动创建管理员账号并在日志中打印账号密码，形如：已创建卖家账号：admin / xxxxxxxx。
  • 数据持久化在 ./data/ 下的 H2 文件库，重启不丢失。

验证：

地址 预期
http://localhost:8080/index.html 买家端商品详情页，HTTP 200
http://localhost:8080/admin.html 卖家后台登录页，HTTP 200
http://localhost:8080/api/product 返回当前在售商品 JSON

注意：本服务没有 /health 端点，探活请用 /api/product。

跑完全量接口冒烟（44 项断言，脚本自带遗留数据清理，可重复执行）：

# 另开一个终端；建议用独立数据目录起一个干净实例，避免污染开发库
cd server && java -jar target/online-shop.jar --server.port=8090 \
     --spring.datasource.url="jdbc:h2:file:./data-smoke/onlineshop;DB_CLOSE_ON_EXIT=FALSE" \
     --app.upload.dir=./data-smoke/uploads

cd ../test-cases && BASE=http://localhost:8090 bash api-smoke.sh

实测（2026-10-13，在端口 8092 的全新空库实例上整跑）：通过 44 项，失败 0 项。

五、Docker 部署

镜像采用两阶段构建（Maven 打包 + JRE 运行），deploy/Dockerfile 已按 server/ 子目录结构适配：

# 在仓库根目录执行
docker build -f deploy/Dockerfile -t online-shop:0.1 .
docker run -d --name shop -p 8080:8080 online-shop:0.1

# 验证（同上：没有 /health，用 /api/product）
curl -o /dev/null -w '%{http_code}\n' http://localhost:8080/api/product

# 导出镜像作为验收材料
docker save online-shop:0.1 -o dist/online-shop-0.1-iter1.tar

一键（推荐，会把"跑单测 → 构建 → 起容器 → 等就绪 → 冒烟 → 导出 tar"一次做完）：

bash deploy/docker-verify.sh

带数据卷（容器重启数据不丢）：docker compose -f deploy/docker-compose.yml up -d； 重置数据：docker compose -f deploy/docker-compose.yml down -v。

本机没有 Docker 也能做——用 GitHub Actions 在云端构建（.github/workflows/docker-image.yml）：

# 方式 A：打 tag 触发
git tag -a v0.1-iter1 -m "迭代 1 基线" && git push origin v0.1-iter1

# 方式 B：Actions 页面选 “Docker Image” → Run workflow，tag 填 0.1-iter1

工作流会依次跑 JUnit 单测 → 构建镜像 → 推 ghcr.io/xych5q/online-shop:0.1-iter1 → 起容器跑 test-cases/api-smoke.sh（44 项断言）→ docker save 的 tar 挂到 Release 附件。 镜像可见性：2026-10-15 实测核验为 Public（匿名令牌 200 / manifest 200 / 层数据实下 44 MB），任何人可直接 docker pull，无需改设置。 （GHCR 包的可见性跟随其关联仓库：本包由公开仓库 xych5q/online-shop 发布，故为公开；只有私有仓库发布的包才默认私有。）

状态说明（2026-10-15 更新）：Docker 镜像属于 10-15 基线验收五件套之一，已完成，不再有缺口。 ① Dockerfile 两阶段基础镜像统一为 JDK/JRE 21（此前的 17 与 pom 的 java.version=21 不符）； ② 补 .dockerignore 裁剪构建上下文、新增 docker-compose.yml 与 docker-verify.sh； ③ 新增云端构建 workflow，已在 GitHub Actions 真实构建成功（首次 2 分 20 秒；最新 run 38404693560 2 分 8 秒）， 容器起来后跑接口冒烟 44/44 通过； ④ 镜像 ghcr.io/xych5q/online-shop:0.1-iter1 已实测为 Public，任何人可匿名 docker pull（匿名令牌 200、 manifest 200、层数据实下 44 MB）；Release 另附 online-shop-0.1-iter1.tar（371 MB）供离线交付。 本机能否装 Docker：可以。开发者笔记本为 Windows 11 专业版（Build 22631）、固件虚拟化已启用、二级地址转换可用、内存 16 GB、C 盘余 62 GB——Docker Desktop 的硬件与系统前置条件全部满足，装完重启即可本地实跑 deploy/docker-verify.sh。装机前可用上面的云端构建先拿到镜像作为过渡。详见 deploy/部署手册.md 第 6 节实测记录。

六、常见问题

现象 原因 处理
依赖下载超时 默认中央仓库在国内慢 配置阿里云镜像 ~/.m2/settings.xml
测试用例失败 代码或环境问题 查看 target/surefire-reports/
端口被占用 8080 已被其他程序占用 加 --server.port=8090
找不到主类 打包插件未生效 检查 pom.xml 中 spring-boot-maven-plugin

七、相关文档