116 lines
3.6 KiB
Plaintext
116 lines
3.6 KiB
Plaintext
# 为什么 Outline 一直 404 · 根因分析
|
||
|
||
> HLDP://zhuyuan/channel/whys/why-outline-404-root-cause
|
||
> 类型: WHY · 故障根因 · 点修 vs 全局地图
|
||
> 日期: D126 · 2026-06-06
|
||
> 映射: BS-SG-001-server-map.hdlp · Nginx配置
|
||
|
||
---
|
||
|
||
## 现象
|
||
|
||
Outline 部署后，页面显示 "Failed to load configuration"。换了多个浏览器、无痕模式、清理缓存，全部一样。
|
||
|
||
## 点修过程（错误的修复方式）
|
||
|
||
**第一次点修：** 以为是 Dex 路径问题 → 修 Nginx /dex/ proxy_pass → 没好
|
||
|
||
**第二次点修：** 以为是 /auth/ 路由不全 → 改 location /auth/oidc 为 /auth/ → 没好
|
||
|
||
**第三次点修：** 以为是 Service Worker 缓存 → 加 no-cache 头 → 没好
|
||
|
||
**第四次点修：** 以为是数据库没团队 → 直接 INSERT teams + authentication_providers → 没好
|
||
|
||
每次修完在服务器上 curl 测试都是 200，但浏览器打开还是错误。
|
||
|
||
## 为什么点修永远修不好
|
||
|
||
点修的问题：**只看到单个请求的响应，没看到整个请求链路。**
|
||
|
||
## 全局地图方法（正确的修复方式）
|
||
|
||
### 第一步：画完整请求链路
|
||
|
||
```
|
||
浏览器加载 outline/
|
||
├─ GET /outline/ → HTML (200 ✅)
|
||
├─ GET /static/... → JS/CSS (200 ✅)
|
||
├─ POST /api/auth.info → 401 ✅ (需要登录)
|
||
├─ POST /api/auth.config → 404 ❌ (配置加载失败)
|
||
└─ POST /api/auth.delete → 401 ✅
|
||
```
|
||
|
||
### 第二步：找到 404 的根源
|
||
|
||
看 Nginx access log：
|
||
|
||
```
|
||
POST /api/auth.info Referer: https://guanghubingshuo.com/outline/ → 401 ✅
|
||
POST /api/auth.config Referer: https://guanghubingshuo.com/ → 404 ❌
|
||
```
|
||
|
||
**发现：同一个页面发出的两个 API 请求，Referer 不一样。**
|
||
|
||
auth.info 的 Referer 是 outline/，auth.config 的 Referer 是首页。
|
||
|
||
### 第三步：看懂 Nginx 路由规则
|
||
|
||
```nginx
|
||
map $http_referer $outline_api_upstream {
|
||
default "http://127.0.0.1:3998"; # hldp-gate
|
||
"~*outline" "http://127.0.0.1:3090"; # Outline
|
||
}
|
||
|
||
location /api/ {
|
||
proxy_pass $outline_api_upstream; # 按 Referer 路由
|
||
}
|
||
```
|
||
|
||
**问题：auth.config 请求的 Referer 是首页，不匹配 ~*outline，被路由到 hldp-gate → 404**
|
||
|
||
### 第四步：根因确认
|
||
|
||
Outline 的 JavaScript 代码：
|
||
- auth.info 调用时，浏览器还在 outline/ 页面 → Referer 正确
|
||
- auth.config 调用时，可能页面已经跳转或 Referer 被浏览器设置为首页 → Referer 错误
|
||
|
||
不是 Outline 后端问题，不是 Dex 问题，不是数据库问题。
|
||
|
||
**是 Nginx 路由规则依赖 Referer，但 Outline 的 API 调用 Referer 不一致。**
|
||
|
||
### 第五步：正确修复
|
||
|
||
不再依赖 Referer，直接按路径路由：
|
||
|
||
```nginx
|
||
# 所有 /api/auth.* 请求直连 Outline，不走路由表
|
||
location ~ ^/api/auth\. {
|
||
proxy_pass http://127.0.0.1:3090;
|
||
...
|
||
}
|
||
|
||
# 其他 /api/ 请求保持原有路由逻辑
|
||
location /api/ {
|
||
proxy_pass $outline_api_upstream;
|
||
}
|
||
```
|
||
|
||
## 关键认知
|
||
|
||
| 点修 | 全局地图 |
|
||
|------|----------|
|
||
| 看到 "Failed to load configuration" → 猜是配置问题 → 修配置 | 画出完整请求链路 → 发现 auth.config 404 → 看 Nginx log → 发现 Referer 不一致 → 看 Nginx 配置 → 发现路由规则问题 |
|
||
| 每次测试用 curl 单点验证 | 看浏览器实际发出的所有请求序列 |
|
||
| 修了 5 次没好 | 1 次找到根因 |
|
||
|
||
## 结论
|
||
|
||
⊢ 点修 = 没有地图的盲人摸象
|
||
⊢ 全局地图 = 先看清楚整个系统怎么连的，再动手
|
||
⊢ 冰朔说得对："点修永远修不好"
|
||
|
||
---
|
||
|
||
> 铸渊 ICE-GL-ZY001 · D126
|
||
> 教训：下次修任何服务器问题，先画地图，再动手
|