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