admin/danyang-match
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(admin): 生产管理端端口 3000 → 13520；守卫扩至三处并容错 CI

Browse Source 
生产 admin 容器发布端口原为 127.0.0.1:3000 —— 3000 是本机最易被其他项目
（videoos / ai-callcenter）抢用的端口，与新定的管理端端口 13520 不一致。
已改为 127.0.0.1:13520:80（仍绑定 loopback，对外访问走 nginx 80/443 + /admin/）。

⚠️ 该实体改动无法进入本次提交：infrastructure/docker-compose.prod.yml 位于
.gitignore 的「Secrets and certificates」段，刻意不进版本控制（含按主机定制的
部署参数）。因此本次提交承载的是「决策记录 + 守卫」，端口改动只在部署机生效。

守卫 ui-tests/ui-document-baseline-contracts.mjs：
- 由「两处一致」扩为「三处一致」：admin-web/vite.config.ts（权威声明）、
  docs/STATUS.md（给人照做的）、docker-compose.prod.yml（生产发布端口）。
- 生产 compose 采取「存在才断言」：CI 全新克隆上该文件不存在，硬 read() 会抛
  ENOENT 让门控假红。已实测——移走文件 → 打印 skip 且 EXIT=0；放回 → 断言恢复。
- 明确排除另外两处管理端入口并写清理由：本地整套栈的管理端经 nginx 6688 暴露
  （6688 是 nginx 入口，不是纯管理端端口）；staging 的 3001 是为与生产同机共存
  而按「生产 + 1」错开（5433/6380/8081/3001），且被 tests/uat/run-uat.sh 的
  UAT_ADMIN_URL 默认值依赖 —— 改动它们要同步消费方，不该由本守卫断言等于 vite 端口。

docs/STATUS.md：新增「管理端端口口径」表，记录四种管理端入口的端口与取舍理由，
并显式标注生产 compose 不在版本控制内（否则后人会以为改了没生效）。

验证：ui-tests 门控 14/14；负向验证 prod compose 改回 3000 → 精准报
「docker-compose.prod.yml=3000，vite.config.ts=13520」；文件缺失 → skip 且不假红；
还原后 md5 逐字节一致（71a30653…）；docker compose config 解析出
published=13520 且 host_ip=127.0.0.1（loopback 绑定未丢失）。
This commit is contained in:
WorkBuddy
2026-09-18 19:49:50 +08:00
parent 9c26d4b7b2
commit 3ff0c0641a
2 changed files with 58 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/STATUS.md
+13
View File
@@ -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
ui-tests/ui-document-baseline-contracts.mjs
+45 -5
View File
@@ -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')