From eeeb6572ba025b60f413b5f5696645a8c4caff6f Mon Sep 17 00:00:00 2001
From: MiFaZhan <mifazhan@users.noreply.gitcode.com>
Date: Fri, 30 Oct 2026 13:11:58 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20nginx=20=E5=9C=A8=20/docs/=20=E4=B8=8B?=
 =?UTF-8?q?=E6=9C=8D=E5=8A=A1=E4=BA=A7=E7=89=A9=EF=BC=8C=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E7=99=BD=E5=B1=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VitePress 配置 base: '/docs/'，构建出的 HTML 里资源引用是绝对路径 /docs/assets/xxx；
而 dist 目录是平铺的（index.html、assets/ 直接在根）。原 nginx.conf 从根路径服务，
/docs/assets/* 全部 404 → 页面能打开但 JS/CSS 加载失败，白屏、点击无反应。

改为用 alias 把 /docs/ 前缀剥掉再落到产物目录，并加 / -> /docs/ 的 302，
避免直接访问根路径白屏。

实测（本地构建镜像后）：/docs/ 200、/docs/manual/web/ 200、/docs/openapi/ 200、
核心 CSS 资源 200；/ 返回 302。
---
 docker/nginx.conf | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docker/nginx.conf b/docker/nginx.conf
index 04e9641..0134bc9 100644
--- a/docker/nginx.conf
+++ b/docker/nginx.conf
@@ -5,6 +5,20 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    # VitePress 配置 base: '/docs/'，构建产物里的资源引用是绝对路径 /docs/assets/xxx，
+    # 而 dist 目录是平铺的（index.html、assets/ 直接在根）。
+    # 因此必须在 /docs/ 路径下提供服务，用 alias 把前缀剥掉再落到产物目录，
+    # 否则页面能返回 200 但 JS/CSS 全部 404 → 白屏。
+    location /docs/ {
+        alias /usr/share/nginx/html/;
+        try_files $uri $uri.html $uri/ $uri/index.html =404;
+    }
+
+    # 根路径跳到文档入口，避免访问 / 时白屏
+    location = / {
+        return 302 /docs/;
+    }
+
     location / {
         try_files $uri $uri.html $uri/ =404;
     }