11 KiB
测试环境单机部署与配置契约
更新日期：2026-09-29。当前只有 test，没有开发/生产环境。本文定义目标部署、切换与验收；具体路由、认证、投递契约唯一见统一认证与服务通信契约。
状态：目标已确认，实现仍在迁移。第 0A 批资金消费者本地修复已完成；新 Gateway/Token/投递/Compose 尚未落地或发布。运行服务器、Nacos 发布值、主机资源和真实 MySQL 故障恢复尚未验证。
结论与范围
按“头程和海外仓不再分区域部署、所有服务同机运行、取消独立事件接收服务与海外网关”设计。这里将“事件接收”对应为当前 event-bridge-service，不推定要删除业务通知、异步任务或消息队列。
建议目标：一个 Gateway、一套 Auth/IAM 登录与权限体系、一个测试 Nacos 命名空间和一套测试内部容器网络。保留 Firstleg、Lastleg、Warehouse、Warehouse Overseas 等业务服务，各自拥有数据表与业务规则。同机可以共用 MySQL 实例，继续按服务分 Schema；不要求合并为一个数据库或一个 Java 进程。
最终移除 gateway-overseas 与 event-bridge-service 部署单元及其区域分支。服务名称中的海外业务含义可以保留；仓库类型、仓管角色、仓绑定和客户数据隔离仍有业务用途。
测试环境目标部署清单
| 类别 | 目标 |
|---|---|
| 环境 | 仅 test，所有服务同一台宿主机 |
| 用户端 | Admin、Client、国内 PDA、海外 PDA 共用一个业务 API 入口；页面和作业职责保留 |
| 入口 | Nginx/反向代理接统一 Gateway，业务内部端口不作为客户端访问入口 |
| 认证 | Auth、IAM、统一 JWT 与 Redis 会话，按平台/客户/PDA 校验权限 |
| 业务 | Order、Firstleg、Lastleg、Warehouse、Warehouse Overseas、Finance |
| 公共能力 | File、Print、Audit、Integration 按现有职责保留 |
| 配置与发现 | 一套 Nacos，使用实际 Namespace ID 的单一测试命名空间，不再分 test-cn/test-overseas |
| 数据与缓存 | 一套测试 MySQL 实例，按服务分 Schema；统一可访问的测试 Redis，保留必要键隔离 |
| 消息 | 保留现有 RocketMQ 用于导出、通知和审计等已发现用途 |
| 服务协同 | 同机内部调用；需要可靠交付的业务采用本地事务记录加直接投递和消费幂等 |
| 退出部署 | gateway-overseas、CN/OVERSEAS 两个 Event Bridge 实例及专用配置 |
服务名、Schema、端口、数据卷和实际中间件配置在改造前做一次清单核对；当前表是目标部署结构，不是对服务器现状的确认。旧 development/production 配置不再作为本次发布入口，也不要求新建对应环境。
分批实施与交付门槛
| 批次 | 工作 | 完成依据 |
|---|---|---|
| 0：文档与基线 | 确认仅 test 的目标、唯一接口路径、统一认证、直接投递职责；列出当前配置与服务清单 | 新目标、当前实现、待办三者明确区分 |
| 0A：资金消费前置修复 | 区分临时执行失败与最终业务拒绝；补齐并发 Inbox 抢占后的摘要校验和一致结果处理 | 临时故障原事件重试、并发同 hash/异 hash、执行成功后结果保存失败的恢复验证通过；修复规则见统一认证与服务通信契约；本地已通过，实库待验证 |
| 1：入口与认证 | Gateway 接入全部业务；Auth/common-security/海外服务统一认证；各端共用入口；解决仓库路由冲突 | 本地编译、认证测试、路由合同及受影响前端测试通过 |
| 2：业务通信 | 替换装柜、船节点、卸柜、暂扣、派送、费用和资金链；补齐直接投递重试及失败处置 | 各链路有直接消费者，成功确认、重复投递和故障恢复测试通过 |
| 3：部署收敛 | 单套 test Compose/Nacos/Jenkins；清理两个废弃服务和专用配置、SQL 初始化引用、安全投影依赖 | 构建与配置合同通过；形成唯一测试发布清单及启动依赖 |
| 4：测试环境验证 | 发布一致的新版本，以新造数据执行 API 全链路和各端实际操作 | 下表业务验收全部通过，保留报告及未通过项 |
改造批次可以分别完成代码检查；仅入口批次完成时，不把测试环境视为已跑通。正式测试部署须使用接口、认证、通信与配置相互匹配的一组版本，避免先停 Bridge 导致现有业务失联。
本地编译和离线检查只是开发工具使用，不代表存在独立“开发环境”。最低检查包括相关 Maven 测试编译/测试、网关路由与拓扑合同、前端类型检查及受影响测试；不以构建成功代替测试环境闭环通过。
测试环境跑通的验收标准
所有项目初始状态均为“待实施、待验证”。
| 验收项 | 操作与预期 |
|---|---|
| 部署与发现 | 所有保留服务启动健康，统一命名空间中可发现；客户端无需访问海外 Gateway 或 Bridge |
| 登录与权限 | Admin、Client、两类 PDA 使用统一认证；刷新有效、退出后失效；停用账号/客户和越权访问被拒绝 |
| PDA 仓绑定 | 未绑定拒绝作业，绑定仓限制正确，换仓后旧会话失效 |
| 仓库路由 | 仓库主档、库位、托盘访问正确服务，原重复前缀不再造成路由歧义 |
| 订单到装柜 | 新造客户与订单走审核、入仓、测量、分柜和装柜；完成后正确生成尾程数据 |
| 海外履约 | 船节点同步、接柜、卸柜、入仓、库存、排车、出库、派送形成闭环；签收按来源回写 Firstleg/Order |
| 状态协同 | 暂扣/解除、卸柜事实、分单签收作用于正确单据，不误推进同柜或同车其他订单 |
| 费用与资金 | 费用准确入 Finance；资金指令与结果对应；重复请求不重复入账、冻结或扣款 |
| 可靠性 | 消费服务短时停止、重启、响应超时、重复和乱序投递后可恢复，失败可查且可重试，无永久丢单 |
| 公共能力 | 文件上传下载、标签打印、异步导出、消息通知、审计正常 |
| 客户与作业界面 | Admin/Client 和 PDA 实际操作完成核心流程；HTTP 通过不能替代页面/设备验证 |
每次验收记录版本、测试数据业务编号、覆盖场景、结果及错误诊断信息。修复失败项后执行受影响回归，再给出整体是否跑通的结论。
D. 唯一测试环境的整体切换与失败恢复
本次采用测试停机窗口一次切换，允许测试数据按明确范围重建，不做新旧协议并行。实际部署、SQL、清理操作不在本文编写过程中执行。
| 顺序 | 操作 | 放行条件/记录 |
|---|---|---|
| D0 版本准备 | 记录各后端/前端/PDA 仓库提交、镜像 tag/digest、APK/WGT 版本、Nacos 配置版本与 SQL 基线 | 各端对应同一架构契约；本地检查通过 |
| D1 运行清单 | 列出当前容器、Compose 项目、网络、服务注册、Nacos Data ID/Group/Namespace、Redis DB/key、MQ topic/group、DB/文件卷引用 | 填实际标识，不输出凭据；确认主机容量和端口 |
| D2 停止写入 | 公告测试窗口、停止正在进行的验收/造数、阻断业务写入；停止旧业务容器、Relay 和相关消费任务 | 没有旧进程继续发消息、续写数据库或向旧 Nacos 注册 |
| D3 应用基线与配置 | 按逐项对象清单处理测试业务数据/旧投递、会话、必要 MQ 测试消息与文件引用；发布统一 test Nacos/Compose 配置 | 数据一致；不整机清空 Redis/MQ/文件，不触碰不在清单中的资源 |
| D4 启动新服务 | 中间件健康 → IAM/Auth 及公共能力 → 所有业务消费者与生产者 → Gateway → 前端；写入口保持关闭 | 健康检查通过且消费者就绪；无循环依赖导致的启动等待；旧网关/Bridge 不再启动 |
| D5 端侧切换 | 发布 Admin/Client 新构建，更新两类 PDA，清除旧登录态后重新登录 | 验收设备构建版本与配置正确；原生地址不再指向海外入口 |
| D6 冒烟 | 统一登录、主档/资源查询、越权拒绝、文件上传，加一条装柜→尾程链与一条资金指令→结果回传 | 无路由误投、认证失效或严重业务错误 |
| D7 完整验收 | 开放本轮验收写入，按前述矩阵新造数据执行完整 API、页面、PDA 及故障恢复 | 所有阻断项关闭才声明跑通 |
| D8 清理退役资源 | 核对旧容器、注册、配置及专用卷/库引用，形成明确清理清单 | 新链路通过、没有残余调用；删除动作单独按范围执行 |
启动顺序是依赖就绪原则，不允许写死为某服务必须业务调用另一未启动服务后才能健康。生产端 Outbox 可先记录并有限重试，不能在业务消费者启动前产生验收写入；冒烟前以实际健康状态确认。
停止条件：认证/客户隔离错误、资金重复执行、必需消费者不可达、投递无法恢复、数据库基线不匹配，任何一项即关闭测试写入并停止本轮验收，不用跳过场景换取整体通过。
失败恢复默认选择：保留故障证据，环境继续停写，修复新架构后用匹配版本重新部署并重建本轮失败测试数据。只有确需恢复原测试工作时，整体恢复旧镜像/前端/PDA、旧 Nacos/Compose 和匹配旧 Schema 基线，清理新旧会话及消息交叉引用；不恢复已经放弃的测试业务数据。单服务镜像回滚仅适用于确认契约和 Schema 未变的情况，不能代替本次架构整体恢复。
待部署准备时填写的运行值：测试窗口、发布清单、实际 Namespace ID、Data ID/Group、域名与端口、Redis DB/key 前缀、MQ 范围、SQL/卷操作清单、主机资源预算、验收数据编号。不得用猜测值替代运行检查；这些值未填写不进入 D2。
基线与范围
测试数据可以按明确对象重建，不设计存量迁移、双写、旧协议兼容或生产发布。本地编译不是独立开发环境。执行初始化、清理和部署前落实具体对象清单与适用授权，本契约不表示这些动作已执行。
配置收敛必须覆盖 Compose、Jenkins、deploy/service-map.yml、发布脚本、Nacos Data ID/Group/Namespace、前端代理与构建变量、PDA 地址、SQL 初始化引用、服务发现和健康检查。容器内不能用 localhost 代替其他服务名。保留文件数据卷及仍被导出/通知/审计使用的 RocketMQ。
不新增中间件，不合并业务服务、Schema、两类 PDA 或领域状态机；旧 development/production 退出当前发布入口，不顺手删除无关历史文件。模块旧指引中双区域部署、双 Token 或必须经海外 Gateway 的强制描述属于迁移前实现，后续实现以本契约和统一认证契约为准，并随对应批次更新模块说明。
验收记录保存各仓库提交、镜像/配置版本、业务编号、覆盖场景与失败项。本地检查、H2 事务测试与真实 MySQL/HTTP/页面/PDA 验收分别记录，不能互相代替。