107 lines
4.0 KiB
Markdown
107 lines
4.0 KiB
Markdown
---
|
||
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;`
|
||
- 本次不处理，单独跟踪
|