diff --git a/README.md b/README.md index 8bc5586..101a09b 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ ## 跨阶段参考 - [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。 +- [双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。 - [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。 - [AI 工程执行与协作约束](AI工程执行与协作约束.md)：临时目录、依赖复用、当前开发阶段、部署数据库授权、质量门禁和独立任务协作规则。 - [财务管理闭环盘点与范围建议](财务管理/README.md)：基于当前入库计费、财务原型和现有代码盘点财务闭环、缺口及建议的首期应收边界。 diff --git a/双区域部署与Nacos规划.md b/双区域部署与Nacos规划.md new file mode 100644 index 0000000..635935c --- /dev/null +++ b/双区域部署与Nacos规划.md @@ -0,0 +1,164 @@ +# 双区域部署与 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` +- `warehouse-overseas-service` +- 海外 Event Bridge，用于接收目标区域为 `OVERSEAS` 的事件并投递本地 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=-cn +DATA_RESIDENCY=CN +``` + +海外环境变量： + +```dotenv +OVERSEAS_NACOS_SERVER_ADDR=<当前环境Nacos地址> +OVERSEAS_NACOS_NAMESPACE=<当前环境海外Namespace ID> +OVERSEAS_DEPLOYMENT_CELL=-overseas +``` + +海外 Compose 必须强制传入 `REGION_CODE=OVERSEAS` 和 `DATA_RESIDENCY=OVERSEAS`，不得继承共享文件中的国内默认值。 + +### 4.2 生产 + +生产国内、海外分别部署本区域 Nacos 集群。服务只注册到本区域，不同步或复制临时服务注册表，也不通过公网访问另一地区 Nacos。 + +```dotenv +# 国内生产凭据 +NACOS_SERVER_ADDR=<国内Nacos内网地址> +NACOS_NAMESPACE= + +# 海外生产凭据 +OVERSEAS_NACOS_SERVER_ADDR=<海外Nacos内网地址> +OVERSEAS_NACOS_NAMESPACE= +``` + +生产 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 真实投递必须分别验收，不能以容器健康检查代替。 + +这些差距未完成前，不得声称生产双区域部署已就绪。 diff --git a/测试环境Jenkins部署指南.md b/测试环境Jenkins部署指南.md index b9b1d9d..7bd20e6 100644 --- a/测试环境Jenkins部署指南.md +++ b/测试环境Jenkins部署指南.md @@ -3,6 +3,8 @@ > 最后核对：2026-08-11 > > 本文供 Codex 对话和项目维护人员部署虫虫出海测试环境使用。只适用于测试环境，不适用于预发布或生产。 +> +> 开发、测试环境内国内/海外服务同机共置，以及生产双区域 Nacos 和 Event Bridge 目标拓扑，统一见[双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)；本文只维护测试环境 Jenkins 操作步骤。 ## 1. 人工部署默认与 Codex 授权边界 diff --git a/跨区域认证与服务通信契约.md b/跨区域认证与服务通信契约.md index f068f78..f24b590 100644 --- a/跨区域认证与服务通信契约.md +++ b/跨区域认证与服务通信契约.md @@ -4,6 +4,7 @@ - 本契约适用于 Admin、Client、国内头程服务、海外网关、尾程服务、海外仓资源服务及跨区域事件桥接。 - 业务范围仍按对应阶段和模块文档确定；本文件只冻结跨区域账号、请求路由、服务鉴权和事件通信边界。 +- 开发/测试同机共置及生产国内/海外双控制面的实际部署拓扑、Nacos、数据库和 Event Bridge 规划见[双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)。 ## 统一账号与 Token