docs(spec): 补联调环境实测——平台必填占位符清单与四类闸门行为

- §16.3:补平台 yml 无默认值的必填占位符(CONFIG_API/FRONTDOMAIN、
  SSW_BOXDEPLOYER_*)与联调取值;DB/Redis 账号密码走 yml 默认值,不落命令行
- §16.3:补 2026-10-24 实测的平台闸门四象限(无头→code600 / 协议不兼容→HTTP401 /
  白名单内部端点→仅需 X-Internal-Token / 非白名单→仍需登录态)
- §16.3:明确连接器出向须区分「白名单内部端点」与「普通端点」

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-24 12:13:07 +08:00
1 parent d03eedd959
commit b418621314
1 file changed
+23 -2
@@ -1028,11 +1028,32 @@ P5 的策略闸门依赖 P3;P6 依赖全部后端阶段。
| TDS 库 | `tds2`(新建于 `jnpf-postgres`,135 个迁移零失败,**45 张表**) |
| TDS 端口 | `30041`(避开连接器 `30000` 与旧版 TDS `30040`) |
| fat jar | `/tmp/sswtds-probe/boot/ssw-tds-admin/target/ssw-tds-admin-7.0.0-RELEASE.jar`(386 MB) |
| 关键环境变量 | `TDS_DB=tds2` · `SERVER_PORT=30041` · `DB_HOST=127.0.0.1` · `DB_PORT=15432` · `REDIS_HOST=127.0.0.1` · `REDIS_PORT=16379` · `CONFIG_APIDOMAIN` · `CONFIG_FRONTDOMAIN` · `SSW_INTERNAL_TOKEN` |
| 关键环境变量 | `TDS_DB=tds2` · `SERVER_PORT=30041` · `DB_HOST=127.0.0.1` · `DB_PORT=15432` · `REDIS_HOST=127.0.0.1` · `REDIS_PORT=16379` · `CONFIG_APIDOMAIN` · `CONFIG_FRONTDOMAIN` |
| 依赖 | `jnpf-postgres`(15432)· `jnpf-redis`(16379) |
连接器侧联调变量:`SSW_TDS_BASE_URL=http://127.0.0.1:30041`(+ 同名 `SSW_INTERNAL_TOKEN`)。
注意平台 `CONFIG_APIDOMAIN` **无默认值**,缺省会启动失败——联调时必须显式给。
⚠️ 平台 yml 里**无默认值的必填占位符**(缺任一个 ⇒ **启动失败**,与「连不上」无关):
| 变量 | 联调时取值 | 说明 |
|---|---|---|
| `CONFIG_APIDOMAIN` | `http://127.0.0.1:30041` | 无默认,缺则起不来 |
| `CONFIG_FRONTDOMAIN` | `http://127.0.0.1:30041` | 同上 |
| `SSW_BOXDEPLOYER_PLATFORM_BASE` | `http://127.0.0.1:30041` | 盒 TDC 回连基址(本机联调填平台自身即可) |
| `SSW_BOXDEPLOYER_REDIS_HOST` | `127.0.0.1` | 盒 TDC 会话/租户引导 Redis |
| `SSW_BOXDEPLOYER_J7_INITIAL_PASSWORD` | 任意占位 | 盒自有 j7 预置口令;**平台侧运行期不消费**,联调填哑值即可 |
| `SSW_INTERNAL_TOKEN` | 两端必须一致 | 缺省 `ssw-internal-token-e2e`(公开弱口令,见 §5.2 护栏) |
**2026-10-24 实测的平台闸门行为**(`curl --noproxy '*'`,TDS :30041):
| 请求 | 实测响应 | 结论 |
|---|---|---|
| 无任何头,打 `GET /api/ssw/tds/Connector/All` | HTTP 200 + `{code:600,"msg":"登录过期,请重新登录"}` | 非白名单路径 ⇒ **HTTP 200 + code 600**,不是 401 |
| `X-Protocol-Version: 9.0` + 合法 token | **HTTP 401** + `{code:401,"msg":"跨端协议版本不兼容(对端 9.0,本端 1.0),请升级对端"}` | 协议闸门 fail-closed,**在白名单 stop() 之前** |
| `X-Internal-Token` + `X-Protocol-Version: 1.0`,打**白名单**内部端点(`SpaceMember/Internal/RoleOf`、`Connector/Internal/EnvReport`、`Contract/Internal/Negotiations`) | HTTP 200 + 业务错(`"subjectId/spaceId 必填"` / `"connectorId 必填"`) | 白名单内部端点**只认 `X-Internal-Token` 即可过网关**(不校验 `SA-SAME-TOKEN`) |
| `X-Internal-Token` + `X-Protocol-Version: 1.0`,打**非白名单**端点(`Connector/All`) | HTTP 200 + `{code:600}` | 🔴 **光有 `X-Internal-Token` 不够**:平台内部请求分支校验的是 `SA-SAME-TOKEN`,非白名单路径另需登录态 |
⇒ 连接器出向客户端**必须区分「白名单内部端点」与「普通端点」**:前者只带内部令牌,后者还需 `SA-SAME-TOKEN` 或用户会话。
---