fix: nginx 根路径 301 重定向到 /emotion-museum/（修复首页 404）

2026-06-28 23:21:03 +08:00
parent 19337b9371
commit 808a590b8d
2 changed files with 139 additions and 113 deletions
@@ -0,0 +1,106 @@
+---
+author: Peanut
+created_at: 2026-06-28
+purpose: 修复生产环境首页 404，删除 nginx 配置中显式阻断根路径的 location 块
+---
+
+# 修复 nginx 根路径 404 设计
+
+## 背景
+
+生产环境 `https://lifescript.happylifeos.com/` 访问首页返回 404 Not Found，但：
+- 前端文件 `/data/www/emotion-museum/index.html` 实际已正确部署
+- 子路径 `https://lifescript.happylifeos.com/emotion-museum-admin/`、`/life-script/`、`/emotion-museum/` 可以正常访问
+- 后端 API 代理 `/api` 正常工作
+
+## 根因（实际）
+
+**真实生效的 nginx 配置不在 `conf/emotion-museum.conf`**，而是在 aaPanel 托管的：
+`/www/server/panel/vhost/nginx/emotion-museum.conf`
+
+原因：nginx 主配置 `/www/server/nginx/conf/nginx.conf` 的 include 顺序是：
+```nginx
+include /www/server/panel/vhost/nginx/*.conf;
+```
+它只 include aaPanel 的 vhost 目录。`/etc/nginx/sites-available/` 是部署脚本的"期望"路径，但**从未被 include**，所以 `deploy.py nginx` 实际上一直没真正生效。
+
+真实配置中第 31-33 行有一个显式阻断根路径的 exact match：
+
+```nginx
+location = / {
+    return 404;
+}
+```
+
+并且前端在真实配置中映射的路径是 `/emotion-museum/`（不是根路径）：
+
+```nginx
+location /emotion-museum/ {
+    alias /data/www/emotion-museum/;
+    ...
+    try_files $uri $uri/ /emotion-museum/index.html;
+}
+```
+
+所以访问 `/` 时，被 `location = / { return 404; }` 精确匹配拦截，根本不会走到任何 location 块。
+
+## 修复方案
+
+### 第一层：修改真实生效的 aaPanel 配置
+
+直接 ssh 编辑 `/www/server/panel/vhost/nginx/emotion-museum.conf`，把：
+
+```nginx
+location = / {
+    return 404;
+}
+```
+
+改成：
+
+```nginx
+location = / {
+    rewrite ^ /emotion-museum/ permanent;
+}
+```
+
+这样根路径会被 301 永久重定向到 `/emotion-museum/`（前端实际部署位置）。
+
+然后 `nginx -t && nginx -s reload` 让配置生效。
+
+### 第二层：同步更新仓库内 `conf/emotion-museum.conf`
+
+保持仓库内的配置文件与真实服务器一致（作为基线参考）。同步修改：
+1. 删除之前的 `location / { alias /data/www/emotion-museum/; ... }` 通用块（真实配置没有）
+2. 新增 `location /emotion-museum/ { ... }` 前端块（与真实配置对齐）
+3. `location = /` 改为 `rewrite ^ /emotion-museum/ permanent;`
+
+**注意**：虽然仓库内配置现在不被真实 nginx include，但保持同步是为了：
+- 作为文档，记录服务器实际配置
+- 未来如果切回 sites-available 部署模式，能直接生效
+- 避免"仓库配置"和"服务器配置"分叉导致混乱
+
+## 验证步骤
+
+1. ssh 直接编辑服务器上的 `/www/server/panel/vhost/nginx/emotion-museum.conf`，改 `location = /` 块
+2. `nginx -t` 验证语法
+3. `nginx -s reload` 重载配置
+4. 浏览器访问 `https://lifescript.happylifeos.com/` 确认 301 → `https://lifescript.happylifeos.com/emotion-museum/`
+5. `/emotion-museum/` 正常返回前端页面（200）
+6. DevTools Network 无 404、Console 无报错
+7. 其他子路径（`/emotion-museum-admin/`、`/life-script/`、`/api/`、`/ws`、`/health`）不受影响
+8. 同步更新 `conf/emotion-museum.conf` 作为仓库基线
+9. 提交 git commit
+
+## 风险与回退
+
+- **影响面小**：只改 1 个 location 块（3 行），其他 location 块完全不动
+- **回退方案**：若出问题，把 `rewrite ^ /emotion-museum/ permanent;` 改回 `return 404;` 即可立即回滚
+- **不会冲突**：`/emotion-museum/`、`/emotion-museum-admin/`、`/life-script/` 都有自己的 location 块，`location = /` 精确匹配只对根路径生效
+
+## 长期改进（不在本次范围）
+
+`deploy.py nginx` 当前部署到 `/etc/nginx/sites-available/`，但服务器主配置 include 的是 aaPanel 路径，所以部署脚本实际上一直无效。后续应该：
+- 让 `deploy.py nginx` 同时更新 `/www/server/panel/vhost/nginx/emotion-museum.conf`
+- 或者在 nginx 主配置中增加 `include /etc/nginx/sites-enabled/*.conf;`
+- 本次不处理，单独跟踪