From f96dcb8aa65b62c8e04ab10c1686a0eebe6f643d Mon Sep 17 00:00:00 2001
From: WorkBuddy <workbuddy@local>
Date: Fri, 18 Sep 2026 20:51:12 +0800
Subject: [PATCH] =?UTF-8?q?fix(admin):=20=E7=AE=A1=E7=90=86=E7=AB=AF?=
 =?UTF-8?q?=E5=85=A5=E5=8F=A3=E6=94=B6=E6=95=9B=E5=88=B0=20/admin/=20?=
 =?UTF-8?q?=E5=AD=90=E8=B7=AF=E5=BE=84=EF=BC=8Cstaging=20=E7=AB=AF?=
 =?UTF-8?q?=E5=8F=A3=2013521=EF=BC=8C=E4=BF=AE=E5=A4=8D=E7=94=9F=E4=BA=A7?=
 =?UTF-8?q?=20/admin/=20=E5=81=87=E6=88=90=E5=8A=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

承接 rc.15 的管理端端口收敛（3000 → 13520），本轮把「入口」也收敛到一处：

- staging admin 发布端口 3001 → 13521（保持「生产 + 1」错开），同步
  tests/uat/run-uat.sh 的默认 UAT_ADMIN_URL。
- 管理端产物改为 /admin/ 子路径部署：vite 构建 base=/admin/（dev 仍为 /，开发与
  排查习惯不变）、router history base 跟随 import.meta.env.BASE_URL、三处容器化
  入口（生产 nginx / 本地整套栈 nginx / admin-web 容器内 nginx）统一为「不剥离
  前缀」转发，形态一致。
- 修复生产 nginx /admin/ 的假成功：原为 alias /usr/share/nginx/html/，而那正是
  nginx:alpine 纯净镜像自带的默认页目录（管理端产物不在该容器内），访问返回
  200 + nginx 欢迎页 —— 浏览器不报错、状态码正常，只是打开的不是管理端，比 404
  更难发现。改为 upstream admin_web + proxy_pass，并以真实两跳容器实测：
  /admin/ → 200 且为管理端标题与 /admin/assets/*、/admin/dashboard → 200（SPA
  兜底）、/admin/brand/logo-mark.png → 200、根路径 → 显式 404（用 location = /
  钉住，不依赖「本配置恰好没有 server 级 root」这一偶然事实）。
- 品牌资源引用统一走新增的 src/brand.ts（public/ 资源不受 vite base 影响，原 5 处
  写死根路径，子路径部署下会裂图）；favicon 由仓库内并不存在的 /favicon.svg 改为
  存在的品牌标。
- 补全 tests/uat/run-uat.sh 被截断的尾部：原文件停在 `if [ -`，bash -n 不通过、
  脚本根本无法运行；顺带把此前「定义了却无人消费」的 ADMIN_URL 接到管理端可达性
  实测上，并补结果汇总与非零退出码。
- ui-tests：ui-document-baseline-contracts 新增两类一致性断言（staging 发布端口 ⇄
  run-uat.sh 默认入口、子路径部署的五处约束）；admin-reference-contracts 的资产
  断言适配 brand 模块（断言「组件经 brand 模块引用」+「brand 模块指向正式资产」）。
  6 条新增断言全部经负向注入验证（注入对应缺陷 → 守卫变红且信息指向正确对象）。

验证：UI 门控 14/14 绿；vue-tsc EXIT=0；vite build EXIT=0 且产物资源均为
/admin/ 前缀；三份 nginx 配置 nginx -t 通过。

注：docs/STATUS.md 含此前的在途文档改动（非本次工作，且其中引用了已被删除的
plans 文件），故未纳入本提交；本轮的口径更新已写入该文件待一并处理。
---
 admin-web/index.html                        |   6 +-
 admin-web/nginx-admin.conf                  |  17 ++-
 admin-web/src/brand.ts                      |  14 +++
 admin-web/src/layouts/MainLayout.vue        |  11 +-
 admin-web/src/router/index.ts               |   4 +-
 admin-web/src/views/DashboardView.vue       |   3 +-
 admin-web/src/views/LoginView.vue           |   5 +-
 admin-web/vite.config.ts                    |  10 +-
 infrastructure/docker-compose.staging.yml   |   8 +-
 infrastructure/nginx-production.conf        |  41 +++++++-
 infrastructure/nginx.conf                   |  16 ++-
 tests/uat/run-uat.sh                        |  41 +++++++-
 ui-tests/admin-reference-contracts.mjs      |  10 +-
 ui-tests/ui-document-baseline-contracts.mjs | 109 ++++++++++++++++++--
 14 files changed, 266 insertions(+), 29 deletions(-)
 create mode 100644 admin-web/src/brand.ts

diff --git a/admin-web/index.html b/admin-web/index.html
index f181f71..4ecba8e 100644
--- a/admin-web/index.html
+++ b/admin-web/index.html
@@ -2,7 +2,11 @@
 <html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <!-- 原指向一个 SVG 图标文件，但仓库内并不存在该文件（public/ 下只有 brand/），
+         属既有的 404；且以 / 开头的绝对路径不会随 vite base 变化，
+         在 /admin/ 子路径部署下即使补上文件也取不到。
+         改为指向已存在、且会被 vite 自动加上 base 前缀的品牌标。 -->
+    <link rel="icon" type="image/png" href="/brand/logo-mark.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>丹阳公益婚恋 - 运营管理后台</title>
   </head>
diff --git a/admin-web/nginx-admin.conf b/admin-web/nginx-admin.conf
index 8ce6a03..2c638be 100644
--- a/admin-web/nginx-admin.conf
+++ b/admin-web/nginx-admin.conf
@@ -15,9 +15,20 @@ server {
     add_header X-XSS-Protection "1; mode=block" always;
     add_header Referrer-Policy "strict-origin-when-cross-origin" always;
 
-    # SPA fallback
-    location / {
-        try_files $uri $uri/ /index.html;
+    # 根路径没有内容：管理端产物挂在 /admin/ 子路径下（构建 base=/admin/）。
+    # 显式 301 而不是返回 nginx 默认页或 404，避免"打开有东西但其实是别的页面"的假成功。
+    location = / {
+        return 301 /admin/;
+    }
+
+    # SPA：/admin/** 映射到产物根目录。
+    # 上游入口（生产 nginx、本地整套栈 nginx）都**不剥离** /admin 前缀地转发到本容器，
+    # 因此这里必须自己认识这个前缀。
+    # try_files 的兜底写成 URI（/admin/index.html）而不是文件路径：与 alias 配合时，
+    # 写文件路径会被再次拼接 alias 而失效 —— 这是 alias + try_files 的已知坑。
+    location /admin/ {
+        alias /usr/share/nginx/html/;
+        try_files $uri $uri/ /admin/index.html;
     }
 
     # API proxy to backend
diff --git a/admin-web/src/brand.ts b/admin-web/src/brand.ts
new file mode 100644
index 0000000..20e25fe
--- /dev/null
+++ b/admin-web/src/brand.ts
@@ -0,0 +1,14 @@
+// 品牌静态资源的运行时前缀。
+//
+// admin-web/public/ 下的文件不受 vite `base` 影响（无论 base 是什么，都会被原样复制到
+// 构建产物的根目录），因此 .vue 模板里若写死 `src="/brand/xxx.png"`，在产物部署于
+// /admin/ 子路径时，浏览器会去站点根路径请求，最终 404（表现为 logo / 登录插画裂图）。
+//
+// 结论：public/ 下的运行时引用必须显式带上 import.meta.env.BASE_URL。
+// 这里集中导出，避免每处各写一遍拼接而在改 base 时漏改。
+const BRAND_BASE = `${import.meta.env.BASE_URL}brand/`
+
+export const BRAND_LOGO = `${BRAND_BASE}logo-mark.png`
+export const BRAND_LOGIN_SCENE = `${BRAND_BASE}login-illustration.jpg`
+export const BRAND_ACTIVITY_FALLBACK = `${BRAND_BASE}activity-default.jpg`
+export const BRAND_BACKDROP = `${BRAND_BASE}admin-danyang-backdrop.jpg`
diff --git a/admin-web/src/layouts/MainLayout.vue b/admin-web/src/layouts/MainLayout.vue
index 9ceb563..f87ea5c 100644
--- a/admin-web/src/layouts/MainLayout.vue
+++ b/admin-web/src/layouts/MainLayout.vue
@@ -2,7 +2,7 @@
   <div class="admin-scene" :class="{ 'sidebar-collapsed': isCollapse }">
     <header class="scene-header" aria-label="善缘丹阳公益服务品牌信息">
       <div class="scene-brand">
-        <img src="/brand/logo-mark.png" alt="善缘丹阳" />
+        <img :src="BRAND_LOGO" alt="善缘丹阳" />
         <div class="scene-brand-copy">
           <strong>善缘丹阳</strong>
           <span>公益婚恋服务平台</span>
@@ -27,7 +27,7 @@
     <el-container class="admin-shell">
       <el-aside :width="isCollapse ? '76px' : '208px'" class="admin-sidebar">
         <div class="brand" :class="{ compact: isCollapse }">
-          <img class="brand-mark" src="/brand/logo-mark.png" alt="" />
+          <img class="brand-mark" :src="BRAND_LOGO" alt="" />
           <div v-if="!isCollapse" class="brand-copy">
             <strong>善缘丹阳</strong>
             <span>公益婚恋服务平台</span>
@@ -129,6 +129,7 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue'
+import { BRAND_BACKDROP, BRAND_LOGO } from '@/brand'
 import { useRoute, useRouter } from 'vue-router'
 import { ElMessage } from 'element-plus'
 import {
@@ -260,7 +261,11 @@ function handleLogout() {
   min-height: 100vh;
   padding: 18px 34px 14px;
   overflow: hidden;
-  background: #fff7f7 url('/brand/admin-danyang-backdrop.jpg') center / cover fixed no-repeat;
+  /* 背景图是 public/ 下的运行时资源，必须带 BASE_URL 前缀：
+     写死品牌目录的绝对路径，在产物部署于 /admin/ 子路径时会 404（页面背景变纯色）。
+     用 v-bind 把常量注入 CSS，避免在样式里各写一遍拼接。 */
+  background: #fff7f7 center / cover fixed no-repeat;
+  background-image: url(v-bind('BRAND_BACKDROP'));
 }
 
 .scene-header {
diff --git a/admin-web/src/router/index.ts b/admin-web/src/router/index.ts
index c654803..520a722 100644
--- a/admin-web/src/router/index.ts
+++ b/admin-web/src/router/index.ts
@@ -44,7 +44,9 @@ const routes: RouteRecordRaw[] = [
   },
 ]
 
-const router = createRouter({ history: createWebHistory(), routes })
+// history 的 base 必须与 vite 的 base 保持一致（生产构建为 /admin/）。
+// 否则部署在 /admin/ 子路径下时，刷新或直达 /admin/xxx 会因路由匹配基准不符而白屏。
+const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes })
 
 router.beforeEach((to) => {
   const authStore = useAuthStore()
diff --git a/admin-web/src/views/DashboardView.vue b/admin-web/src/views/DashboardView.vue
index e122dd8..1404403 100644
--- a/admin-web/src/views/DashboardView.vue
+++ b/admin-web/src/views/DashboardView.vue
@@ -157,11 +157,12 @@ import {
 } from '@element-plus/icons-vue'
 import { useAuthStore } from '@/stores/auth'
 import { createEmptyDashboard, loadDashboard } from '@/services/dashboard'
+import { BRAND_ACTIVITY_FALLBACK } from '@/brand'
 import type { DashboardActivity, DashboardModel } from '@/types/dashboard'
 
 const router = useRouter()
 const authStore = useAuthStore()
-const activityFallback = '/brand/activity-default.jpg'
+const activityFallback = BRAND_ACTIVITY_FALLBACK
 const dashboard = ref<DashboardModel>(createEmptyDashboard())
 const loading = ref(true)
 const fatalError = ref('')
diff --git a/admin-web/src/views/LoginView.vue b/admin-web/src/views/LoginView.vue
index 3436dc7..3f39de4 100644
--- a/admin-web/src/views/LoginView.vue
+++ b/admin-web/src/views/LoginView.vue
@@ -1,10 +1,10 @@
 <template>
   <main class="login-shell">
     <section class="brand-panel" aria-label="善缘丹阳公益婚恋服务平台">
-      <img class="brand-scene" src="/brand/login-illustration.jpg" alt="" />
+      <img class="brand-scene" :src="BRAND_LOGIN_SCENE" alt="" />
       <div class="brand-overlay">
         <div class="brand-title">
-          <img src="/brand/logo-mark.png" alt="" />
+          <img :src="BRAND_LOGO" alt="" />
           <div>
             <strong>善缘丹阳</strong>
             <span>公益婚恋服务平台</span>
@@ -62,6 +62,7 @@
 
 <script setup lang="ts">
 import { reactive, ref } from 'vue'
+import { BRAND_LOGIN_SCENE, BRAND_LOGO } from '@/brand'
 import { useRouter } from 'vue-router'
 import { ElMessage } from 'element-plus'
 import type { FormInstance } from 'element-plus'
diff --git a/admin-web/vite.config.ts b/admin-web/vite.config.ts
index d6c161d..a58bf3c 100644
--- a/admin-web/vite.config.ts
+++ b/admin-web/vite.config.ts
@@ -2,8 +2,14 @@ import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import { resolve } from 'path'
 
-export default defineConfig({
+export default defineConfig(({ command }) => ({
   plugins: [vue()],
+  // 管理端产物部署在 nginx 的 /admin/ 子路径下（见 infrastructure/nginx-production.conf
+  // 与 admin-web/nginx-admin.conf）。构建时必须带 /admin/ 前缀，否则 index.html 引用的
+  // /assets/*.js 会落到站点根路径，被生产 nginx 的其它 location 兜成 404 或错误页面。
+  // 开发服务器保持根路径：http://localhost:13520/ 的既有开发与排查习惯不变
+  // （vite 的 base 对 dev 与 build 各自生效，故此处按 command 分叉）。
+  base: command === 'build' ? '/admin/' : '/',
   resolve: {
     alias: {
       '@': resolve(__dirname, 'src'),
@@ -22,4 +28,4 @@ export default defineConfig({
       },
     },
   },
-})
+}))
diff --git a/infrastructure/docker-compose.staging.yml b/infrastructure/docker-compose.staging.yml
index 071774a..ef28eac 100644
--- a/infrastructure/docker-compose.staging.yml
+++ b/infrastructure/docker-compose.staging.yml
@@ -87,7 +87,13 @@ services:
     depends_on:
       - backend
     ports:
-      - "3001:80"
+      # staging 与生产同机共存，全部端口按「生产 + 1」错开（5433/6380/8081/13521）。
+      # 生产管理端为 13520（admin-web/vite.config.ts + docker-compose.prod.yml），
+      # 故此处为 13521 —— 与 tests/uat/run-uat.sh 的 UAT_ADMIN_URL 默认值一致，
+      # 两处均由 ui-tests/ui-document-baseline-contracts.mjs 钉住。
+      # 管理端构建产物部署在 /admin/ 子路径下（见 admin-web/vite.config.ts 的 base），
+      # 故直连访问地址为 http://localhost:13521/admin/ 。
+      - "13521:80"
 
 volumes:
   postgres_staging_data:
diff --git a/infrastructure/nginx-production.conf b/infrastructure/nginx-production.conf
index 4cb9a57..9023e88 100644
--- a/infrastructure/nginx-production.conf
+++ b/infrastructure/nginx-production.conf
@@ -46,6 +46,12 @@ http {
         server backend:8080;
     }
 
+    # 管理端容器（同一 danyang-net 网络，服务名 admin-web —— 见 docker-compose.prod.yml）。
+    # 本容器是 nginx:alpine 纯净镜像，自身不含管理端产物，只能靠代理取。
+    upstream admin_web {
+        server admin-web:80;
+    }
+
     # HTTP -> HTTPS redirect (uncomment for production)
     # server {
     #     listen 80;
@@ -79,6 +85,15 @@ http {
             return 503 '<h1>系统维护中</h1><p>请稍后再访问。</p>';
         }
 
+        # 根路径没有内容（管理端在 /admin/ 下，小程序走 /api/）。
+        # 显式 404：当前之所以是 404，只是因为本配置没有 server 级 root，
+        # 而 nginx 默认的 html 目录（/etc/nginx/html）不存在 —— 属偶然事实。
+        # 一旦有人为了别的用途补上 root，根路径就会开始返回那个目录下的内容。
+        # 用精确匹配钉住这一行为，且不影响其它未匹配路径的既有处理。
+        location = / {
+            return 404;
+        }
+
         # Health checks (no auth needed)
         location = /api/v1/health/live {
             proxy_pass http://backend;
@@ -93,10 +108,30 @@ http {
             proxy_set_header Host $host;
         }
 
-        # Admin Web (SPA)
+        # Admin Web (SPA) —— 子路径部署在 /admin/ 下（构建 base=/admin/，见 admin-web/vite.config.ts）。
+        #
+        # 2026-09-18 修正：此处原为 `alias /usr/share/nginx/html/;`，而本容器是 nginx:alpine
+        # 纯净镜像 —— 那个目录里只有镜像自带的欢迎页，并没有管理端产物。结果是访问 /admin/
+        # 返回 200 + nginx 欢迎页，属于"假成功"，比 404 更难被发现（页面能打开，但不是管理端）。
+        # 真正的产物在 admin-web 容器内，故改为代理到 upstream。
+        #
+        # 代理**不剥离** /admin 前缀：管理端构建 base 为 /admin/，其 index.html 引用的资源
+        # 本身就以 /admin/ 开头，由 admin-web 容器内的 nginx（admin-web/nginx-admin.conf）
+        # 统一处理这个前缀，三处入口（生产 / 本地整套栈 / staging 直连）因此形态一致。
+        #
+        # 暴露面提醒：管理端登录页不应无条件对公网开放。当前依赖外层防火墙/WAF 控制；
+        # 若需在 nginx 层收敛，在此 location 内加 allow/deny 白名单（运营办公网段 + VPN）。
+        location = /admin {
+            return 301 /admin/;
+        }
         location /admin/ {
-            alias /usr/share/nginx/html/;
-            try_files $uri $uri/ /admin/index.html;
+            # 只写 upstream 名，不写端口：upstream 块里已声明 `server admin-web:80;`，
+            # 此处再带 :80 会让 nginx 报 `upstream "admin_web" may not have port 80` 而拒绝启动。
+            proxy_pass http://admin_web;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
         }
 
         # API proxy
diff --git a/infrastructure/nginx.conf b/infrastructure/nginx.conf
index 333276c..a8efde4 100644
--- a/infrastructure/nginx.conf
+++ b/infrastructure/nginx.conf
@@ -90,13 +90,25 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
         }
 
-        # Admin web
-        location / {
+        # Admin web —— 管理端产物挂在 /admin/ 子路径下（构建 base=/admin/，
+        # 见 admin-web/vite.config.ts）。与生产 nginx 保持同一形态：**不剥离**前缀地
+        # 转发给 admin-web 容器，由容器内的 nginx（admin-web/nginx-admin.conf）
+        # 统一处理 /admin/ 前缀。三处入口（生产 / 本地整套栈 / staging 直连）因此一致。
+        location = /admin {
+            return 301 /admin/;
+        }
+        location /admin/ {
             proxy_pass http://admin_web;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header X-Forwarded-Proto $scheme;
         }
+
+        # 其余未匹配路径（不含 /admin、/api、/ws）统一跳转到管理端入口。
+        # 根路径没有内容，显式跳转以避免"打根路径拿到一个空白/错页"的假成功。
+        location / {
+            return 301 /admin/;
+        }
     }
 }
diff --git a/tests/uat/run-uat.sh b/tests/uat/run-uat.sh
index 50b5979..5fa9595 100644
--- a/tests/uat/run-uat.sh
+++ b/tests/uat/run-uat.sh
@@ -6,7 +6,12 @@
 set -euo pipefail
 
 BASE_URL="${UAT_BASE_URL:-http://localhost:8080}"
-ADMIN_URL="${UAT_ADMIN_URL:-http://localhost:3001}"
+# 管理端 UAT 入口。
+# 13521 = staging admin 容器发布端口（infrastructure/docker-compose.staging.yml），
+# 按「生产 admin 端口 + 1」错开；/admin/ 是管理端产物的部署子路径
+# （base 由 admin-web/vite.config.ts 决定）——根路径不提供服务，访问根会 301 到 /admin/。
+# 此默认值由 ui-tests/ui-document-baseline-contracts.mjs 钉住，改端口时须两处同步。
+ADMIN_URL="${UAT_ADMIN_URL:-http://localhost:13521/admin/}"
 PLATFORM_URL="${UAT_PLATFORM_URL:-https://match.danyang.gov.cn}"
 TOKEN_FILE="/tmp/uat_token.txt"
 PASS=0
@@ -247,4 +252,36 @@ else
 fi
 
 # 5.2 备份文件存在
-if [ -
+# 备份由 infrastructure/scripts/backup.sh 产出（容器内 /app/backups，宿主机为 infrastructure/backups）。
+if ls infrastructure/backups/*.sql.gz > /dev/null 2>&1; then
+    BACKUP_COUNT=$(ls -1 infrastructure/backups/*.sql.gz 2>/dev/null | wc -l | tr -d ' ')
+    log_result "数据库备份文件" "PASS" "发现 ${BACKUP_COUNT} 个备份"
+else
+    log_result "数据库备份文件" "SKIP" "未发现备份文件（首次部署前正常）"
+fi
+
+# 5.3 管理端页面可达
+# 2026-09-18 前 ${ADMIN_URL} 是个定义了却无人消费的常量 —— 端口/子路径改了、
+# 脚本没同步，也不会有任何检查变红。此处把它接到实测上：
+# 期望 200，且期望的是 `/admin/` 子路径（管理端产物 base 为 /admin/，访问根路径会 301）。
+ADMIN_CODE=$(curl -s -o /dev/null -w "%{http_code}" "${ADMIN_URL}" 2>/dev/null || echo "000")
+if [ "$ADMIN_CODE" = "200" ]; then
+    log_result "管理端页面可达" "PASS" "${ADMIN_URL}"
+else
+    log_result "管理端页面可达" "FAIL" "${ADMIN_URL} → HTTP ${ADMIN_CODE}"
+fi
+
+echo ""
+
+# ========================================
+# 6. 结果汇总
+# ========================================
+echo "============================================"
+echo " UAT 检查结果：PASS=${PASS}  FAIL=${FAIL}  SKIP=${SKIP}"
+echo "============================================"
+
+# 有 FAIL 时以非零退出：让 CI/人工调用方靠退出码就能发现，而不是必须滚屏找 ❌。
+if [ "$FAIL" -gt 0 ]; then
+    exit 1
+fi
+exit 0
diff --git a/ui-tests/admin-reference-contracts.mjs b/ui-tests/admin-reference-contracts.mjs
index 612f66f..f88fb38 100644
--- a/ui-tests/admin-reference-contracts.mjs
+++ b/ui-tests/admin-reference-contracts.mjs
@@ -7,6 +7,10 @@ const read = (path) => readFileSync(resolve(root, path), 'utf8')
 const theme = read('admin-web/src/theme/index.css')
 const layout = read('admin-web/src/layouts/MainLayout.vue')
 const dashboard = read('admin-web/src/views/DashboardView.vue')
+// 品牌资产的实际文件名集中在 src/brand.ts：public/ 下的资源不受 vite base 影响，
+// 引用时必须显式拼 BASE_URL（否则在 /admin/ 子路径部署下 404）。因此下面断言
+// 「组件经 brand 模块引用」+「brand 模块指向正式资产」两处，而不是在组件里找文件名字面量。
+const brand = read('admin-web/src/brand.ts')
 
 for (const token of [
   '--admin-coral',
@@ -27,7 +31,8 @@ assert.ok(
 for (const className of ['admin-scene', 'admin-shell', 'admin-sidebar', 'admin-topbar', 'admin-content']) {
   assert.ok(layout.includes(className), `缺少框架结构 ${className}`)
 }
-assert.match(layout, /admin-danyang-backdrop\.jpg/, '管理端外层未使用正式背景资产')
+assert.match(brand, /admin-danyang-backdrop\.jpg/, '品牌模块未指向正式背景资产')
+assert.match(layout, /BRAND_BACKDROP/, '管理端外层未使用正式背景资产')
 assert.match(layout, /permissions/, '侧栏未保留权限控制')
 
 for (const item of [
@@ -60,7 +65,8 @@ assert.match(dashboard, /metrics/, '工作台缺少指标数据绑定')
 assert.match(dashboard, /Asia\/Shanghai/, '工作台日期未固定为中国时区')
 assert.match(dashboard, /loadDashboard/, '工作台未接入真实数据适配层')
 assert.match(dashboard, /retryLoad/, '工作台缺少失败重试')
-assert.match(dashboard, /activity-default\.jpg/, '活动封面缺少本地降级资产')
+assert.match(brand, /activity-default\.jpg/, '品牌模块未指向活动封面降级资产')
+assert.match(dashboard, /BRAND_ACTIVITY_FALLBACK/, '活动封面缺少本地降级资产')
 assert.match(dashboard, /item\.max\s*>\s*0/, '成效进度未处理 max 为 0 的情况')
 assert.match(dashboard, /v-for="metric in dashboard\.metrics"/, '六指标必须由 DashboardModel 统一渲染')
 
diff --git a/ui-tests/ui-document-baseline-contracts.mjs b/ui-tests/ui-document-baseline-contracts.mjs
index d70b429..c7a916b 100644
--- a/ui-tests/ui-document-baseline-contracts.mjs
+++ b/ui-tests/ui-document-baseline-contracts.mjs
@@ -78,13 +78,13 @@ assert.doesNotMatch(matrix, /63 个页面.*(全部|全量).*重构/, '页面矩
 // 前两处（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 端口。
+//     与 /api 一起暴露（6688 是 nginx 入口端口，不是纯管理端端口），故不参与"等于 vite 端口"。
+// staging（docker-compose.staging.yml）原也列在"不纳入"——它按「生产 + 1」错开，端口本就不
+// 等于 vite 端口。但它与 tests/uat/run-uat.sh 默认值之间的一致性是可断言的（两者都在版本
+// 控制内），而两者不一致正是"照脚本去跑、管理端却打不开"的直接原因，故改为单独一组断言：
+// 见下方「staging 管理端入口一致性」。
 const viteConfig = read('admin-web/vite.config.ts')
 const vitePort = viteConfig.match(/^\s*port:\s*(\d+),/m)?.[1]
 // 解析失败即失败：正则匹配不到时捕获组为 undefined，断言会退化成"与 undefined 比较"
@@ -125,4 +125,101 @@ if (!existsSync(resolve(root, prodComposePath))) {
   )
 }
 
+// —— staging 管理端入口一致性（发布端口 / UAT 脚本默认值 / 子路径） ——
+// 2026-09-18 之前，tests/uat/run-uat.sh 里的 ADMIN_URL 是个「定义了却无人消费」的常量：
+// 端口改了、脚本没同步，不会有任何检查变红。现该变量已接到实测的管理端可达性检查上，
+// 这里再用门控保证它与 staging compose 的发布端口一致 —— 否则实测会稳定地测错对象。
+const stagingCompose = read('infrastructure/docker-compose.staging.yml')
+const stagingAdminMapping = stagingCompose
+  .match(/container_name:\s*danyang-match-staging-admin\n([\s\S]*?)(?=\n {2}[a-z]|$)/)?.[1]
+  ?.match(/-\s*"([^"]+)"/)?.[1]
+assert.ok(stagingAdminMapping, '未能从 docker-compose.staging.yml 的 admin-web 解析出端口映射（守卫自身失效）')
+const stagingAdminPort = stagingAdminMapping.split(':').at(-2)
+
+const uatAdminUrlMatch = read('tests/uat/run-uat.sh')
+  .match(/^ADMIN_URL="\$\{UAT_ADMIN_URL:-http:\/\/localhost:(\d+)(\/[^}"]*)?\}"/m)
+assert.ok(uatAdminUrlMatch, '未能从 tests/uat/run-uat.sh 解析出 ADMIN_URL 默认值（守卫自身失效）')
+assert.equal(
+  uatAdminUrlMatch[1],
+  stagingAdminPort,
+  `管理端 UAT 入口端口不一致：run-uat.sh=${uatAdminUrlMatch[1]}，docker-compose.staging.yml=${stagingAdminPort}`,
+)
+// 子路径：产物部署在 /admin/ 下，UAT 入口必须带该前缀。缺了它测的是根路径（301 或 404）——
+// "检查了但检查错了对象"比不检查更坏，因为它给出的是通过。
+assert.equal(uatAdminUrlMatch[2], '/admin/', `run-uat.sh 的管理端入口未指向 /admin/ 子路径：${uatAdminUrlMatch[0]}`)
+// staging 与生产同机共存，端口必须错开。生产端口在 CI 上不可知（prod compose 不在版本
+// 控制内），故只能断言"不撞车"，不断言具体的「生产 + 1」。
+assert.notEqual(stagingAdminPort, vitePort, `staging 管理端端口与主管理端端口撞车（都是 ${stagingAdminPort}），同机部署会冲突`)
+
+// —— 管理端子路径部署一致性 ——
+// 产物部署在 /admin/ 子路径下（vite base 按 command 分叉）。该形态依赖五处同时成立：
+// vite base、router history base、生产 nginx、本地整套栈 nginx、admin-web 容器自身 nginx。
+// 任一处退回根路径假设，都会造成"页面能打开但白屏 / 裂图 / 指到别的东西"。
+// 历史缺陷：生产 nginx 的 /admin/ 曾写 `alias /usr/share/nginx/html/` —— 那是 nginx:alpine
+// 镜像自带的默认页目录（本容器内并没有管理端产物），于是 /admin/ 返回 200 + nginx 欢迎页：
+// 假成功，比 404 更难发现。故下面既断言"代理到 upstream"，也反向断言"不得再退回 alias"。
+assert.match(
+  viteConfig,
+  /base:\s*command\s*===\s*'build'\s*\?\s*'\/admin\/'\s*:\s*'\/'/,
+  'vite 未把构建 base 设为 /admin/（产物会引用站点根路径的资源）',
+)
+assert.match(
+  read('admin-web/src/router/index.ts'),
+  /createWebHistory\(import\.meta\.env\.BASE_URL\)/,
+  'router 的 history base 未跟随 vite base（子路径部署下刷新或直达深层路由会白屏）',
+)
+
+const prodNginx = read('infrastructure/nginx-production.conf')
+assert.match(prodNginx, /upstream\s+admin_web\s*\{[\s\S]*?server\s+admin-web:80;/, '生产 nginx 未声明 admin_web upstream')
+assert.match(
+  prodNginx,
+  /location\s+\/admin\/\s*\{[^}]*proxy_pass\s+http:\/\/admin_web;/,
+  '生产 nginx 的 /admin/ 未代理到 admin_web upstream',
+)
+assert.doesNotMatch(
+  prodNginx,
+  /location\s+\/admin\/\s*\{[^}]*alias\s/,
+  '生产 nginx 的 /admin/ 又退回 alias 本容器目录（会返回镜像默认页，属假成功）',
+)
+
+assert.match(
+  read('infrastructure/nginx.conf'),
+  /location\s+\/admin\/\s*\{[^}]*proxy_pass\s+http:\/\/admin_web;/,
+  '本地整套栈 nginx 的 /admin/ 未代理到 admin_web（6688 上取不到管理端）',
+)
+
+const adminContainerNginx = read('admin-web/nginx-admin.conf')
+assert.match(
+  adminContainerNginx,
+  /location\s+\/admin\/\s*\{[\s\S]*?alias\s+\/usr\/share\/nginx\/html\/;/,
+  'admin-web 容器 nginx 未服务 /admin/ 子路径',
+)
+assert.match(
+  adminContainerNginx,
+  /try_files\s+\$uri\s+\$uri\/\s+\/admin\/index\.html;/,
+  'admin-web 容器 nginx 的 SPA 兜底未指向 /admin/index.html（alias 配 try_files 写成文件路径会失效）',
+)
+
+// public/ 下的运行时资源不受 vite base 影响（原样复制到产物根），因此写死 `src="/brand/...`
+// 或 `url('/brand/...')` 在子路径部署下会 404（logo / 插画 / 背景图裂）。统一走 src/brand.ts。
+for (const file of [
+  'admin-web/src/layouts/MainLayout.vue',
+  'admin-web/src/views/LoginView.vue',
+  'admin-web/src/views/DashboardView.vue',
+]) {
+  const src = read(file)
+  assert.doesNotMatch(src, /src="\/brand\//, `${file} 仍写死 /brand/ 根路径引用（子路径部署下会裂图）`)
+  assert.doesNotMatch(src, /url\('\/brand\//, `${file} 仍写死 url('/brand/...')（子路径部署下会裂图）`)
+}
+assert.match(
+  read('admin-web/index.html'),
+  /href="\/brand\/logo-mark\.png"/,
+  'index.html 的 favicon 未指向存在的品牌资源（vite 会为它补上 base 前缀）',
+)
+assert.doesNotMatch(
+  read('admin-web/index.html'),
+  /favicon\.svg/,
+  'index.html 仍引用不存在的 /favicon.svg（仓库内无此文件，且绝对路径不随 base 变化）',
+)
+
 console.log('UI document baseline contracts passed')