165 lines
7.0 KiB
Markdown
165 lines
7.0 KiB
Markdown
# 双区域部署与 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`
|
||
- 海外 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 真实投递必须分别验收，不能以容器健康检查代替。
|
||
|
||
这些差距未完成前，不得声称生产双区域部署已就绪。
|