baiyue-firstleg/docs/cross-region-firstleg-lastleg-deployment-plan.md

头程国内、尾程海外的跨区域微服务部署方案

更新时间：2026-07-29
依据：当前 D:/baiyue Spring Cloud Alibaba 微服务、悦/头程物流流程图.svg、头程下单原型和货代后台原型。

审核状态：待用户审核。本文是项目拆分、部署和迁移的实施方案；文中目标架构、海外资源和切流步骤不代表已经完成生产部署。当前生成的部署目录仅是同一 Git 仓库内的 Maven 聚合和配置骨架。

1. 结论

推荐采用“国内业务单元 + 海外业务单元 + 跨区域可靠事件桥”，不要把同一套 Nacos、MySQL、Redis 或一个微服务调用链直接横跨国内外服务器。

这里的“国内业务单元、海外业务单元”首先是代码、数据库和数据所有权边界，不等于一期必须立即购买海外服务器。当前项目应立即按两个部署单元拆分配置、服务职责和事件契约，但一期允许所有服务都部署在国内同一机房：lastleg-service、海外仓实例和海外集成实例先以 REGION_CODE=CN 运行。待事件链路、鉴权和对象存储满足迁移门槛后，再把尾程写入单元迁到海外，不需要重新拆项目。

国内单元：客户、订单、头程、国内仓、认证和权限的主数据
海外单元：尾程、海外仓、清关、提柜、派送、POD、Amazon SP-API
跨区交接：本地事务 Outbox -> HTTPS/mTLS 事件中继 -> Inbox 去重 -> 处理回执
统一轨迹：海外发布里程碑事件，国内保存只读投影供客户查询

这一方案符合原型的业务边界：

• 头程在国内完成“下单 → 到仓 → 出仓 → 装船发运”。
• 尾程在海外完成“到港前 → 到港 → 到仓 → 出仓 → 签收”。
• “装船发运”是两个区域的数据所有权交接点。

1.1 当前已生成的部署骨架

路径	当前用途	当前状态
D:/baiyue/deployments/cn	国内部署单元 Maven 聚合、环境变量示例和构建脚本	已生成，待审核；一期实际部署入口
D:/baiyue/deployments/overseas	海外部署单元 Maven 聚合、环境变量示例和构建脚本	已生成，待审核；暂不代表海外服务器已部署
D:/baiyue/common-event-contract	国内外共享的事件信封、类型和区域契约	已生成基础源码，6 个单元测试通过；尚未接入业务事件链路，不得视为可用于生产
D:/baiyue/event-bridge-service	跨区事件接收幂等、待发送事件和投递尝试的独立服务边界	已生成基础骨架，8 项测试通过；内部令牌、目标区域校验和 Inbox 幂等接收已实现，生产传输开关为关闭

两个部署目录引用根仓库现有模块，不复制业务源码，也不建立第二个 Git 仓库。构建命令为：

国内和海外聚合均已包含 common-event-contract 与 event-bridge-service。国内默认构建为 18 个 Reactor 模块；一期尾程临时在国内运行时，使用 phase1-domestic-lastleg Profile 构建 19 个 Reactor 模块并包含 lastleg。

cd D:\baiyue\deployments\cn
.\build.ps1

# 一期尾程临时部署在国内
.\build.ps1 -IncludePhase1Lastleg

cd D:\baiyue\deployments\overseas
.\build.ps1

只校验默认聚合关系时，在对应目录执行 mvn -f pom.xml -DskipTests validate；校验一期国内尾程兼容聚合时执行 mvn -f pom.xml -Pphase1-domestic-lastleg -DskipTests validate。事件契约可在根目录执行 mvn -pl common-event-contract -am test。以上构建通过只说明代码依赖和测试通过，不等于生产部署、网络连通或数据迁移验收通过。

2. 当前代码现状判断

模块	当前情况	对跨区部署的影响
gateway	已按服务名走 Nacos 和 lb:// 路由	可以分别部署国内、海外 Gateway，但必须连接各自区域的 Nacos
auth-service	国内统一登录，HS256 JWT	可先放国内；正式跨区前建议改为 RS256/ES256 + JWKS
iam-service	租户、角色、菜单、按钮权限	主库建议放国内，海外通过 Token 权限快照工作，不应每次跨区查询 IAM
order-service	已有下单和状态机，也有 ord_outbox_event	Outbox 只是表和写入逻辑，尚缺可靠发布器、MQ/中继和跨区消费者
firstleg-service	目前只有健康检查、任务分配等少量能力	原型中的到仓、测量、排柜、订舱、装柜、报关等还需实现
lastleg-service	当前基本只有健康检查	还没有到港前、清关、提柜、海外仓、派送、POD 的业务闭环
warehouse-service	当前是一个服务边界	需要区分国内仓实例和海外仓实例，各自独占区域数据库
file-service	当前默认使用本地磁盘	跨区域部署不能继续依赖单机 D:/...，需要迁移到 OSS/S3 类对象存储
integration-service	已预留百度 OCR、Amazon SP-API 配置	国内实例启用百度 OCR；海外实例启用 Amazon SP-API 和当地承运商接口
event-bridge-service	已有端口 9300、独立库和三张基础表；内部服务令牌、目标区域、事件信封与摘要校验及 Inbox 幂等已实现，8 项测试通过	mTLS、来源白名单、RocketMQ、真实跨公网 HTTP 投递、Outbox 扫描调度和业务消费者尚未实现，不能用于生产交接

因此现在可以先搭好部署骨架和事件契约，但不能把 lastleg-service 部署到海外后就认定尾程业务已经完成。

3. 推荐部署拓扑

flowchart LR
    FE[客户/平台前端] --> EDGE[统一域名 + CDN/WAF/全局路由]

    subgraph CN[国内业务单元]
        CNGW[gateway-cn]
        AUTH[auth-service]
        IAM[iam-service]
        ORDER[order-service]
        FIRST[firstleg-service]
        CNWMS[warehouse-service CN]
        CNFILE[file-service CN]
        CNOCR[integration-service Baidu OCR]
        CNDB[(国内独立 MySQL)]
        CNREDIS[(国内 Redis)]
        CNNACOS[Nacos prod-cn]
        CNOUT[Outbox Publisher]
        CNPROJ[统一轨迹投影]
    end

    subgraph OS[海外业务单元]
        OSGW[gateway-overseas]
        LAST[lastleg-service]
        OSWMS[warehouse-service OVERSEAS]
        OSFILE[file-service OVERSEAS]
        OSINT[integration-service Amazon/海关/承运商]
        OSDB[(海外独立 MySQL)]
        OSREDIS[(海外 Redis)]
        OSNACOS[Nacos prod-overseas]
        OSIN[Inbox Consumer]
        OSOUT[Outbox Publisher]
    end

    EDGE -->|Auth/IAM/Order/First-leg| CNGW
    EDGE -->|Last-leg/海外仓作业| OSGW
    CNGW --> AUTH & IAM & ORDER & FIRST & CNWMS & CNFILE
    OSGW --> LAST & OSWMS & OSFILE & OSINT
    FIRST --> CNOUT
    CNOUT -->|HTTPS 443 + mTLS| OSIN
    OSIN --> LAST
    LAST --> OSOUT
    OSOUT -->|里程碑/回执 HTTPS 443 + mTLS| CNPROJ

3.1 国内部署的服务

服务	是否国内主部署	说明
gateway	是	国内客户、平台后台入口
auth-service	是	账号登录、刷新、退出的唯一写入口
iam-service	是	企业、成员、角色、菜单和按钮权限主数据
order-service	是	商户下单、审核、受理以及订单主档
firstleg-service	是	到国内仓、测量差异、排柜、订舱、拖车、装柜和国内报关
warehouse-service	是	国内仓资料和国内仓作业数据
file-service	是	企业资质、国内报关资料、装柜照片等国内文件入口
integration-service	是	百度 OCR、国内报关代理或港务接口适配
audit-service	是	国内业务审计主记录
print-service	按需	国内标签、箱唛、作业单打印

3.2 海外部署的服务

服务	是否海外部署	说明
gateway	是	海外运营后台、海外 PDA 和承运商回调入口
lastleg-service	是	到港前、清关、提柜、到仓、派送、签收和异常主服务
warehouse-service	是	海外仓预约、开柜、清点、打托、拣货和装车
file-service	是	BOL、DO/PU、开柜照片、POD 等海外文件
integration-service	是	Amazon SP-API、FBA 预约、海关、码头和海外承运商适配
audit-service	是	海外操作本地审计；摘要可异步回传国内
print-service	按需	BOL、派送单、海外标签和仓内作业单

海外不部署 order-service 和 firstleg-service 的写实例，国内也不部署 lastleg-service 的写实例，避免同一业务聚合在两个区域同时写入。

3.3 一期与目标物理归属

服务	一期物理位置	后期主写位置	迁移说明
auth-service、iam-service	国内	国内	统一登录和权限主数据保持国内唯一写入
order-service、firstleg-service	国内	国内	订单和头程事实保持国内唯一写入
lastleg-service	国内	海外	一期先在国内运行；后期只把新创建的尾程聚合切到海外，旧单在国内排空
warehouse-service	国内单实例	国内仓实例在国内，海外仓实例在海外	同一代码按区域配置部署，数据库完全隔离
file-service	国内	国内、海外各一套	文件元数据和对象桶按数据产生区域归属，按业务需要复制
integration-service	国内	国内、海外各一套	国内启用 OCR/港务适配，海外启用 Amazon/海关/承运商适配
audit-service、print-service	国内	按区域各自部署	本地操作本地留痕和打印，不跨区同步调用
gateway、Nacos、Redis	国内	国内、海外各一套	两区互不注册、互不直接访问 Redis

4. 原型节点与服务归属

4.1 国内头程

原型阶段	原型动作	主要服务
下单	客户下单、委托下单、快速下单、换标下单	order-service；一期仅实现普通头程订单，不扩展快速/换标完整产品
到仓	预约取货、送货上门	firstleg-service + 国内 warehouse-service
到仓	入库测量、差异核对、指定库位	国内 warehouse-service，结果事件回写 firstleg-service
出仓	智能排柜、订舱、预约拖车	firstleg-service
出仓	PDA 拣货、装柜、柜照和铅封照	国内 warehouse-service + file-service
出仓	报关资料、代理报关、回执	firstleg-service + 国内 integration-service + file-service
出仓	港务信息、预计开船、到港	firstleg-service + 船司/港务适配器
交接	装船发运	firstleg-service 生成不可变交接快照并写 Outbox

4.2 海外尾程

原型阶段	原型动作	主要服务
到港前	FBA 仓预约、BOL 预清货、清关资料、货物中转备注	lastleg-service + 海外 integration-service
到港	清关放行、DO/PU、通知码头车队提柜	lastleg-service
到仓	开柜拍照比对、PDA 打托、派送车队预约	lastleg-service + 海外 warehouse-service + file-service
出仓	BOL 送货、PDA 拣货装车、整柜派送、自提出仓	lastleg-service + 海外 warehouse-service
签收	私人仓/FBA 签收回执、送仓异常	lastleg-service + file-service + Amazon/承运商适配器

5. 跨区交接设计

5.1 正确交接点

当前 order-service 在订单 APPROVED 时写 FIRST_LEG_ORDER_APPROVED，这不是尾程交接事件。尾程只能在真实“装船发运”完成后建立预到港任务。

建议新增：

FirstLegShipmentDeparted.v1
LastMileHandoffAccepted.v1
LastMileHandoffRejected.v1
LastMileMilestoneChanged.v1
LastMileCompleted.v1

5.2 交接事件示例

{
  "eventId": "01J...ULID",
  "eventType": "FirstLegShipmentDeparted",
  "eventVersion": 1,
  "occurredAt": "2026-07-29T16:30:00+08:00",
  "traceId": "trace-xxx",
  "sourceRegion": "CN",
  "operatorTenantId": 10001,
  "customerTenantId": 20001,
  "aggregateId": 90001,
  "aggregateVersion": 7,
  "handoverVersion": 1,
  "payload": {
    "firstLegOrderIds": [80001, 80002],
    "containerNo": "MSCU1234567",
    "sealNo": "SEAL123456",
    "vesselName": "EXAMPLE VESSEL",
    "voyageNo": "V001",
    "mblNo": "MBL001",
    "hblNos": ["HBL001"],
    "etd": "2026-07-30T10:00:00+08:00",
    "eta": "2026-08-18T09:00:00-07:00",
    "destinationPortCode": "USLAX",
    "destinationWarehouse": {
      "type": "FBA",
      "code": "LGB8"
    },
    "cargoSnapshot": [],
    "documentRefs": [],
    "checksum": "sha256:..."
  }
}

文件正文不要放进消息，只传文件 ID、版本、SHA-256 和一次性下载凭证。海外确认保存后再返回 LastMileHandoffAccepted。

5.3 可靠性规则

1. 头程状态更新、状态历史和 Outbox 必须在一个国内 MySQL 本地事务中完成。
2. 国内发布器轮询 PENDING/RETRY Outbox，使用 HTTPS 443 + mTLS 投递到海外事件入口。
3. 海外先按 eventId 写 Inbox，唯一索引去重，再创建尾程交接记录。
4. 消费失败时不确认；重复投递必须返回相同业务结果。
5. 海外校验通过后写本地 Outbox，异步回传 Accepted/Rejected 回执。
6. 国内收到 Accepted 后才把交接状态标记为 ACCEPTED，但不能回滚已经真实发生的装船事实。
7. 修改交接数据要发布更高 handoverVersion 的新事件，不能覆盖旧快照。
8. 跨区断网时，两个区域本地业务继续运行；Outbox 积压告警，网络恢复后自动补投。

不建议让 firstleg-service 通过 OpenFeign 跨公网同步调用 lastleg-service 创建尾程单。国际链路一次超时就会把真实装船操作拖入不确定状态。

5.4 Topic、事件桥和订单通知

一期不强制引入跨区 MQ，可由 Outbox 发布器直接通过 HTTPS/mTLS 投递；引入 RocketMQ 后，国内和海外各使用独立集群，禁止一个 Broker 集群横跨两区。建议 Topic 如下：

Topic	方向	主要事件
shipment-handover-cn	国内 → 海外	FirstLegShipmentDeparted.v1
shipment-handover-result-os	海外 → 国内	LastMileHandoffAccepted.v1、LastMileHandoffRejected.v1
shipment-milestone-os	海外 → 国内	LastMileMilestoneChanged.v1、LastMileCompleted.v1
security-session-cn	国内 → 海外	会话撤销、账号禁用、权限版本变化

同一尾程聚合以 aggregateId 作为顺序键；只能保证同一聚合有序，不追求全局有序。事件入 Inbox 并提交本地事务后才返回成功，失败采用有上限的指数退避，超过阈值进入死信并告警。

短信、邮件、站内信和企业微信等客户通知不得放在订单事务内同步发送。国内 notification-service 或通知消费者订阅国内订单事件及海外回传的里程碑事件，按 eventId + channel + recipient 幂等发送；承运商回调在海外本地处理，再通过里程碑事件回传国内。

6. Gateway 与流量路由

建议对外保持一个域名，例如 api.example.com，由 CDN/WAF/全局流量入口按路径转发：

路径	目标区域
/api/auth/**	国内 Gateway
/api/platform/v1/iam/**、/api/merchant/v1/iam/**	国内 Gateway
/api/merchant/v1/orders/**、/api/platform/v1/orders/**	国内 Gateway
/api/merchant/v1/first-leg/**、/api/platform/v1/first-leg/**	国内 Gateway
/api/merchant/v1/last-leg/**、/api/platform/v1/last-leg/**	海外 Gateway
海外仓/PDA 专用路径	海外 Gateway

国内 Gateway 只通过国内 Nacos 发现本地服务；海外 Gateway 只通过海外 Nacos 发现本地服务。跨区内部事件入口不暴露在普通业务 Gateway 上，应使用独立内部域名、WAF 白名单、mTLS 和消息签名。

如果暂时没有全局流量产品，可以先使用两个域名：

https://api-cn.example.com
https://api-us.example.com

前端通过同一个 API SDK 根据业务域选择基础地址，不要让浏览器知道 Nacos 服务名。

一期即固定对外域名和证书，域名先指向国内 WAF/负载均衡；计划切换前至少 7 天把 DNS TTL 调整到 300 秒。后期统一域名由全局流量入口按路径转发，auth/iam/order/first-leg 固定国内，last-leg 才允许按灰度规则转发海外。DNS 只负责稳定入口，不用 DNS 权重承担租户或订单级灰度，因为 DNS 缓存无法保证同一业务聚合始终进入同一区域。

灰度期可先使用 api-us-canary.example.com 供指定运营账号和租户验证，正式流量由 Gateway 根据可信的 execution_region 路由。Gateway 必须删除客户端伪造的区域头。若前端需要访问两个域名，CORS 只允许明确的生产前端域名、必要方法和请求头；启用 Cookie 时禁止 Access-Control-Allow-Origin: *，并统一处理预检请求。优先使用同一对外域名，减少浏览器跨域和登录态问题。

7. Nacos 设计

不要使用一个 Nacos 集群横跨国内和海外，也不要让海外服务连接国内 8848。

区域	Nacos	Namespace	Group	注册服务示例
国内	nacos-cn.internal	prod-cn	BAIYUE	gateway、auth、iam、order、firstleg、国内 warehouse/file/integration
海外	nacos-overseas.internal	prod-overseas	BAIYUE	gateway、lastleg、海外 warehouse/file/integration

两个区域可以保留相同服务名，例如都叫 warehouse-service，因为它们位于不同 Nacos 集群。配置必须增加：

REGION_CODE=CN / OVERSEAS
DEPLOYMENT_CELL=prod-cn / prod-overseas
DATA_RESIDENCY=CN / OVERSEAS

当前各服务的 spring.config.import 固定读取 group=BAIYUE，所以两个区域先保持相同 Group，通过独立集群和 Namespace 隔离。若后续希望使用 BAIYUE-CN/BAIYUE-US，必须先把所有服务配置导入 URI 中的 Group 改成环境变量。

生产密钥不得放进 Nacos 明文配置，应进入云 KMS、Secret Manager 或主机受限环境变量。

8. 数据库、Redis 和文件边界

8.1 数据库

• 国内 MySQL：baiyue_auth、baiyue_iam、baiyue_order、baiyue_firstleg、baiyue_warehouse_cn、baiyue_file_cn、baiyue_integration_cn、baiyue_audit_cn、baiyue_print_cn。
• 一期尾程仍在国内使用 baiyue_lastleg_cn，库名提前带区域后缀，避免迁移时混淆数据所有权。
• 海外 MySQL：baiyue_lastleg_os、baiyue_warehouse_os、baiyue_file_os、baiyue_integration_os、baiyue_audit_os、baiyue_print_os。
• 禁止跨区数据库外键、跨区事务和双写。
• 国内只保存海外状态的只读轨迹投影；海外仍是尾程事实的唯一写入者。
• ID 继续使用应用生成的雪花 ID/ULID，避免区域数据库自增 ID 冲突。

数据库迁移优先采用“旧单排空、新单切换”，不移动执行中的尾程聚合。确需迁移历史数据时，先全量复制，再用 Binlog/CDC 追平；切换前短暂停止对应聚合写入，确认延迟为零、行数和关键字段校验一致后，才允许海外库转为主写。国内旧库在回滚观察期保持只读，不得与海外库同时写入。

8.2 Redis 与登录会话

当前各 Servlet 服务会访问 Redis 检查 Access Token 的 jti 会话键。若海外 lastleg-service 直接读取国内 Redis，跨区断网会导致海外所有请求鉴权失败。

推荐目标方案：

1. Auth 使用 RS256/ES256 签发短期 Access Token，海外 Gateway/服务通过 JWKS 本地缓存验签。
2. Access Token 有效期缩短到 10～15 分钟。
3. 登录、撤销、禁用账号发布 SessionIssued/SessionRevoked/AccountDisabled 事件，复制到海外本地 Redis。
4. 海外服务只访问海外 Redis，不访问国内 Redis。

以上改造是海外影子环境上线前置条件，不应放到海外正式切流之后。当前代码仍使用 HS256，并要求通过 Redis 中存在 jti 才允许访问；迁移时先支持带 kid 的 RS256/ES256 Token 和 JWKS 本地缓存，再将海外校验改为“本地验签 + 短有效期 + 本地撤销集合”。私钥只保存在国内 Auth，海外只持有公钥。过渡期国内可短暂兼容旧 Token，但海外灰度账号必须重新登录取得新 Token，稳定后移除 HS256。

PoC 阶段可以通过专线/VPN临时读取国内 Redis，但不能作为正式生产方案；Redis 的 6379 绝不能暴露公网。

8.3 文件

当前本地磁盘文件存储不适合双区域。建议：

• 国内文件进入国内 OSS/COS/S3 兼容桶。
• 海外文件进入海外区域对象存储桶。
• 只复制尾程履约必需的报关资料、BOL、箱单和授权照片。
• 文件下载使用短期预签名 URL，跨区域复制前做病毒扫描、MIME/魔数和 SHA-256 校验。
• POD 等海外原始文件保留在海外，国内保存合规副本或文件引用。

跨境传输企业、联系人、收货地址和报关资料前，应完成数据分类、最小化、访问审计和适用地区的合规评估。

9. 统一客户轨迹

客户不应为了看完整物流轨迹分别查询国内、海外两套数据库。建议国内新增“统一轨迹只读投影”，可以先放在 order-service，后续独立为 tracking-query-service。

头程本地状态 -> 国内轨迹投影
海外 LastMileMilestoneChanged -> 跨区事件 -> 国内轨迹投影
客户 GET /api/merchant/v1/orders/{id}/timeline -> 只查国内投影

轨迹投影允许最终一致，目标延迟 P95 小于 30 秒。页面应展示“最后同步时间”，跨区中断时显示“海外轨迹同步延迟”，不能把旧状态误报成业务失败。

10. integration-service 的区域部署

现有 integration-service 不需要再增加 common-sdk。同一模块按区域配置不同适配器：

国内实例	海外实例
BAIDU_OCR_ENABLED=true	BAIDU_OCR_ENABLED=false
AMAZON_SP_API_ENABLED=false	AMAZON_SP_API_ENABLED=true
国内港务/报关代理适配器	Amazon SP-API、海外海关、码头、车队/承运商适配器

各业务服务只调用内部抽象接口，不直接依赖百度或 Amazon SDK。第三方回调必须校验签名、保存原始回调摘要，并按第三方事件 ID 幂等处理。

11. 网络和安全

1. 国内与海外通过站点到站点 VPN、云企业网或专线连接；跨区业务事件只开放 HTTPS 443。
2. 3306、6379、8848、MQ Broker 端口不得暴露公网。
3. 跨区事件入口使用 mTLS、IP 白名单、时间戳、nonce 和 HMAC/数字签名，防重放。
4. Gateway 清除外部伪造的 X-User-Id、X-Tenant-Id、X-App-Code 等内部头。
5. 国内和海外使用不同数据库账号、Redis密码、内部服务 Token 和对象存储凭证。
6. 所有交接、清关放行、提柜、装车、签收和人工覆盖动作写不可篡改审计日志。
7. 跨区链路设置独立限流、超时、熔断和重试策略，禁止无限重试。

12. 高可用与灾备规格

12.1 正式生产推荐

每个区域至少：

• 2 个应用节点，前置负载均衡/WAF。
• 3 节点 Nacos 集群或云托管注册配置中心。
• MySQL 主备/托管高可用，开启 Binlog 和时间点恢复。
• Redis 高可用或托管版。
• 区域本地 MQ/事件中继服务。
• 区域对象存储和跨可用区备份。

目标建议：核心写接口可用性 99.9%，数据库 RPO ≤ 5 分钟、RTO ≤ 60 分钟，跨区事件 P95 ≤ 30 秒。

12.2 低成本一期过渡

可以先使用国内、海外各一台应用服务器加托管 MySQL/Redis/对象存储，但必须接受单机故障风险，并至少做到：

• Docker Compose 或 systemd 自动拉起。
• 每日全备、持续 Binlog、异地备份。
• HTTPS、WAF/安全组、只开放 80/443。
• Outbox/Inbox、失败重试和人工补投工具先完成。
• 上线前做跨区断网 30 分钟并恢复补投的演练。

13. 分阶段实施顺序

阶段 A：国内完成逻辑拆分并上线

1. 所有服务仍可只部署国内，但按 CN/OVERSEAS 部署单元拆分 Nacos 配置、库名、对象存储目录和服务启动清单。
2. 为尾程聚合增加不可变的 execution_region，创建时确定归属，执行过程中不允许改变。
3. 实现尾程五个阶段的国内版本，并将本地磁盘文件迁到国内对象存储。
4. 国内先使用独立 baiyue_lastleg_cn，禁止尾程表与订单、头程或仓储跨库联表。

阶段 B：在国内打通可靠事件

1. 实现 FirstLegShipmentDeparted.v1、交接回执和里程碑事件。
2. 完成 Outbox 发布器、Inbox 幂等、聚合版本检查、重试、死信、人工补投和通知消费者。
3. 事件桥先在国内回环运行，验证跨服务契约，不把第一次验证留到跨国网络。
4. 完成重复投递、乱序、30 分钟断网、文件复制失败和恢复补投演练。

阶段 C：建立海外影子环境

1. 建立独立海外 Nacos、Gateway、MySQL、Redis、对象存储和监控，不注册到国内 Nacos。
2. 在切流前完成 RS256/ES256 + JWKS、海外本地撤销集合以及对象存储按需复制。
3. 海外服务先只消费脱敏测试事件或生产镜像事件，禁止产生真实外部操作和业务回执。
4. 对比国内结果与海外影子结果，连续 7 天满足数据、权限、性能和事件延迟门槛后才能灰度。

阶段 D：按新尾程聚合灰度

1. 先选择内部测试租户，再按 1% → 10% → 30% → 100% 放量，每档至少观察一个完整业务周期。
2. 只有新创建的尾程聚合进入海外并永久写入 execution_region=OVERSEAS；已经在国内执行的旧单继续留在国内直至完成。
3. Gateway 按聚合归属路由，不按一次请求随机分流；国内订单和统一轨迹查询入口保持不变。
4. 每档验证交接成功率、事件积压、鉴权失败率、文件可用率和租户隔离后再继续放量。

阶段 E：旧单排空与正式收口

1. 国内停止创建新的尾程聚合，只保留旧单处理、查询和应急能力。
2. 旧单全部完成并超过售后观察期后，将 baiyue_lastleg_cn 改为只读归档。
3. 停止临时兼容路由和 HS256，海外成为尾程唯一写入单元；完成灾备和回滚演练后收口。

14. 上线验收门槛

• 国内 Nacos 停止海外注册后，国内服务仍能正常下单和执行头程。
• 国际链路断开时，真实装船操作成功且事件保留在 Outbox，不产生半完成尾程单。
• 网络恢复后，同一事件重复投递 10 次只创建一条尾程交接记录。
• 海外拒绝不完整交接时，国内能收到结构化拒绝原因并进入人工处理。
• 海外里程碑乱序到达时，较旧版本不能覆盖较新状态。
• 海外 MySQL/Redis短暂不可用时，不影响国内订单和头程。
• 商户 A 不能访问商户 B 的交接、柜、货物、文件和 POD。
• 未授权用户即使直接调用清关放行、装车、签收接口也返回 403。
• POD、清关资料和装柜照片下载均使用短期授权并留下审计记录。
• 跨区事件积压、死信、延迟和回执缺失均有告警和补投手册。

14.1 灰度继续和回滚阈值

• 继续放量：跨区事件 P95 小于 30 秒、P99 小于 2 分钟，交接成功率不低于 99.9%，Inbox 重复创建业务记录为 0，必需文件 SHA-256 校验通过率 100%。
• 暂停放量：最老 Outbox 积压超过 5 分钟、海外接口 P95 比国内基线升高 30%、新增 401/403 比基线升高 0.2 个百分点，或出现无法自动补投的死信。
• 立即回滚：连续 5 分钟 5xx 超过 1%、发现跨租户访问、数据丢失/重复写入、错误业务状态推进或关键文件不可恢复。
• 回滚先停止创建新的海外聚合，已有海外聚合原则上继续由海外处理，不能直接路由到国内旧库。若海外无法继续写入，必须先冻结写入，通过反向事件或 CDC 补齐国内应急库并校验后再切回；禁止两区同时写同一聚合。
• 国内旧库、旧版本应用和路由配置至少保留 7 天回滚观察期。每次切换和回滚均记录审批人、时间点、数据校验结果和路由版本。

15. 近期 P0 清单

当前 P0 基线：部署聚合入口、公共事件契约和事件桥 Inbox 幂等基础骨架已经生成；头程真实发运、尾程聚合、可靠发布传输、统一轨迹和通知仍未闭环。

1. P0-01：冻结装船发运交接点和 FirstLegShipmentDeparted.v1 字段，给尾程聚合增加不可变 execution_region、聚合版本和唯一幂等键。验收：重复交接只创建一个聚合，旧版本不能覆盖新版本。
2. P0-02：完成头程到仓、测量、排柜、订舱、装柜、报关和装船发运最小流程，生成带版本与摘要的不可变交接快照。验收：前置条件不满足不能发运，关键证据可审计。
3. P0-03：在现有 event-bridge-service 基础上补齐 Outbox 扫描和发布状态机、有限重试、死信、人工补投及指标。验收：业务提交和事件不丢失，进程重启后可继续投递。
4. P0-04：实现 Inbox 到尾程业务消费者和接受/拒绝回执，并完成尾程到港前、到港、到仓、出仓、签收五阶段。验收：重复、乱序、坏摘要和非法状态流转均有自动化测试。
5. P0-05：先在国内回环打通事件桥，完成事件签名、来源白名单和 mTLS；RocketMQ 发布消费与真实跨区 HTTPS 投递按最终传输选型实现。验收：断网 30 分钟后可自动恢复补投，链路无跨库和同步跨区 Feign。
6. P0-06：将文件存储抽象为对象存储，完成版本、病毒扫描、SHA-256 和短期下载授权。验收：交接所需文件可按清单受控复制且下载有租户审计。
7. P0-07：把 JWT 改为 RS256/ES256 + JWKS，移除海外服务对国内 Redis 正向会话键的依赖。验收：海外断开国内 Redis 后仍可校验短期令牌和本地撤销信息。
8. P0-08：建立 CN/OVERSEAS 配置模板、区域化数据库名和 REGION_CODE/DEPLOYMENT_CELL/DATA_RESIDENCY 启动校验。验收：区域错配时服务拒绝启动，两区不共享 MySQL、Redis 和 Nacos。
9. P0-09：实现国内统一轨迹投影和异步订单通知。验收：重复不新增、乱序不回退、通知失败不回滚业务且可死信补投。
10. P0-10：建立覆盖断网、重复、乱序、跨租户、文件失败和回滚的自动化验收。验收：国内回环全部通过后才允许建设海外影子环境。

16. 最终建议

现在最合适的落地路线不是立即购买很多服务器，而是先完成三个基础能力：

1. 把 firstleg-service 的真实“装船发运”节点做出来。
2. 把现有 Outbox 表补成可发布、可重试、可告警的可靠事件链路。
3. 在国内先为 lastleg-service 实现 Inbox + 交接回执并验证五个尾程阶段，再将同一部署单元迁到海外影子环境。

完成这三项后，国内和海外才能真正成为两个可以独立运行、网络中断后仍可恢复的业务单元。