D126: Outline 404 root cause WHY

brain/fifth-domain/zero-point/zhuyuan/zhuyuan-channel/whys/why-outline-404-root-cause.hdlp

@@ -0,0 +1,115 @@
+# 为什么 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
+> 教训：下次修任何服务器问题，先画地图，再动手