docs: document running the jar against the integration YAML

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-19 09:38:24 +08:00
parent 5f09fa0666
commit e065e48ecc
1 changed files with 27 additions and 0 deletions
@@ -78,6 +78,33 @@ java -jar target/admin-api-1.2.1-SNAPSHOT.jar
 java -jar target/admin-api-1.2.1-SNAPSHOT.jar --spring.profiles.active=test
 ```

+### 联调环境（msgexchange-v2 integration）
+
+宿主机使用独立配置 `../msgexchange-v2/deploy/integration/admin-api.yml`，**不加载**内置 `dev`/`test`/`pro` 地址。YAML 通过 `${TEST_SERVER_HOST}` 指向中间件：MySQL `13307`（Primary）、PostgreSQL `15432`（Secondary）、Elasticsearch `19300`。
+
+前置条件：
+
+- JDK 8
+- 可执行 JAR 必须包含兼容该运行时的 `org.postgresql:postgresql` 驱动；单改 YAML 无法替代。用 `./build.sh` 或带 `../chengdu-repository` 的 `mvn package` 构建，见 [构建说明](docs/build.md)
+- 中间件栈已在 `msgexchange-v2` 启动：`export TEST_SERVER_HOST=你的服务器IP` 后执行 `docker compose -f compose.integration.yaml up -d`
+- `TEST_SERVER_HOST` 必须是应用机能访问的服务器 IP 或域名，**不能**填写 `0.0.0.0`
+
+在 `admin-api` 仓库根目录执行：
+
+```bash
+export TEST_SERVER_HOST=你的服务器IP
+java -jar target/admin-api-1.2.1-SNAPSHOT.jar \
+  --spring.profiles.active=localtest \
+  --spring.config.location="file:$PWD/../msgexchange-v2/deploy/integration/admin-api.yml" \
+  --logging.config="file:$PWD/../msgexchange-v2/deploy/integration/logback.xml"
+```
+
+`localtest` + `spring.config.location` 避免加载内置环境地址。服务监听 `0.0.0.0:18080`，Eureka 关闭，两侧 JPA 均为 `ddl-auto: none`。启动日志需确认 Primary 为 MySQL、Secondary 为 PostgreSQL。
+
+验证：`http://localhost:18080/doc.html`，冒烟 `curl http://localhost:18080/dictionary/datadicItems/ROUTE_TYPE`。
+
+sys-api 不在本栈，依赖它的操作日志开关接口会失败（预期，不以假响应掩盖）。空库上的基础数据、季度计划、字典和历史查询可能因缺表或缺索引失败；Primary 需另行导入测试结构与脱敏数据。完整栈说明见 `msgexchange-v2/deploy/integration/README.md`。
+
 ### 验证

 ```bash