提交

2026-08-26 19:46:14 +08:00
parent 63182a2b88
commit 3975759458
22 changed files with 446 additions and 75 deletions
@@ -1,66 +1,62 @@
-# 数据库环境切换说明
+# Nacos 环境切换说明

-## 环境定义
+数据库、Redis 和服务地址均由所选环境的 Nacos 配置决定。本地启动时只切换
+Nacos 地址与 namespace，不再通过 `application-test.yml` 单独切换数据库。

- `dev`：本地开发环境，连接 `127.0.0.1:3306`，默认账号为 `root/123456`。
- `test`：联调测试环境，连接 `8.163.30.128:3306`，各微服务仍使用独立数据库。
+## 环境映射

-所有服务默认使用 `dev`：
+| Maven Profile | Nacos 地址 | Namespace |
+| --- | --- | --- |
+| `local` | `127.0.0.1:8848` | `public` |
+| `dev` | `dev-nacos.buggoglobal.com:8848` | `DEV_NACOS_NAMESPACE` |
+| `test` | `8.163.30.128:8848` | `d99d7998-5bb0-4ffe-a2a0-1a564ce14463` |

-```yaml
-spring:
-  profiles:
-    active: ${SPRING_PROFILES_ACTIVE:dev}
+本地 Nacos 使用 `nacos/nacos`。开发和测试密码不写入 Git，需在启动 IDEA
+之前设置一次用户环境变量：
+
+```powershell
+[Environment]::SetEnvironmentVariable('DEV_NACOS_PASSWORD', '<开发 Nacos 密码>', 'User')
+[Environment]::SetEnvironmentVariable('TEST_NACOS_PASSWORD', '<测试 Nacos 密码>', 'User')
+[Environment]::SetEnvironmentVariable('DEV_NACOS_NAMESPACE', '<开发海外 namespace>', 'User')
 ```

-建议不要直接修改配置文件。通过 IDEA 的启动配置设置 `Active profiles` 即可切换：
+设置后完全退出并重新打开 IDEA，使 Maven 能读取新环境变量。

- 本地数据库：`dev`
- 测试数据库：`test`
+## IDEA 中切换

-也可以使用启动参数：
+1. 在 Maven 面板的 `Profiles` 中，`local`、`dev`、`test` 只勾选一个。
+2. 重新加载 Maven 项目。
+3. 在目标服务的 Maven `Plugins > spring-boot > spring-boot:run` 启动。

-```text
--spring.profiles.active=test
+例如海外查询链路需要分别启动 `gateway-overseas`、`lastleg-service` 和
+`warehouse-overseas-service`。已经运行的进程不会自动切换环境，切换 Profile
+后必须停止并重新启动。
+
+IDEA 普通绿色 Run 按钮不执行 Maven，因此不会读取 Maven Profile。需要继续使用
+绿色 Run 时，请在 Run Configuration 的 Environment variables 中设置
+`NACOS_SERVER_ADDR`、`NACOS_NAMESPACE`、`NACOS_USERNAME` 和 `NACOS_PASSWORD`。
+`gateway-overseas` 已默认启用 `overseas` Spring Profile。
+
+## PowerShell 中切换
+
+也可以在当前终端加载同一套变量，然后从同一终端启动服务：
+
+```powershell
+. .\scripts\use-nacos-environment.ps1 -Environment local -Region overseas
+. .\scripts\use-nacos-environment.ps1 -Environment dev -Region overseas
+. .\scripts\use-nacos-environment.ps1 -Environment test -Region overseas
 ```

-## 测试数据库密码
+脚本读取 `DEV_NACOS_PASSWORD`、`TEST_NACOS_PASSWORD`，namespace 优先读取
+`*_OVERSEAS_NACOS_NAMESPACE`，未设置时读取 `*_NACOS_NAMESPACE`。命令前面的点和
+空格不能省略，否则变量只存在于脚本子进程中。

-测试数据库密码不写入 Git。启动 `test` 环境前，在 IDEA 启动配置的环境变量中设置：
+## 当前限制

-```text
-TEST_DB_PASSWORD=测试数据库密码
-```
-
-公共测试连接参数支持覆盖：
-
-```text
-TEST_DB_HOST=8.163.30.128
-TEST_DB_PORT=3306
-TEST_DB_USERNAME=root
-TEST_DB_PASSWORD=测试数据库密码
-```
-
-每个服务还支持使用自己的 `*_TEST_DB_URL`、`*_TEST_DB_USERNAME` 和 `*_TEST_DB_PASSWORD` 覆盖公共参数。
-
-## 分库映射
-
-| 服务 | 测试数据库 |
-| --- | --- |
-| 认证服务 | `baiyue_auth` |
-| 权限服务 | `baiyue_iam` |
-| 订单服务 | `baiyue_order` |
-| 仓库服务 | `baiyue_warehouse` |
-| 头程履约服务 | `baiyue_firstleg` |
-| 文件服务 | `baiyue_file` |
-| 审计服务 | `baiyue_audit` |
-| 事件桥接服务 | `baiyue_event_bridge` |
-
-网关、打印和集成服务没有业务数据库，但同样支持 `dev/test` Profile。网关在两种环境下都会自动加载 `cn` 路由配置。
-
-## 注意事项
-
- `test` 只切换数据库，Nacos 和 Redis 默认仍连接本机。
- 环境变量优先级高于配置文件，可用于临时覆盖单个服务。
- 修改 IDEA 环境变量后需要重启对应服务。
- 不要把测试数据库密码提交到配置文件、启动脚本或 Git。
+- 测试 Nacos 的 `8848` 客户端端口已确认可连接。
+- 开发 Nacos 网页控制台可访问，但 `dev-nacos.buggoglobal.com:8848` 当前从本机
+  无法连接。需要开放 Nacos 客户端端口以及 Nacos 2.x/3.x 所需的 gRPC 端口，
+  或提供一个客户端可访问的内部地址。
+- 国内和海外存在同名 Data ID，远程环境必须使用各自独立 namespace。开发海外
+  namespace 尚未确认，因此通过 `DEV_NACOS_NAMESPACE` 在本机配置。
+- 不要同时勾选多个环境 Profile；Maven 对同名属性的最终取值不直观，容易连错环境。