构建过程手册 - xiaochu-dev/online-shopping-group5 GitHub Wiki

在线购物系统 构建过程手册（MVP 基线版）

项目 内容
文档名称 05-构建过程手册
项目名称 在线购物系统（挑战升级）
版本 MVP（第 1 次迭代基线版本）
项目组号 第 5 组
编制人 胡成溯（组长）
编制日期 2026-10-19
文档版本 v1.0
对齐标准 课程 Wiki《系统验收标准》第 3 项「构建」：构建配置文件、构建工具程序、构建过程手册、构建结果文件

文档说明：本手册只讲「从源代码到可交付产物」的构建过程；安装、初始化与访问见 部署手册。 第 2~5 节为必读路径（约 5 分钟），第 6 节为 Docker 镜像构建，第 7 节为构建结果校验。

1 构建工具与版本

项 名称 版本 说明
语言运行时 Python ≥ 3.10（构建与测试基线 3.12） 与部署环境一致
依赖管理 pip 随 Python 附带（实测 26.1.2） 依赖清单 requirements.txt
构建脚本 build.py 随仓库提供 依次执行「跑测试 → 收集文件 → 打包 zip」
Windows 入口 build.bat 随仓库提供 双击即可：建 .venv → 装依赖 → 调 build.py
容器化 Docker / Buildx Docker 24+ 仅第 6 节使用；无 Docker 时可跳过
CI 平台 GitHub Actions — 推送 main 自动跑测试并构建镜像

构建配置文件清单

文件 作用
requirements.txt 运行期依赖（5 个包，精确锁版本）
requirements-dev.txt 测试期依赖（在运行期基础上加 httpx2）
build.py / build.bat 构建脚本
Dockerfile / .dockerignore 镜像构建定义
.github/workflows/docker-publish.yml CI：测试 → 构建镜像 → 推送 GHCR

2 环境要求

项 要求
操作系统 Windows 10/11（手册主路径）、Linux、macOS 均可
Python 3.10 以上，安装时勾选「Add Python to PATH」
磁盘 约 200 MB（虚拟环境 + 依赖）
网络 首次构建需联网下载依赖；国内可用清华镜像
数据库 无需安装，使用标准库 sqlite3

3 构建产物

产物 路径 说明
交付压缩包 dist/online-shopping-group5-1.0.0.zip 源代码交付包，解压即得完整项目目录（28 个文件、约 54 KB）
容器镜像 ghcr.io/xiaochu-dev/online-shopping-group5:baseline-v1.0 构建完成的可运行镜像，部署见 部署手册

压缩包内含 Dockerfile、build.py、requirements*.txt，因此拿到 zip 的人可以再次构建； 包内不含 .git、虚拟环境、__pycache__、*.db 与 dist/ 自身。

4 构建步骤（Windows 一键路径）

4.1 获取源代码

git clone https://github.com/xiaochu-dev/online-shopping-group5.git
cd online-shopping-group5

或从仓库 main 分支的 Code → Download ZIP 下载后解压。

4.2 一键构建

build.bat

脚本自动完成三步：

  1. 若无 .venv 则创建虚拟环境；
  2. pip install -r requirements-dev.txt 安装依赖（含测试依赖）；
  3. 调用 build.py：依次执行 4 套自动化用例（共 72 项），全部通过后打包出 dist/online-shopping-group5-1.0.0.zip。

任一用例失败时构建中止并不产出压缩包，控制台会打印失败脚本名。

4.3 手动构建（Linux / macOS / CI）

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
python build.py

已有环境时只需最后一行 python build.py。

5 构建过程的可验证输出

一次完整构建的控制台输出（摘要）：

========================================================
构建 online-shopping-group5 v1.0.0
Python 3.12.x  |  项目目录 .../online-shopping-group5
========================================================

[1/3] 执行自动化测试用例
--------------------------------------------------------
  >>> 冒烟测试（主流程 30 项）  (test_smoke.py)
  >>> 黄程宇模块自测（18 项）  (test_b_module.py)
  >>> 周到模块自测（10 项）  (test_d_module.py)
  >>> 交叉测试（验收清单 14 项）  (test_cross_review.py)
--------------------------------------------------------
测试全部通过。

[2/3] 收集交付文件
  共 28 个文件

[3/3] 打包
--------------------------------------------------------
构建成功：dist\online-shopping-group5-1.0.0.zip  (54.2 KB)
用例文件 覆盖范围 用例数
test_smoke.py 登录→发布→排队→撤销→冻结→递补→标记结果→历史→改密 全链路 30
test_b_module.py 黄程宇模块（商品发布、图片校验、买家意向） 18
test_d_module.py 周到模块（口令码、队列排序、撤销、递补） 10
test_cross_review.py 对照《需求规格说明书》第 6 章验收清单的交叉测试 14
合计 72（全通过，0 失败）

6 Docker 镜像构建

6.1 方式一：GitHub Actions 自动构建（推荐，无需本地 Docker）

仓库内 .github/workflows/docker-publish.yml 定义了两段式流水线：

  1. test 作业：Python 3.12 环境安装 requirements-dev.txt，顺序执行 4 套用例（72 项），失败即终止；
  2. build-and-push 作业：test 通过后，用 docker/build-push-action 构建镜像并推送到 GHCR，打三个标签 latest、baseline-v1.0、sha-<commit>。

触发方式：推送 main、推送 baseline-* 标签，或 Actions 页面手动 Run workflow。

拉取镜像：

docker pull ghcr.io/xiaochu-dev/online-shopping-group5:baseline-v1.0

6.2 方式二：本地构建（已安装 Docker 时）

docker build -t online-shopping-group5:baseline-v1.0 .

Dockerfile 关键设计：

设计点 说明
基础镜像 python:3.12-slim，与开发基线一致
分层缓存 先 COPY requirements.txt 装依赖，再 COPY . .，改代码不重装包
数据外置 ENV DB_PATH=/app/data/shop.db + VOLUME ["/app/data"]，容器重建不丢数据
健康检查 每 30s 请求 /product，返回 200 视为就绪（该页公开且依赖数据库）
启动命令 CMD ["python","main.py"]，内部 init_db() 后监听 0.0.0.0:8000

7 构建结果校验

# 校验项 期望结果
1 压缩包存在 dist/online-shopping-group5-1.0.0.zip 生成
2 压缩包结构 顶层目录为 online-shopping-group5-1.0.0/，含 main.py、Dockerfile、requirements.txt
3 无冗余文件 不含 .git/、__pycache__/、*.db、.venv/
4 镜像可拉取 docker pull ghcr.io/xiaochu-dev/online-shopping-group5:baseline-v1.0 成功
5 镜像可启动 docker run --rm -p 8000:8000 ghcr.io/...:baseline-v1.0 后访问 /product 返回 200
6 健康状态 docker ps 中 STATUS 显示 healthy

8 常见问题

# 现象 原因 解决
1 python 不是内部或外部命令 未加入 PATH 重装时勾选 Add Python to PATH，或用 py -3 代替
2 测试报 requires the httpx2 package 只装了 requirements.txt，缺测试依赖 改装 requirements-dev.txt
3 pip install 超时 / 502 默认源网络不稳定 加 -i https://pypi.tuna.tsinghua.edu.cn/simple 重试
4 Actions 里 build-and-push 报 403 组织禁用了包写入或 Actions 权限 仓库 Settings → Actions → General 允许读写；组织策略允许 GHCR
5 拉取镜像报 denied GHCR 包默认私有 在组织/个人 Packages 页面把该包可见性改为 Public
6 docker build 极慢 国内拉取基础镜像慢 配置镜像加速源，或直接用 6.1 的 Actions 构建

变更记录

版本 日期 变更内容 修订人
v1.0 2026-10-19 首版：构建工具与版本、构建步骤、产物说明、Docker 构建、校验清单、FAQ 胡成溯

本文件对齐课程《系统验收标准》第 3 项「构建」四要素：构建配置文件（requirements*.txt、Dockerfile）、构建工具程序（Python + pip + build.py）、构建过程手册（本页）、构建结果文件（dist/online-shopping-group5-1.0.0.zip、GHCR 镜像）。

⚠️ **GitHub.com Fallback** ⚠️