docs/双区域部署与Nacos规划.md

双区域部署与 Nacos 规划

1. 适用范围与结论

本文冻结国内头程与海外仓服务在开发、测试和生产环境中的部署拓扑、Nacos、数据库及 Event Bridge 边界。账号、Token、API 路由和事件语义继续以《跨区域认证与服务通信契约》为准。

当前结论：

• 开发、测试采用单宿主机共置：同一环境内同时部署国内 Compose 与海外 Compose，通过独立容器、网络、端口、Nacos Namespace 和数据库 Schema 隔离。
• 生产采用国内、海外两套独立区域控制面：各自使用本区域 Nacos 集群、数据库和 Redis，不允许海外服务跨境依赖国内 Nacos、MySQL 或 Redis。
• 跨区域只开放双区域 API、JWKS 公钥和 Event Bridge 接收入口，不使用跨区域服务发现。

2. 环境拓扑

环境	宿主与网络	Nacos	数据库	适用目的
development	单宿主机共置国内/海外 Compose	一套开发 Nacos，国内/海外独立 Namespace	可共用一个开发 MySQL 实例，但必须使用独立 Schema	日常开发联调
test	单宿主机共置国内/海外 Compose	一套测试 Nacos，国内/海外独立 Namespace	可共用一个测试 MySQL 实例，但必须使用独立 Schema	集成测试和验收
production-cn	国内独立部署单元	国内高可用 Nacos 集群	国内独立 MySQL/Redis	Auth、IAM、头程、国内仓和 Finance
production-overseas	海外独立部署单元	海外高可用 Nacos 集群	海外独立 MySQL/Redis	海外 Gateway、Lastleg 和海外 Warehouse

如果开发与测试实际共用同一套 Nacos 实例，必须创建四个 Namespace，不得复用：

development-cn
development-overseas
test-cn
test-overseas

Namespace 名称不是服务名。环境变量必须填写 Nacos 实际 Namespace ID；控制台自动生成 UUID 时使用 UUID，不使用展示名称代替。

3. 服务归属

3.1 国内区域

• gateway、auth-service、iam-service
• firstleg-service、order-service、finance-service
• 国内 warehouse-service、file-service、audit-service 等公共服务
• 国内 Event Bridge，用于接收目标区域为 CN 的事件并投递本地 Firstleg

3.2 海外区域

• gateway-overseas
• lastleg-service，同时持有 baiyue_lastleg 内的 IAM 安全事件 Inbox/投影，并开放内部事件接收和实时校验端点
• warehouse-overseas-service
• 海外 Event Bridge，用于接收目标区域为 OVERSEAS 的事件；业务事件和三类 IAM 安全事件按事件类型投递 Lastleg 的不同内部入口

海外浏览器请求直接进入海外 Gateway，不经过国内 Gateway。Auth 仍只部署在国内；海外服务通过受控 JWKS 地址验证 Auth 签发的短时海外 Token，不访问国内 Redis。

4. Nacos 规划

4.1 开发与测试

非生产环境允许一套 Nacos 实例承载多个 Namespace。国内配置发布自 baiyue-firstleg/config/nacos/cn/，海外配置发布自 baiyue-firstleg/config/nacos/overseas/，相同 Data ID 依靠 Namespace 隔离。

国内环境变量：

NACOS_SERVER_ADDR=<当前环境Nacos地址>
NACOS_NAMESPACE=<当前环境国内Namespace ID>
REGION_CODE=CN
DEPLOYMENT_CELL=<environment>-cn
DATA_RESIDENCY=CN

海外环境变量：

OVERSEAS_NACOS_SERVER_ADDR=<当前环境Nacos地址>
OVERSEAS_NACOS_NAMESPACE=<当前环境海外Namespace ID>
OVERSEAS_DEPLOYMENT_CELL=<environment>-overseas

海外 Compose 必须强制传入 REGION_CODE=OVERSEAS 和 DATA_RESIDENCY=OVERSEAS，不得继承共享文件中的国内默认值。

4.2 生产

生产国内、海外分别部署本区域 Nacos 集群。服务只注册到本区域，不同步或复制临时服务注册表，也不通过公网访问另一地区 Nacos。

# 国内生产凭据
NACOS_SERVER_ADDR=<国内Nacos内网地址>
NACOS_NAMESPACE=<production-cn Namespace ID>

# 海外生产凭据
OVERSEAS_NACOS_SERVER_ADDR=<海外Nacos内网地址>
OVERSEAS_NACOS_NAMESPACE=<production-overseas Namespace ID>

生产 Nacos 必须启用认证、网络 ACL 和持久化；不暴露公网管理端口。数据库密码、JWT 私钥、内部服务 Token 和第三方密钥不得写入 Nacos 明文，继续由 Jenkins Credentials 或生产密钥管理系统注入。

5. 数据库隔离

开发、测试即使共用一个 MySQL 实例，也必须保持以下 Schema 独立：

区域	服务	Schema
国内	Event Bridge	baiyue_event_bridge
海外	Event Bridge	baiyue_event_bridge_overseas
海外	Lastleg	baiyue_lastleg
海外	Warehouse	baiyue_lastlag_warehouse

生产必须进一步使用区域内独立数据库实例或集群。国内服务不得查询海外 Schema，海外服务不得查询国内 Schema；跨区域事实只通过版本化事件或已确认的受保护内部接口传递。

6. Event Bridge 双实例

每个区域部署一个相同制品、独立数据库的 Event Bridge：

Firstleg Outbox
  -> 海外 Event Bridge Inbox
  -> Lastleg 本地消费者

Lastleg Outbox
  -> 国内 Event Bridge Inbox
  -> Firstleg 本地消费者

国内 Firstleg 配置海外 Bridge 基础地址，Feign 自动追加接收路径：

LASTLEG_EVENT_BRIDGE_URL=<海外Event Bridge基础地址>

海外 Lastleg 配置国内 Bridge 基础地址：

FIRSTLEG_EVENT_BRIDGE_URL=<国内Event Bridge基础地址>

区域内消费者使用本地服务地址：

# 海外 Bridge
EVENT_CONSUMER_URL=http://lastleg-service:9303/internal/lastleg/events

# 国内 Bridge
FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL=http://firstleg:9202/internal/firstleg/v1/container-events

跨区域 Bridge 接收入口使用 TLS、内部服务身份、网络白名单和幂等校验；不得暴露数据库或消费者内部接口。

7. Jenkins 与环境文件

开发、测试可以各用一份 Secret File，同时包含国内和海外非敏感路由变量；Compose 负责选择本区域变量。生产必须拆分凭据：

firstleg-production-cn-env
firstleg-production-overseas-env

生产海外部署不得读取国内数据库、Redis 或 Nacos 地址。Event Bridge 同一制品需要按 CN、OVERSEAS 两个部署单元分别发布，使用不同 Compose Project、容器名、端口和数据库。

8. 当前仓库实施差距

目标架构已冻结，但当前部署代码仍需完成以下收敛：

1. docker-compose.overseas.yml 当前仍从 NACOS_SERVER_ADDR 取值，应改为显式使用 OVERSEAS_NACOS_SERVER_ADDR。
2. deploy/scripts/deploy-built-service.sh 与 deploy-services.sh 的海外服务门禁应校验 OVERSEAS_NACOS_SERVER_ADDR。
3. Jenkins 生产配置需要拆分国内/海外 Secret File，并为 Event Bridge 提供明确区域部署参数或独立 Job。
4. 海外 Nacos Namespace 创建、配置发布、JWKS 可达性和双向 Event Bridge 真实投递必须分别验收，不能以容器健康检查代替。

这些差距未完成前，不得声称生产双区域部署已就绪。