部署手册 - xiaochu-dev/online-shopping-group5 GitHub Wiki
在线购物系统 部署手册（MVP）
| 项目 | 内容 |
|---|---|
| 文档名称 | 04-部署手册 |
| 项目名称 | 在线购物系统（挑战升级） |
| 版本 | MVP（第 1 次迭代基线版本） |
| 项目组号 | 第 5 组 |
| 编制人 | 胡成溯（组长） |
| 编制日期 | 2026-10-06 |
| 文档版本 | v1.0 |
| 对齐标准 | 课程 Wiki《系统验收标准》第 4 项「部署」：运行环境说明、安装部署过程、部署脚本 |
文档说明：本手册描述 MVP 版本从零到可访问的完整部署过程。按第 1~4 节顺序执行即可完成部署；第 5 节为常见问题排查；第 6 节为评审现场的一键演示脚本。
1 运行环境
| 项 | 要求 | 说明 |
|---|---|---|
| 操作系统 | Windows 10 / 11 | 64 位；Linux / macOS 同样可运行（命令通用），本文以 Windows 为准 |
| Python | ≥ 3.10（开发与测试基线为 3.12） | 安装时勾选「Add Python to PATH」 |
| 数据库 | 无外部数据库依赖 | 使用 Python 标准库 sqlite3，数据库为项目目录下的单文件 shop.db，无需安装任何数据库服务 |
| 浏览器 | Chrome / Edge 现代浏览器 | 访问与演示使用 |
| 网络 | 本机回环即可 | 服务监听 127.0.0.1:8000，无需公网 |
| 第三方依赖 | 仅 4 个 pip 包 | 见 requirements.txt：fastapi、uvicorn、jinja2、python-multipart（表单与文件上传解析） |
2 安装步骤
2.1 获取源代码
从 Git 平台下载 项目简写-版本号.zip 并解压，或直接克隆仓库，得到项目目录：
shop-mvp/
├── main.py # 应用入口（uvicorn 启动）
├── db.py # 建表与种子数据初始化脚本
├── run.bat # Windows 一键启动脚本
├── requirements.txt # 第三方依赖清单
├── app/ # 路由层、服务层代码
├── templates/ # Jinja2 模板（后台 / 买家页 / 历史）
└── static/ # 占位图、上传图片目录
2.2 创建虚拟环境（推荐）
cd shop-mvp
python -m venv .venv
.venv\Scripts\activate
2.3 安装依赖
pip install -r requirements.txt
国内网络环境建议使用清华镜像源加速：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
安装完成后可用 pip list 确认 fastapi、uvicorn、jinja2、python-multipart 均已就位。
3 初始化
首次部署必须先执行初始化脚本（自动建表 + 写入种子卖家账号）：
python db.py
初始化脚本自动完成：
- 在项目根目录创建 SQLite 数据库文件
shop.db； - 创建
seller/product/intent三张表及队列复合索引（DDL 见《03-架构设计与数据库表结构》第 6 节）； - 写入种子卖家账号：
| 项 | 值 |
|---|---|
| 用户名 | admin |
| 初始密码 | admin12345 |
⚠️ 安全提示：种子密码仅用于首次登录，评审与日常使用前请登录后台立即修改密码（后台「修改密码」入口，需验证原密码，新密码 ≥ 8 位）。
4 启动与访问
4.1 启动服务
两种方式任选其一：
方式一：命令行启动
python main.py
方式二：双击一键启动脚本
双击项目根目录下的 run.bat
run.bat 内部执行「激活虚拟环境 + python main.py」，用于评审现场免命令行演示。
启动成功后控制台输出：
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
4.2 访问入口
| 页面 | 地址 | 权限 |
|---|---|---|
| 买家页（商品浏览与意向提交） | http://127.0.0.1:8000/product | 公开 |
| 登录页 | http://127.0.0.1:8000/login | 公开 |
| 卖家后台（发布 / 意向人 / 冻结 / 标记结果） | http://127.0.0.1:8000/admin | 需登录 |
| 历史记录 | http://127.0.0.1:8000/admin/history | 需登录 |
首次部署顺序：第 3 节初始化 → 第 4 节启动。未初始化直接启动会提示数据库文件缺失，按第 3 节执行
python db.py后重新启动即可。
5 常见问题（FAQ）
| # | 问题 | 原因 | 解决方法 |
|---|---|---|---|
| 1 | 启动报 [Errno 10048] / address already in use，8000 端口被占用 |
8000 端口已被其他进程（或上次未退出的实例）占用 | 换端口启动：python main.py --port 8001，并以 http://127.0.0.1:8001 访问；或先结束占用进程 |
| 2 | 图片上传被拒绝，提示超出大小限制 | FR-02-6：单张图片 ≤ 5MB，且仅接受 JPG / PNG | 压缩图片或换小图。限制定义于发布表单校验逻辑（app/ 下发布校验代码，对应 FR-02-6），修改上限需改该校验常量并重新启动 |
| 3 | 数据想重置回初始状态（演示前清场） | 数据持久化在 shop.db，重启不丢失（NFR-04） |
重置方法：① 停止服务（Ctrl+C 或关闭窗口）；② 删除项目根目录下的 shop.db（若启用 WAL 还有 shop.db-wal、shop.db-shm 一并删除）；③ 重新执行 python db.py；④ 重新启动。重置后卖家账号恢复为 admin/admin12345 |
| 4 | 访问 /admin 被跳转到登录页 |
FR-01-3：后台须登录后访问 | 正常行为，用卖家账号登录即可 |
| 5 | pip install 下载缓慢或超时 |
默认源境外网络不稳定 | 使用 2.3 节的清华镜像源命令重试 |
| 6 | 上传的商品图片不显示 | static/ 目录被移动或改名 |
保持项目目录结构原样，确认 static/ 目录存在且有写入权限 |
6 评审演示脚本（一键演示路径）
以下为第 1 次评审的完整演示动线，覆盖 MVP 验收清单第 1~12 项。演示前建议按 FAQ-3 重置数据库，保证队列干净。演示用买家在多个浏览器窗口（或普通 + 无痕窗口）中打开买家页。
| 步 | 操作 | URL | 预期页面 / 结果 |
|---|---|---|---|
| 1 | 卖家登录：打开登录页，输入 admin / 当前密码 |
http://127.0.0.1:8000/login |
登录成功，跳转后台 /admin，可见「发布商品」入口 |
| 2 | 发布商品：后台点「发布商品」，填名称、描述、上传图片（或留空用占位图）、价格 9.90，提交 |
http://127.0.0.1:8000/admin/publish |
发布成功，商品进入「在售」；打开买家页可见该商品 |
| 3 | 买家甲提交意向：买家窗口 1 打开买家页，填姓名「买家甲」、电话，提交 | http://127.0.0.1:8000/product |
提交成功，当场显示口令码，提示「当前排队第 1 位」 |
| 4 | 买家乙、丙依次提交：买家窗口 2、3 重复操作（乙第 2、丙第 3） | http://127.0.0.1:8000/product |
各自获得独立口令码；后台意向列表按提交时间正序显示甲→乙→丙 |
| 5 | 买家乙撤销：在乙的口令码页（或凭口令码进入撤销页）撤销意向 | 口令码页「撤销意向」入口 | 撤销成功；后台列表变为甲→丙，丙位次自动前移到第 2 位 |
| 6 | 进入交易（自动冻结）：后台选中队首「买家甲」进入交易 | http://127.0.0.1:8000/admin |
意向甲转「交易中」，商品转「已冻结」；买家页显示**「商品交易中」**，无法提交新意向 |
| 7 | 标记交易失败（递补）：后台对甲标记「交易失败」 | http://127.0.0.1:8000/admin |
甲转「失败」，商品自动回「在售」→ 新队首丙自动转「交易中」→ 商品再次冻结（递补完成）；买家页显示「商品交易中」 |
| 8 | 标记交易成功：后台对丙标记「交易成功」 | http://127.0.0.1:8000/admin |
丙转「成功」，商品撤下进入历史；商品已下架，队列其余意向（无）转失败 |
| 9 | 历史核对：后台打开历史列表，点进该商品详情 | http://127.0.0.1:8000/admin/history |
历史列表按交易时间倒序展示、可翻页；详情页可见商品级字段（名称/描述/图片/价格/发布时间/结果/交易时间）与意向人级字段（甲=失败、乙=已撤销、丙=成功），字段完整 |
| 10 | 改密（收尾，可选）：后台修改密码，输入原密码与新密码（≥8 位） | http://127.0.0.1:8000/admin |
原密码校验通过方可修改，新密码生效（演示后如需还原按 FAQ-3 重置） |
演示要点提示：步骤 6~7 是「队列与递补」的核心演示点（FR-06-1、FR-07-6/7）；步骤 9 可对照验收清单第 12 项逐字段核对。若评审现场 8000 端口冲突，全程将 URL 中的 8000 替换为 FAQ-1 中的备用端口即可。
变更记录
| 版本 | 日期 | 变更内容 | 修订人 |
|---|---|---|---|
| v1.0 | 2026-10-06 | 首版创建：运行环境、安装步骤、初始化、启动访问、FAQ、评审演示脚本 | 胡成溯 |
本文件对齐课程《系统验收标准》第 4 项「部署」三要素：运行环境说明（第 1 节）、安装部署过程（第 2~4 节）、部署脚本（run.bat 一键启动 + db.py 初始化脚本）。