API 部署 BgFilter 验活 URL 缺省时从已校验 env 派生

Jenkins job 不传 --bgfilter-worker-health-url，旧默认值固定 8083 会把
父子 env 已对齐的合法自定义端口在切 current 前错误阻断。缺省时改为在
预检中从已校验的 worker HOST/PORT 派生 readiness URL；显式传入时仍
严格三方比对，配置漂移照旧 fail-closed。守卫测试默认改为不传该 flag
以对齐真实 Jenkins 调用形态，另保留显式匹配放行与显式漂移拒绝用例。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

scripts/check-production-api-deploy.mjs

@@ -115,7 +115,11 @@ function assertDeployScriptSupportsProtectedEnvCleanup() {
 
 function assertSuccessfulDeployCanKeepMaintenance() {
   const fixture = prepareFixture('keep-maintenance-after-success');
-  const result = runDeploy(fixture, { keepMaintenance: true });
+  // 显式传入与父子 env 一致的 readiness URL：覆盖"显式匹配仍放行"的路径。
+  const result = runDeploy(fixture, {
+    keepMaintenance: true,
+    bgfilterWorkerHealthUrl: 'http://127.0.0.1:18083/readyz',
+  });
 
   assertStatus(result, 0, '显式保持维护时完整 fixture 应部署成功。');
   if (result.status !== 0) {
@@ -482,7 +486,7 @@ function assertDeployCopiesPingoraDirectReleaseDependencies() {
   assertIncludes(
     commandsLog,
     'curl -fsS --max-time 2 http://127.0.0.1:18083/readyz',
-    '部署脚本必须在重启父进程前验活 BgFilter worker。',
+    '部署脚本必须在重启父进程前验活 BgFilter worker；缺省 flag 时 readiness URL 必须从已校验 env 派生自定义端口。',
   );
   const bgfilterReadyIndex = commandsLog.indexOf(
     'curl -fsS --max-time 2 http://127.0.0.1:18083/readyz',
@@ -2472,8 +2476,11 @@ function runDeploy(fixture, options = {}) {
     fixture.externalGenerationWorkerEnvFile,
     '--bgfilter-worker-env-file',
     fixture.bgfilterWorkerEnvFile,
-    '--bgfilter-worker-health-url',
-    options.bgfilterWorkerHealthUrl ?? 'http://127.0.0.1:18083/readyz',
+    // 缺省不传 --bgfilter-worker-health-url，与真实 Jenkins 调用一致：
+    // 让预检从已校验的 worker env HOST/PORT 派生 readiness URL。
+    ...(options.bgfilterWorkerHealthUrl === undefined
+      ? []
+      : ['--bgfilter-worker-health-url', options.bgfilterWorkerHealthUrl]),
     '--database',
     'genarrative-prod',
     '--spacetime-server-url',

scripts/deploy/production-api-deploy.sh

@@ -5,11 +5,12 @@ set -euo pipefail
 usage() {
   cat <<'EOF'
 用法:
-  ./scripts/deploy/production-api-deploy.sh --source-dir build/<version> [--version <version>] [--release-root /opt/genarrative/releases] [--current-link /opt/genarrative/current] [--service genarrative-api.service] [--pingora-service genarrative-pingora-gateway.service] [--require-pingora-gateway] [--bgfilter-worker-service genarrative-bgfilter-worker.service] [--bgfilter-worker-health-url http://127.0.0.1:8083/readyz] [--bgfilter-worker-env-file /etc/genarrative/bgfilter-worker.env] [--no-bgfilter-worker] [--worker-service-pattern 'genarrative-external-generation-worker@*.service'] [--no-worker-services] [--worker-controller-service genarrative-external-generation-controller.service] [--no-worker-controller] [--health-url http://127.0.0.1:8082/readyz] [--api-env-file /etc/genarrative/api-server.env] [--worker-env-file /etc/genarrative/external-generation-worker.env] [--database genarrative-prod] [--spacetime-server-url http://127.0.0.1:3101] [--keep-maintenance-mode]
+  ./scripts/deploy/production-api-deploy.sh --source-dir build/<version> [--version <version>] [--release-root /opt/genarrative/releases] [--current-link /opt/genarrative/current] [--service genarrative-api.service] [--pingora-service genarrative-pingora-gateway.service] [--require-pingora-gateway] [--bgfilter-worker-service genarrative-bgfilter-worker.service] [--bgfilter-worker-health-url <url>] [--bgfilter-worker-env-file /etc/genarrative/bgfilter-worker.env] [--no-bgfilter-worker] [--worker-service-pattern 'genarrative-external-generation-worker@*.service'] [--no-worker-services] [--worker-controller-service genarrative-external-generation-controller.service] [--no-worker-controller] [--health-url http://127.0.0.1:8082/readyz] [--api-env-file /etc/genarrative/api-server.env] [--worker-env-file /etc/genarrative/external-generation-worker.env] [--database genarrative-prod] [--spacetime-server-url http://127.0.0.1:3101] [--keep-maintenance-mode]
 
 说明:
   进入维护模式，校验并发布 api-server 单文件，更新 current 链接，重启 systemd 服务并执行 readiness 检查。
   默认先停止、启动并验活唯一 BgFilter worker，再重启 API、外部生成 worker controller 和已加载的 worker 实例。
+  --bgfilter-worker-health-url 缺省时从已校验的 worker env HOST/PORT 派生；显式传入时必须与父子 env 三方一致，否则预检失败。
   若传入 --database，会在重启前把 GENARRATIVE_SPACETIME_DATABASE 写入 api-server 环境文件，避免服务继续读取旧库。
   若发布包包含 pingora-gateway，或传入 --require-pingora-gateway，部署脚本会要求 release manifest、二进制与 checksum 一致，再在 current 链接切换后先复核 systemd/env 仍是本机高端口 shadow 配置，启动或重启 Pingora 影子服务并复核 active。
   默认在 readiness 通过后退出维护模式；传入 --keep-maintenance-mode 时保留维护文件，供人工验收后再恢复公网。
@@ -634,8 +635,11 @@ validate_bgfilter_loopback_endpoint_alignment() {
   fi
 
   expected_health_url="${expected_base_url}/readyz"
-  if [[ "${health_url}" != "${expected_health_url}" ]]; then
-    echo "[production-api-deploy] --bgfilter-worker-health-url 必须与父进程 base URL 和子 worker listener 指向同一 loopback endpoint: expected=${expected_health_url}, actual=${health_url:-<empty>}" >&2
+  if [[ -z "${health_url}" ]]; then
+    # 合法自定义端口不应仅因调用方未重复传入可派生值而阻断发布（Jenkins job 不传该 flag）。
+    BGFILTER_WORKER_HEALTH_URL="${expected_health_url}"
+  elif [[ "${health_url}" != "${expected_health_url}" ]]; then
+    echo "[production-api-deploy] --bgfilter-worker-health-url 必须与父进程 base URL 和子 worker listener 指向同一 loopback endpoint: expected=${expected_health_url}, actual=${health_url}" >&2
     return 1
   fi
 }
@@ -1083,7 +1087,8 @@ PINGORA_SERVICE_NAME="genarrative-pingora-gateway.service"
 WORKER_SERVICE_PATTERN="genarrative-external-generation-worker@*.service"
 WORKER_CONTROLLER_SERVICE="genarrative-external-generation-controller.service"
 BGFILTER_WORKER_SERVICE="genarrative-bgfilter-worker.service"
-BGFILTER_WORKER_HEALTH_URL="http://127.0.0.1:8083/readyz"
+# 缺省时在预检阶段从已校验的 worker HOST/PORT 派生；显式传入时仍强制三方一致。
+BGFILTER_WORKER_HEALTH_URL=""
 BGFILTER_WORKER_ENV_FILE="/etc/genarrative/bgfilter-worker.env"
 HEALTH_URL="http://127.0.0.1:8082/readyz"
 API_ENV_FILE="/etc/genarrative/api-server.env"