fix(nginx): add hololake-frontend→guanghulab root path migration, sandbox routes, and _shared dir

ZY-NGINX-ROOTFIX-2026-0325-001 · DEV-004 之之诊断

- deploy-to-server.yml: add hololake-frontend root path fix in Nginx migration
- deploy-to-server.yml: add sandbox alias routes (DEV-004, DEV-005) via snippet
- deploy-to-server.yml: auto-create /var/www/_shared directory
- deploy-to-server.yml: add defensive root path verification
- deploy/nginx/hololake.conf: add DEV-004, DEV-005 sandbox location blocks
- data/nginx-rootfix-report-20260325.json: fix report

Co-authored-by: qinfendebingshuo <207279273+qinfendebingshuo@users.noreply.github.com>
Agent-Logs-Url: https://github.com/qinfendebingshuo/guanghulab/sessions/486292a1-798d-400e-ad49-660f3e64b6aa

.github/workflows/deploy-to-server.yml

@@ -355,15 +355,34 @@ jobs:
               # 一次性迁移：更新 root 路径（从旧的 status-board 子目录改为站点根目录）
               if grep -q 'root.*guanghulab/status-board' /etc/nginx/sites-available/default 2>/dev/null || \
                  grep -q 'root.*guanghulab/status-board' /etc/nginx/conf.d/*.conf 2>/dev/null; then
-                echo '🔄 更新 Nginx root 路径...'
+                echo '🔄 更新 Nginx root 路径（status-board → 站点根）...'
                 sudo sed -i 's|root.*guanghulab/status-board[^;]*|root ${{ secrets.DEPLOY_PATH }}|g' \
                   /etc/nginx/sites-available/default 2>/dev/null || true
                 sudo sed -i 's|root.*guanghulab/status-board[^;]*|root ${{ secrets.DEPLOY_PATH }}|g' \
                   /etc/nginx/conf.d/*.conf 2>/dev/null || true
                 NGINX_CHANGED=true
-                echo '✅ Nginx root 路径已更新'
+                echo '✅ Nginx root 路径已更新（status-board 迁移）'
+              fi
+
+              # 一次性迁移：修正 root 路径（从旧残留 hololake-frontend 改为 guanghulab）
+              # 根因：ZY-NGINX-ROOTFIX-2026-0325-001 · DEV-004 之之诊断
+              if grep -q 'root.*/var/www/hololake-frontend' /etc/nginx/sites-available/default 2>/dev/null || \
+                 grep -q 'root.*/var/www/hololake-frontend' /etc/nginx/conf.d/*.conf 2>/dev/null; then
+                echo '🔄 更新 Nginx root 路径（hololake-frontend → guanghulab）...'
+                sudo sed -i 's|root /var/www/hololake-frontend|root ${{ secrets.DEPLOY_PATH }}|g' \
+                  /etc/nginx/sites-available/default 2>/dev/null || true
+                sudo sed -i 's|root /var/www/hololake-frontend|root ${{ secrets.DEPLOY_PATH }}|g' \
+                  /etc/nginx/conf.d/*.conf 2>/dev/null || true
+                NGINX_CHANGED=true
+                echo '✅ Nginx root 路径已更新（hololake-frontend → guanghulab）'
+              fi
+
+              # 验证 root 路径确实正确（防御性检查）
+              if ! grep -q "root ${{ secrets.DEPLOY_PATH }}" /etc/nginx/conf.d/*.conf 2>/dev/null && \
+                 ! grep -q "root ${{ secrets.DEPLOY_PATH }}" /etc/nginx/sites-available/default 2>/dev/null; then
+                echo '⚠️ Nginx root 路径可能未正确设置，请手动检查'
               else
-                echo '✅ Nginx root 路径正确，无需修改'
+                echo '✅ Nginx root 路径正确，指向 ${{ secrets.DEPLOY_PATH }}'
               fi
 
               # 配置 API + WebSocket 反向代理
@@ -480,6 +499,49 @@ jobs:
                 echo '✅ API 反向代理已存在，无需修改'
               fi
 
+              # 补建 _shared 目录（沙盒共享资源）
+              if [ ! -d /var/www/_shared ]; then
+                sudo mkdir -p /var/www/_shared
+                sudo chmod 755 /var/www/_shared
+                echo '✅ _shared 目录已创建'
+              fi
+
+              # 沙盒 alias 路由补充（DEV-004, DEV-005）
+              # 根因：ZY-NGINX-ROOTFIX-2026-0325-001 · 沙盒模块需通过域名访问
+              SANDBOX_CONF='/etc/nginx/snippets/guanghulab-sandbox.conf'
+              if [ ! -f \"\$SANDBOX_CONF\" ]; then
+                printf '%s\n' \
+                  '# guanghulab 沙盒路由（由 CD 工作流自动生成）' \
+                  '' \
+                  '# DEV-004 之之 · 沙盒路由' \
+                  'location /DEV-004/ {' \
+                  '    alias /var/www/DEV-004/;' \
+                  '    index index.html;' \
+                  '    try_files \$uri \$uri/ =404;' \
+                  '}' \
+                  '' \
+                  '# DEV-005 小草莓 · 沙盒路由' \
+                  'location /DEV-005/ {' \
+                  '    alias /var/www/DEV-005/;' \
+                  '    index index.html;' \
+                  '    try_files \$uri \$uri/ =404;' \
+                  '}' \
+                  | sudo tee \"\$SANDBOX_CONF\" > /dev/null
+
+                # 在 server 块中加入 sandbox include 指令
+                NGINX_MAIN=\$(grep -rl 'server_name' /etc/nginx/sites-available/ 2>/dev/null | head -1)
+                if [ -z \"\$NGINX_MAIN\" ]; then
+                  NGINX_MAIN='/etc/nginx/sites-available/default'
+                fi
+                if [ -f \"\$NGINX_MAIN\" ] && ! grep -q 'guanghulab-sandbox' \"\$NGINX_MAIN\" 2>/dev/null; then
+                  sudo sed -i '/server_name/a\\    include /etc/nginx/snippets/guanghulab-sandbox.conf;' \"\$NGINX_MAIN\" 2>/dev/null && \
+                    NGINX_CHANGED=true && echo '✅ 沙盒路由已自动配置' || \
+                    echo '⚠️ 沙盒路由自动配置失败，请手动添加'
+                fi
+              else
+                echo '✅ 沙盒路由配置已存在'
+              fi
+
               # 如果有变更，验证并重新加载 Nginx
               if [ \"\$NGINX_CHANGED\" = true ]; then
                 sudo nginx -t && sudo systemctl reload nginx && echo '✅ Nginx 配置已重新加载' || \

data/nginx-rootfix-report-20260325.json

@@ -0,0 +1,30 @@
+{
+  "instruction_id": "ZY-NGINX-ROOTFIX-2026-0325-001",
+  "executed_at": "2026-03-25T05:04:00Z",
+  "executor": "AG-ZY-01 铸渊",
+  "root_cause": "Nginx root 指向 /var/www/hololake-frontend（旧残留），实际部署目录为 /var/www/guanghulab",
+  "diagnosis_by": "DEV-004 之之",
+  "fixes_applied": [
+    "Nginx root 路径修正: deploy-to-server.yml 增加 hololake-frontend → guanghulab 迁移逻辑",
+    "Nginx 模板更新: deploy/nginx/hololake.conf 添加 DEV-004, DEV-005 沙盒 alias 路由",
+    "沙盒 alias 路由补充: deploy-to-server.yml 自动生成 guanghulab-sandbox.conf snippet",
+    "API 反向代理确认: /api/, /api/ps/ 已在模板和工作流中配置",
+    "_shared 目录补建: deploy-to-server.yml 自动创建 /var/www/_shared",
+    "PM2 errored 进程: 需在服务器上手动执行 pm2 restart --only-errored"
+  ],
+  "changes_in_repo": [
+    ".github/workflows/deploy-to-server.yml — 增加 hololake-frontend root 路径迁移、沙盒路由配置、_shared 目录创建",
+    "deploy/nginx/hololake.conf — 添加 DEV-004, DEV-005 沙盒 alias 路由",
+    "data/nginx-rootfix-report-20260325.json — 本修复回执"
+  ],
+  "verification": {
+    "note": "修复已提交到仓库，下次部署到服务器时将自动应用。服务器验证需在部署后通过 Phase 5 脚本确认。",
+    "expected_fix_on_deploy": [
+      "Nginx root 路径从 hololake-frontend 修正为 guanghulab",
+      "/var/www/_shared 目录自动创建",
+      "沙盒路由 /DEV-004/ 和 /DEV-005/ 自动配置"
+    ]
+  },
+  "nginx_test": "将在下次部署时自动执行 nginx -t",
+  "status": "COMMITTED_PENDING_DEPLOY"
+}

deploy/nginx/hololake.conf

@@ -133,6 +133,20 @@ server {
         proxy_set_header X-Real-IP $remote_addr;
     }
 
+    # ── DEV-004 之之 · 沙盒路由 ──
+    location /DEV-004/ {
+        alias /var/www/DEV-004/;
+        index index.html;
+        try_files $uri $uri/ =404;
+    }
+
+    # ── DEV-005 小草莓 · 沙盒路由 ──
+    location /DEV-005/ {
+        alias /var/www/DEV-005/;
+        index index.html;
+        try_files $uri $uri/ =404;
+    }
+
     # ── 错误页面 ──
     error_page 404 /404.html;
     error_page 500 502 503 504 /50x.html;