From 90db243a68a5d16d643dd0273614b93666d65ca7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Wed, 14 Oct 2026 10:58:01 +0800 Subject: [PATCH] =?UTF-8?q?fix(web):=20=E6=97=A7=20index.html=20=E7=9A=84?= =?UTF-8?q?=E5=93=88=E5=B8=8C=E8=B5=84=E6=BA=90=E5=9B=9E=E9=80=80=E5=88=B0?= =?UTF-8?q?=E3=80=8C=E4=B8=8A=E4=B8=80=E7=89=88=E6=9E=84=E5=BB=BA=E3=80=8D?= =?UTF-8?q?=EF=BC=8C=E9=A1=B5=E9=9D=A2=E4=B8=8D=E5=86=8D=E7=A9=BA=E7=99=BD?= =?UTF-8?q?/=E8=A3=B8=E5=A5=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现象(主人反馈:页面**偶尔**变成"只有文字没样式"):旧入口 index.html 引用的是上一版的 `index-CddbQIqQ.js` / `index-DLg1Y9tN.css`,而新镜像里只剩当次构建的两个文件 ⇒ JS 404 白屏、CSS 404 只有文字没样式。触发条件是"短时间内多次重建 web + CDN/浏览器还拿着旧入口"。 修复(三层,各管一段): 1. **入口不缓存**(上一笔已做):`index.html` → `no-cache, must-revalidate`,CDN/浏览器每次回源校验; 2. **旧哈希资源仍可取**(本笔):`/assets/` 未命中时先回退到只读挂载的 `deploy/legacy-assets/assets`(**上一版构建**的资源),再 404 ⇒ 还持有旧入口的客户端 不会因为一个文件 404 而白屏/裸奔;该目录由 `scripts/deploy-api-web.sh` 在**每次重建前** 从"正在运行的那个镜像"里落盘(`LEGACY_ASSETS=` 会打在部署日志里),并加进 .gitignore; 3. **未命中不再回退成 HTML**:避免浏览器把 index.html 当 JS 执行报一堆语法错误。 验证:旧入口的两个引用 `assets/index-CddbQIqQ.js`、`assets/index-DLg1Y9tN.css` 现在都是 200 (旧客户端可用);当前入口的 `assets/index-Dbnd-DW-.js`、`assets/index-Bgkt4A1i.css` 也是 200; 不存在的文件名仍明确 404;`nginx -t` 通过;本机 8088 与公网入口 kg.zheromiku.top 一致;make verify 15/15。 --- .gitignore | 2 ++ CHANGELOG.md | 5 ++++- compose.yaml | 4 ++++ deploy/nginx.conf | 8 ++++++++ scripts/deploy-api-web.sh | 12 ++++++++++++ 5 files changed, 30 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index d0c1df9..f07adae 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,5 @@ backups/ .ci-remote-tags .ci-commits-count .ci-preview-url +# 上一版构建的静态资源(部署脚本落盘、只读挂载的运行时目录,不进 git) +deploy/legacy-assets/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ef3b3c..4d3ef5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,10 @@ ### Fixed -- 前端入口的缓存策略:`index.html` 此前没有缓存头,CDN/浏览器会启发式缓存它,于是**页面会一直停在旧构建上**(实测被腾讯云 EdgeOne 卡住:源站已是新包,公网入口仍发旧包,看起来像"新菜单/新页面没上线")。现在 `index.html` 每次回源校验(`no-cache, must-revalidate`)、带内容哈希的 `/assets/` 长缓存(`immutable`),旧哈希资源明确 404 而不是回退成 HTML。 +- 前端入口与静态资源的缓存语义("新功能看起来没上线"与"页面偶尔裸奔/空白"的根因): + - `index.html` 此前**没有缓存头**,CDN/浏览器按启发式缓存它 ⇒ 页面会一直停在旧构建上(实测被腾讯云 EdgeOne 卡住:源站已是新包,公网入口仍发旧包)。现在 `index.html` 每次回源校验(`no-cache, must-revalidate`); + - 带内容哈希的 `/assets/` 长缓存(`immutable`),但**未命中时先回退到"上一版构建的资源"目录、再 404**(`deploy/legacy-assets` 由部署脚本在每次重建前落盘并只读挂载):CDN/浏览器仍持有旧 `index.html` 时,它引用的旧 JS/CSS 依旧能取到 ⇒ 不会出现"JS 404 白屏"或"CSS 404 只有文字没样式"; + - 明确 404 时不再回退成 `index.html`(否则浏览器把 HTML 当 JS 执行,报一堆语法错误)。 ### Security diff --git a/compose.yaml b/compose.yaml index 46d5d71..ab7693b 100644 --- a/compose.yaml +++ b/compose.yaml @@ -211,6 +211,10 @@ services: api: condition: service_healthy read_only: true + volumes: + # 上一版构建的静态资源(只读,由部署脚本落盘):CDN/浏览器可能还持有旧 index.html, + # 让它的旧哈希引用不至于 404 —— 否则页面会空白或"只有文字没样式"。 + - ./deploy/legacy-assets:/usr/share/nginx/legacy:ro tmpfs: - /tmp - /var/cache/nginx diff --git a/deploy/nginx.conf b/deploy/nginx.conf index 98ebf69..d7697b3 100644 --- a/deploy/nginx.conf +++ b/deploy/nginx.conf @@ -30,6 +30,14 @@ server { location /assets/ { expires 1y; add_header Cache-Control "public, max-age=31536000, immutable"; + # 当前构建里没有再找**上一版构建**的资源:CDN/浏览器可能还持有旧 index.html, + # 它引用的旧哈希文件若直接 404,页面就会空白或"裸奔"(只有文字没样式)。 + # 旧目录由部署脚本在每次重建前落盘(deploy/legacy-assets,只读挂载)。 + try_files $uri @legacy; + } + + location @legacy { + root /usr/share/nginx/legacy; try_files $uri =404; } diff --git a/scripts/deploy-api-web.sh b/scripts/deploy-api-web.sh index 84d4bc8..3400110 100644 --- a/scripts/deploy-api-web.sh +++ b/scripts/deploy-api-web.sh @@ -35,6 +35,18 @@ if [ "${#IDENTITY_ARGS[@]}" -lt 6 ]; then fi printf ' %s\n' "${IDENTITY_ARGS[@]}" +echo "=== 1c. 保留上一版构建的静态资源(CDN/浏览器可能还持有旧 index.html)" +# 只保留**当前正在跑的那一版**:旧 index.html 的旧哈希引用仍能取到文件, +# 页面不会因为某个 JS/CSS 404 而空白或"裸奔"。目录只读挂载进 web 容器。 +LEGACY_DIR="deploy/legacy-assets" +PREV_WEB_IMAGE=$(docker inspect -f '{{.Image}}' knowledge-governance-p1-web-1 2>/dev/null || true) +mkdir -p "$LEGACY_DIR/assets" && chmod 777 "$LEGACY_DIR" "$LEGACY_DIR/assets" +if [ -n "$PREV_WEB_IMAGE" ]; then + docker run --rm --user 0 --entrypoint sh -v "$PWD/$LEGACY_DIR:/out" "$PREV_WEB_IMAGE" \ + -c 'cp -a /usr/share/nginx/html/assets/. /out/assets/ 2>/dev/null || true' >/dev/null 2>&1 || true + echo " LEGACY_ASSETS=$(ls -1 "$LEGACY_DIR/assets" 2>/dev/null | tr '\n' ' ')" +fi + echo "=== 2. 构建 api" docker build --network host "${PROXY_ARGS[@]}" "${IDENTITY_ARGS[@]}" -f Dockerfile -t knowledge-governance-p1-api:latest . || { echo "API_BUILD_FAILED"; exit 1; }