material_manage_system/DEPLOY.md

Docker 部署指南

项目简介

仓库物料管理系统 (WMMS) - 前后端分离架构

• 后端: Go + Gin + MySQL (端口 8082)
• 前端: Vue 3 + Vite + Nginx (端口 80)
• 数据库: MySQL 8.0 (端口 3306)

快速启动 (Windows)

前置条件

1. 安装 Docker Desktop (Windows 10/11)
2. 启动 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（改完记得改回去）。

手机打不开时怎么查

1. 确认同一个 WiFi：手机和电脑必须是同一个 SSID。
2. WiFi 的客户端隔离（AP 隔离）：单位、公共场所的网络常开启此功能，导致设备之间无法互访。这属于网络策略，与本项目无关 —— 用手机开热点让电脑连上试一次即可确认。
3. Windows 防火墙：需放行 80 端口入站。Docker Desktop 安装时会按其网络类别自动添加放行规则，若仍不通，用管理员 PowerShell 临时加一条：

   New-NetFirewallRule -DisplayName "WMMS 80" -Direction Inbound -LocalPort 80 -Protocol TCP -Action Allow
   # 测试完删除：Remove-NetFirewallRule -DisplayName "WMMS 80"
   

4. 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_data Docker volume
• 上传文件: uploads_data Docker 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 volume inspect warehouse-mms_mysql_data --format '{{.CreatedAt}}'

把结果和最近一次改 schema 的提交时间对比：卷比代码新就没问题，卷比代码旧就要按下节处理。

方式一：清空重建（推荐，最简单可靠）

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/ 下有三个手工迁移脚本，按需执行：

脚本	作用	是否破坏数据
add_order_display_fields.sql	出入库单补 inbound_no / outbound_no / operator / remark	否，仅加列并回填单号
update_material_categories.sql	重建分类树并写入编码规则	是，会清空物料、单据、库存、流水
update_warning_stock_zero.sql	清理阈值为 0 的历史预警规则	是，会删除这些规则行

执行方式：

docker compose exec -T db mysql -uroot -pwmms1234 --default-character-set=utf8mb4 wmms < scripts/xxx.sql

执行前请先备份，并阅读脚本头部的说明。

环境变量

变量	默认值	说明
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 volume inspect warehouse-mms_mysql_data --format '{{.CreatedAt}}'

如果卷的创建时间早于最近一次改 schema 的提交，就是这个原因。

解决：确认库里无业务数据后执行 docker compose down -v && docker compose up -d --build 重建；需要保留数据则改跑 scripts/ 下的增量脚本。

其他排查技巧

哪些表结构会不一致？ 直接在容器里对比：

# 看当前库到底建了哪些表和列
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