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，不得复用：

```text
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`
- 海外 `file-service`，独占海外 RDS 中的 `baiyue_file`，只访问海外本区域私有 OSS Bucket；详细边界见《[阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)》
- 海外 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 隔离。

国内环境变量：

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

海外环境变量：

```dotenv
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。

```dotenv
# 国内生产凭据
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：

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

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

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

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

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

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

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

```dotenv
# 海外 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 负责选择本区域变量。生产必须拆分凭据：

```text
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 真实投递必须分别验收，不能以容器健康检查代替。
5. 海外 Gateway 和 Nacos 已存在 File Service 入口，但海外统一 SQL 与部署清单尚未包含海外 `file-service`、`baiyue_file`；OSS 接入实施前必须补齐并完成区域内真实上传、下载和双实例读取验收。

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