diff --git a/docs/STATUS.md b/docs/STATUS.md index de25915..8170d9d 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -474,6 +474,19 @@ Redis: localhost:6381 MinIO: localhost:9003 (凭证由本地环境变量提供) ``` +**管理端端口口径**(2026-09-18 对齐为 13520): + +| 形态 | 端口 | 说明 | +|---|---|---| +| admin-web 本地开发(vite) | **13520** | 权威声明在 `admin-web/vite.config.ts`;`strictPort: true`,被占用直接失败而非静默漂移到 13521 | +| 生产 admin 容器发布 | **13520** | 声明在 `infrastructure/docker-compose.prod.yml`——**该文件位于 `.gitignore` 的「Secrets and certificates」段,刻意不进版本控制**,故此改动仅在部署机生效;仍绑定 `127.0.0.1`,对外访问走 nginx 80/443 + `/admin/` | +| 本地整套栈的管理端入口 | 6688 | admin 容器不发布端口,与 `/api` 同由 nginx 的 6688 暴露(6688 是 nginx 入口,不是纯管理端端口) | +| staging admin 容器发布 | 3001 | 为与生产同机共存,staging 全部端口按「生产 + 1」错开(5433/6380/8081/3001);`tests/uat/run-uat.sh` 的 `UAT_ADMIN_URL` 默认指向它 | + +`ui-tests/ui-document-baseline-contracts.mjs` 钉住「本地开发 / 本文档 / 生产 compose」三者端口一致: +前两处为硬断言;生产 compose 因不在版本控制内,采取「存在才断言」——CI 上该文件不存在, +显式打印 skip 而非假红。 + --- ## 当前 Phase diff --git a/ui-tests/ui-document-baseline-contracts.mjs b/ui-tests/ui-document-baseline-contracts.mjs index b80d67f..d70b429 100644 --- a/ui-tests/ui-document-baseline-contracts.mjs +++ b/ui-tests/ui-document-baseline-contracts.mjs @@ -67,12 +67,24 @@ assert.match(matrix, /2026-09-16 验收通过/, '页面矩阵未记录 11 页验 assert.doesNotMatch(matrix, /待重新实现|待开始/, '页面矩阵仍残留未完成状态') assert.doesNotMatch(matrix, /63 个页面.*(全部|全量).*重构/, '页面矩阵仍要求本批全量重构') -// —— 管理端本地开发端口一致性 —— -// 端口在两个地方各写了一份:admin-web/vite.config.ts 是唯一权威, -// docs/STATUS.md 的「当前运行状态」是给人照做的。只改一处不会让任何测试变红, -// 但会让照文档操作的人打不开页面 —— 属于本项目反复出现的「声明与兑现失联」同族问题, -// 因此用门控钉住。注意断言的是「两处一致」而非写死 13520:改端口是允许的, +// —— 管理端端口一致性(本地开发 / 文档 / 生产发布) —— +// 同一个端口写在三处:admin-web/vite.config.ts 是唯一权威, +// docs/STATUS.md 的「当前运行状态」是给人照做的, +// infrastructure/docker-compose.prod.yml 是生产 admin 容器的发布端口。 +// 只改一处不会让任何测试变红,但会让照文档操作的人打不开页面, +// 或让本机直连排查打到错的端口 —— 属于本项目反复出现的「声明与兑现失联」同族问题, +// 因此用门控钉住。注意断言的是「几处一致」而非写死 13520:改端口是允许的, // 允许的是「一起改」,不是「只改一处」。 +// 前两处(vite / STATUS)是版本控制内的硬断言;第三处(生产 compose)只能 +// 「存在才断言」,因为它被刻意排除在版本控制之外 —— 理由见下。 +// +// 刻意不纳入守卫的另外两处「管理端入口」,它们是不同形态,不是同一端口的失联: +// - infrastructure/docker-compose.yml:admin 容器不发布端口,管理端经 nginx 的 6688 +// 与 /api 一起暴露(6688 是 nginx 入口端口,不是纯管理端端口); +// - infrastructure/docker-compose.staging.yml:staging 需与生产同机共存, +// 全部端口按「生产 + 1」错开(5433/6380/8081/3001),且 3001 被 +// tests/uat/run-uat.sh 的 UAT_ADMIN_URL 依赖。 +// 改动这些入口时应同步其消费方,而不是让本守卫去断言它们等于 vite 端口。 const viteConfig = read('admin-web/vite.config.ts') const vitePort = viteConfig.match(/^\s*port:\s*(\d+),/m)?.[1] // 解析失败即失败:正则匹配不到时捕获组为 undefined,断言会退化成"与 undefined 比较" @@ -85,4 +97,32 @@ const docPort = status.match(/管理后台:\s*http:\/\/localhost:(\d+)\//)?.[1] assert.ok(docPort, 'docs/STATUS.md「当前运行状态」未声明管理后台地址(守卫自身失效)') assert.equal(docPort, vitePort, `管理后台端口不一致:STATUS.md=${docPort},vite.config.ts=${vitePort}`) +// 生产 compose 的 admin 发布端口。 +// ⚠️ infrastructure/docker-compose.prod.yml 位于 .gitignore 的「Secrets and certificates」 +// 段,刻意不进版本控制 —— 因此 CI(全新克隆)上这个文件根本不存在。若在这里硬 read(), +// 门控会在 CI 上抛 ENOENT 变成假红。故取「存在即断言、不存在则显式打印跳过」: +// 本机有它,本机就能拦住漂移;跳过时打印原因,不让它被误读成「已校验通过」。 +const prodComposePath = 'infrastructure/docker-compose.prod.yml' +if (!existsSync(resolve(root, prodComposePath))) { + console.log(`skip: ${prodComposePath} 不在版本控制内(CI 上不存在),跳过生产管理端端口校验`) +} else { + // 先切出 admin-web 服务块(到下一个 2 空格缩进的服务名为止), + // 再取块内唯一的带引号端口映射(形如 "127.0.0.1:13520:80")。 + // 不直接写 /ports:\s*\n\s*-\s*"/ —— 端口上方允许有注释行,那样会匹配不到并让守卫误判为失效。 + const prodCompose = read(prodComposePath) + const prodAdminBlock = prodCompose.match( + /container_name:\s*danyang-match-admin\n([\s\S]*?)(?=\n {2}[a-z]|$)/, + )?.[1] + assert.ok(prodAdminBlock, '未能从 docker-compose.prod.yml 切出 admin-web 服务块(守卫自身失效)') + const prodAdminMapping = prodAdminBlock.match(/-\s*"([^"]+)"/)?.[1] + assert.ok(prodAdminMapping, '未能从 docker-compose.prod.yml 的 admin-web 解析出端口映射(守卫自身失效)') + // "127.0.0.1:13520:80" → 主机端口取倒数第二段(兼容不带绑定地址的 "13520:80")。 + const prodAdminPort = prodAdminMapping.split(':').at(-2) + assert.equal( + prodAdminPort, + vitePort, + `管理端端口不一致:docker-compose.prod.yml=${prodAdminPort},vite.config.ts=${vitePort}`, + ) +} + console.log('UI document baseline contracts passed')