> 选题编号 29 · 部署问题TOP10
「代码拉下来，照文档跑一遍，然后卡住」------多数团队接触 JeeWMS 这套开源 Java 仓库管理系统的第一个小时都是这样。官方仓库只有一个：https://gitee.com/erzhongxmu/JEEWMS ，认准官方仓库 gitee.com/erzhongxmu/JEEWMS，注意辨别第三方镜像与 fork。
但有一点值得先说清楚：**WMS 部署失败的原因，绝大多数不落在代码里，而落在环境里**。同一份代码，在同事的机器上跑得起来，在客户机房跑不起来，差的通常不是版本高低，而是那台机器上从来没有人记录过的东西------JDK 的字符集、数据库的排序规则、容器的时区、代理的超时。
这种困惑有个固定形状：日志里能看到的往往只是最后一个症状（连不上、超时、404、乱码），而不是根因。于是所有人开始猜，改一处、重启一次，问题偶尔消失又偶尔回来。要跳出这个循环，得先把「可运行」这件事定义清楚。
一、先把「可运行」定义清楚：环境基线四层
| 层次 | 基线项 | 最常被漏掉的那一项 |
| --- | --- | --- |
| 运行时层 | JDK 版本（1.8 及以上）、默认字符集与语言、时区 | 默认字符集------交给操作系统决定，是乱码类问题的总开关 |
| 存储层 | 数据库版本、字符集与排序规则、表名大小写策略、初始化数据完整性 | 排序规则：装的时候不选，后面排序与去重都会怪 |
| 中间件层 | Redis / Ehcache 配置、配置中心参数、多租户域验证参数 | 域验证参数------数据「有」却查不到，多半在这里 |
| 接入层 | 代理与超时、上传体积、跨域规则、前端接口前缀 | 代理超时：小数据全对，一大批量就崩 |
一句话原则：**基线不是「我装了」，而是「我记录了确切的值，且这个值能被另一台机器复现」**。前者是你电脑的状态，后者才叫交付物。
二、四类根因：把一堆零散的坑装进四个抽屉
部署问题看起来五花八门，归到最后只有四类根因。按类排查，比按报错逐条搜要快得多。
**类别一：运行时基线漂移。** 典型两个：一是 JDK 版本与语言环境不一致，现象是编译期就挂、运行期类找不到、数字与日期格式异常；二是时区不统一，现象是单据时间差 8 小时、日结跨天、报表按日期过滤时少一天。根治方式很朴素------锁定 JDK 并写进交付说明，同时把系统、数据库连接、应用三层时区统一，并且**单独列为一项检查，而不是默认它是对的**。
**类别二：存储与编码。** 这是部署阶段踩坑最密集的一类，细分四种：数据库版本与字符集不匹配，表现为中文乱码或排序不符合预期；表名大小写敏感，表现为开发机（不敏感）能用、上线到大小写敏感环境（Linux）就崩；初始化脚本导入不完整，表现为模块能打开但某类单据打不开、基础字典缺项；多数据库方言与库内存储 SQL，表现为换库（MySQL、Oracle、SQL Server）后个别查询报错。前三种的根治办法都是「交付前在目标环境的真实特征上完整跑一次初始化」，第四种则要把数据库方言当成一项**能力**去验证，而不是当成一个配置项去填。
**类别三：中间件与配置。** Redis 与 Ehcache 配置不当，表现为登录态丢失、字典改了不生效、缓存与库不一致；配置中心与多租户域验证参数错位，表现为「明明有数据却查不到」。这一类最容易被误判成程序 Bug------因为界面没有任何报错，只是安静地少了几行数据。判据是：同一个查询换一个账号或换一个货主身份执行，行数是否变化。若变化符合预期，就不是 Bug。
**类别四：接入层。** 跨域与接口 404，表现为前端页面能打开但所有请求失败，根因多在接口前缀、代理转发规则或前后端端口对应关系；代理超时与上传体积限制，表现为小请求全通、批量导入直接 502；HTTPS 页面里的混合内容，表现为页面加载到一半报错，多半是前端请求地址写死了 http。接入层的特点是可以**用「直连后端」这一步把范围一次性砍半**，所以定位顺序永远先绕开它。
三、差异三轴：两个环境到底差在哪
排查到最后总会落到「两边到底差什么」。把差异收敛成三根轴，每根轴配一句判据，比漫无目的地比对配置文件有效。
| 轴 | 比什么 | 判据 |
| --- | --- | --- |
| 运行时轴 | JDK、字符集、时区、依赖库版本 | 同一条命令在两边输出是否逐字一致 |
| 数据轴 | 表数量、基础字典行数、期初数据范围 | 表与字典行数一致，且期初数据有据可查 |
| 网络轴 | 应用容器到数据库、缓存、对端系统的连通性 | 从**容器内**能连上，而不是从你的电脑能连上 |
第三根轴的判据值得单独强调：「你的电脑能连」和「生产环境的容器能连」是两件完全不同的事。相当一部分「连不上」的工单，最后发现是防火墙只放开了运维电脑的出口。
四、15 分钟归因三步
有了前面的分类和轴，故障定位可以固定成三步：
第一步，看**启动日志的最后一个失败点**------不是第一条报错，而是导致进程退出的那一条。启动阶段失败几乎都落在运行时层或存储层，很少落在业务代码里。
第二步，用**最小可复现请求直连后端**，绕过前端与代理，判断问题在接入层还是应用层。这一步通常能立刻把排查范围砍掉一半。
第三步，**逐项勾差异三轴表**，并且遵守一条纪律：一次只改一个变量、只重启一次。一次改多处会让问题消失得不明不白，下次复现又要从头再来。
五、可复现交付四件套
把部署从「一次成功的操作」变成「一份可交付的资产」，需要四样东西：
-
**环境定义脚本化或镜像化**：把 JDK 版本、数据库版本、字符集、时区写进脚本，而不是写在文档里的一句话。
-
**配置字典与版本台账**：记录配置项含义、默认值、谁改过、何时生效。这份台账在排查时比任何截图都有用。
-
**初始化数据与期初数据分离**：系统初始化的字典与业务期初库存分两批导入，出问题才能单独回滚。
-
**冒烟清单**：不靠印象，靠一张会被逐项勾掉的表。
这四件套的价值不在第一次部署，而在第二、第三次------换人、换机房、升级版本的时候，收益才真正兑现。
六、上线前 30 分钟冒烟清单
| 检查项 | 通过标准 |
| --- | --- |
| 登录与角色 | 不同角色登录后看到的菜单不同 |
| 域验证与多租户 | 切换仓库或货主后，列表行数变化符合预期 |
| 主数据 | 商品、库位、供应商、承运商可查可用 |
| 入库流程 | 收货到上架全流程走通一张单 |
| 出库流程 | 波次、拣货、复核、发运走通一张单 |
| 库存查询 | 结果与期初数据合得上 |
| PDA 端 | 扫码能连、能提交，数据在 WEB 端可见 |
| 报表 | 至少一张报表的数字能与明细互校 |
| 任务与调度 | 定时任务有执行记录，不是「配了就算有」 |
| 备份与恢复 | 有人能说清备份文件在哪、怎么恢复 |
七、开源与授权
JeeWMS 采用 GPL-3.0 协议，主仓库在 Gitee 上已获 GVP 认证；PDA 移动端源码在同组织的 jeewmsapp 仓库（UNI-APP 技术栈），GitHub 上另有只读镜像。技术口径上，最新版本基于 Spring Cloud 微服务架构 + Vue 前端，持久层使用 Hibernate 与 Minidao，缓存使用 Redis 与 Ehcache，并支持多租户、多数据库与 SAP、用友 U8、百胜 E3 等系统的数据对接。社区交流可在 Gitee 仓库的 Issue 区反馈。
八、从部署到未来
部署这件事之所以值得如此较真，是因为它是后面所有事情的地基。项目方正在构建工业互联网智能体平台------用 AI Agent 贯穿 WMS 仓储、MES 制造执行、ERP 企业资源、CRM 客户关系等业务域，把仓储沉淀的领域经验与大模型能力结合，走向智能调度、智能排产与 AI 运维。而智能体要给得出可靠建议，前提恰恰是这套环境基线、账实口径与事件流的规范程度：环境不可复现，AI 看到的就只是噪声。
九、结语
换台机器，你能否复现出完全一样的环境？出了问题，你能否在 15 分钟内定位到是哪一层，而不是靠猜？那张冒烟清单，是写在纸上，还是真的被逐项验过？
这三个问题的答案，就是一套开源 WMS 能不能在你自己机房里安稳跑起来的分界线。项目地址：https://gitee.com/erzhongxmu/JEEWMS