7.7 KiB
Docker 部署指南
项目简介
仓库物料管理系统 (WMMS) - 前后端分离架构
- 后端: Go + Gin + MySQL (端口 8082)
- 前端: Vue 3 + Vite + Nginx (端口 80)
- 数据库: MySQL 8.0 (端口 3306)
快速启动 (Windows)
前置条件
- 安装 Docker Desktop (Windows 10/11)
- 启动 Docker Desktop
启动服务
# 进入项目目录
cd c:\1111\12.project\VSCode\warehouse-mms
# 启动所有服务
docker-compose up -d
# 查看服务状态
docker-compose ps
访问应用
- 前端地址: http://localhost
- 后端API: http://localhost:8082/api （绑定在
127.0.0.1，仅限本机） - 健康检查: http://localhost:8082/api/health
用手机 / 局域网其他设备访问
手机连上与电脑同一个 WiFi，浏览器打开 http://<电脑的局域网IP>，用下节账号登录即可，不需要带端口号（80 是 HTTP 的默认端口，浏览器会自动使用）。
先查看电脑的局域网 IP —— 取 WLAN 那一行的地址，忽略 vEthernet (WSL)、VMware Network Adapter 这些虚拟网卡：
ipconfig
例如地址是 192.168.31.76，手机就访问 http://192.168.31.76。
为什么不需要改配置：前端请求走相对路径 /api，手机访问时会自动打到 http://<电脑IP>/api，再由 Nginx 反代给后端容器。前后端都没有硬编码 localhost，所以换任何 IP 访问都能正常工作。
端口绑定策略
| 服务 | 绑定地址 | 局域网可访问 | 原因 |
|---|---|---|---|
| frontend | 0.0.0.0:80 |
✅ 是 | 手机、其他设备要打开网页 |
| backend | 127.0.0.1:8082 |
❌ 否 | 前端经 Nginx 走容器内部网络反代（proxy_pass http://backend:8082），不经过宿主机端口 |
| db | 127.0.0.1:3307 |
❌ 否 | 数据库不应暴露；本机仍可用客户端连 3307 调试 |
后端和数据库绑定在 127.0.0.1 是有意的安全设置，只允许本机访问。若你临时需要让别的机器直连后端 API 调试，把 docker-compose.yml 里对应那行改回 "8082:8082"，再执行 docker compose up -d（改完记得改回去）。
手机打不开时怎么查
- 确认同一个 WiFi：手机和电脑必须是同一个 SSID。
- WiFi 的客户端隔离（AP 隔离）：单位、公共场所的网络常开启此功能，导致设备之间无法互访。这属于网络策略，与本项目无关 —— 用手机开热点让电脑连上试一次即可确认。
- Windows 防火墙：需放行 80 端口入站。Docker Desktop 安装时会按其网络类别自动添加放行规则，若仍不通，用管理员 PowerShell 临时加一条：
New-NetFirewallRule -DisplayName "WMMS 80" -Direction Inbound -LocalPort 80 -Protocol TCP -Action Allow # 测试完删除：Remove-NetFirewallRule -DisplayName "WMMS 80" - IP 会变：
192.168.x.x由 DHCP 分配，路由器重启后可能变化。想长期使用，建议在路由器上给这台电脑做静态 IP 绑定。
⚠️ 数据库使用默认密码
wmms1234，后端 API 也没有额外的访问控制，因此不要把 8082 / 3307 暴露到公网。
默认用户
| 用户名 | 密码 | 角色 |
|---|---|---|
| admin | admin123 | 管理员 |
| user | user123 | 普通用户 |
常用命令
# 查看日志
docker-compose logs -f
# 查看后端日志
docker-compose logs -f backend
# 停止服务
docker-compose down
# 重新构建并启动
docker-compose up -d --build
# 删除所有数据（谨慎操作）
docker-compose down -v
数据持久化
- MySQL数据:
mysql_dataDocker volume - 上传文件:
uploads_dataDocker volume
⚠️ 数据卷复用会导致表结构落后于代码
MySQL 官方镜像只在数据目录为空时才执行 /docker-entrypoint-initdb.d/ 下的脚本。也就是说 scripts/init.sql 只在 mysql_data 卷第一次创建时执行一次；只要卷还在，后续 docker compose up -d 一律直接复用旧数据，init.sql 完全不执行。
docker compose down 不带 -v 时卷会保留，所以改过 schema 之后重新部署，新代码会跑在旧表结构上。典型症状是容器全部 healthy、日志干净，但部分接口返回 500：
Error 1054 (42S22): Unknown column 'inbound_no' in 'field list'
部署前先确认现有表结构：
docker compose exec db mysql -uroot -pwmms1234 -e "SHOW COLUMNS FROM inbound_orders; SHOW COLUMNS FROM outbound_orders; SHOW COLUMNS FROM material_categories;" wmms
将实际字段与当前 scripts/init.sql 对比。数据卷的创建时间只能作为排查线索，不能证明表结构是否一致。
方式一：清空重建（推荐，最简单可靠）
docker compose down -v && docker compose up -d --build
-v 会删除 mysql_data 和 uploads_data 两个卷，库中数据全部丢失。执行前务必确认没有需要保留的业务数据，必要时先备份：
docker compose exec db mysqldump -uroot -pwmms1234 --default-character-set=utf8mb4 wmms > backup.sql
方式二：保留数据并更新结构
需要保留业务数据时，先备份数据库，再根据实际表结构与 scripts/init.sql 的差异编写并审核增量 SQL，在备份副本上验证后执行。
当前 scripts/init.sql 用于空库首次初始化，已包含出入库单号、操作人、备注、分类说明、6 个大类和 28 个子类，以及对应编码规则。库存预警阈值为 0 是有效配置，新库无需清理历史规则。不要将完整初始化脚本直接用于已有业务数据的数据库。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
| DB_DSN | root:wmms1234@tcp(db:3306)/wmms?charset=utf8mb4&parseTime=true | 数据库连接字符串 |
| GIN_MODE | release | Gin 运行模式 |
手动构建
# 构建后端
docker build -t wmms-backend .
# 构建前端
cd frontend
docker build -t wmms-frontend .
# 启动
docker-compose up -d
故障排查
端口冲突
如果 80 或 3306 端口被占用:
# 查看端口占用
netstat -ano | findstr ":80"
netstat -ano | findstr ":3306"
# 修改 docker-compose.yml 中的端口映射
数据库连接失败
# 检查数据库是否就绪
docker-compose logs db
# 等待数据库启动完成（约10秒）
接口返回 500：Unknown column 'xxx'
症状：容器状态全部 healthy，docker compose logs 也看不到异常，但某些接口返回 500，例如：
Error 1054 (42S22): Unknown column 'description' in 'field list'
原因：mysql_data 卷是旧的，init.sql 没有执行，表结构落后于当前代码。详见上文《数据持久化 → ⚠️ 数据卷复用会导致表结构落后于代码》。
确认：
docker compose exec db mysql -uroot -pwmms1234 -e "SHOW COLUMNS FROM material_categories;" wmms
检查报错涉及的表是否缺少字段，并与当前 scripts/init.sql 对比。
解决：确认数据库和上传文件均无需保留后，可执行 docker compose down -v && docker compose up -d --build 重建；需要保留数据时，先备份，再按实际结构差异准备并验证增量 SQL。
其他排查技巧
哪些表结构会不一致？ 直接在容器里对比：
# 看当前库到底建了哪些表和列
docker compose exec db mysql -uroot -pwmms1234 -e "SHOW TABLES;" wmms
docker compose exec db mysql -uroot -pwmms1234 -e "SHOW COLUMNS FROM inbound_orders;" wmms
查看容器内部
# 进入后端容器
docker exec -it wmms-backend sh
# 进入数据库容器
docker exec -it wmms-db mysql -u root -p