Nginx外置缓存-error_page

一、引言：当缓存成为故障源，error_page是最后防线

在《Nginx外置缓存》系列前文中，我们构建了以OpenResty + Redis为核心的分布式缓存体系。这套架构在正常情况下表现优异，但生产环境的残酷现实是：外置缓存本身可能成为最大的单点故障。

• Redis集群主从切换期间，数百毫秒的写入阻塞导致Nginx大量504；
• 缓存服务OOM重启，所有请求瞬间穿透到源站，引发雪崩；
• Lua脚本bug导致Redis连接池耗尽，正常业务被缓存模块拖垮；
• 网络分区使Redis不可达，error_log中刷屏connection refused，用户看到默认500白页；
• 缓存返回了损坏的数据（如截断的JSON），客户端解析失败却无从恢复。

这些场景的共同点是：缓存层的异常没有被优雅地捕获和转化。默认的Nginx错误处理机制对Lua层面的异常几乎无感知，而开发者往往只关注“缓存命中时的性能”，忽略了“缓存失效时的生存能力”。

error_page指令在传统Nginx中用于自定义错误页面，但在外置缓存架构中，它的角色远不止于此——它是缓存故障与服务可用性之间的隔离阀，是降级策略的执行入口，是用户体验的最后一道保障。本文将重新定义error_page在外置缓存场景下的用法，从基础语法到高级降级模式，给出生产级容错架构。

二、error_page在外置缓存中的三重角色

2.1 角色重定义

📌核心认知：在外置缓存架构中，error_page不再是“给用户看的页面”，而是“给系统用的控制流”。它拦截的是基础设施层的异常，输出的是架构层的决策。

2.2 为什么不能只在Lua里try-catch？

很多开发者认为在Lua代码中用pcall包裹Redis操作就够了。但这有三个盲区：

1. Nginx原生错误无法捕获：proxy_pass超时、upstream连接失败等发生在C层面，Lua的pcall看不到；
2. 子请求错误不传播：ngx.location.capture返回的错误状态码不会自动触发外层Lua的异常处理；
3. 统一降级策略难维护：每个location都写一套try-catch+降级逻辑，代码膨胀且不一致。

error_page提供了声明式的、跨层级的错误处理机制，与Lua的命令式异常处理互补，而非替代。

三、基础配置：缓存错误的精准捕获

3.1 区分缓存相关错误码

server { listen 80; # ========== 缓存专用错误映射 ========== # Redis连接失败/超时 → 590 (自定义) error_page 590 = @cache_fallback_backend; # 缓存数据损坏/解析失败 → 591 error_page 591 = @cache_fallback_stale; # 源站也失败 → 592 error_page 592 = @cache_static_degraded; # 标准错误兜底 error_page 500 502 503 504 /50x.html; location /api/ { content_by_lua_block { -- Lua缓存逻辑（见下文） } } # ========== 降级处理器 ========== location @cache_fallback_backend { internal; add_header X-Cache-Degraded "redis-unavailable" always; proxy_pass http://backend; proxy_connect_timeout 3s; # ⭐ 降级时缩短超时 proxy_read_timeout 5s; } location @cache_fallback_stale { internal; add_header X-Cache-Degraded "stale-data" always; # 尝试读取本地备份或返回预设默认值 content_by_lua_block { local fallback = ngx.shared.local_cache:get("fallback:" .. ngx.var.uri) if fallback then ngx.header["X-Cache"] = "STALE-HIT" ngx.say(fallback) else ngx.status = 503 ngx.say('{"error":"service temporarily unavailable"}') end } } location @cache_static_degraded { internal; add_header X-Cache-Degraded "full-degradation" always; default_type application/json; return 503 '{"code":503,"msg":"service degraded","retry_after":30}'; } }

3.2 自定义错误码的意义

Nginx标准错误码无法区分“Redis挂了”和“源站挂了”。自定义590/591/592让监控和降级策略可以精确识别故障层级：

⚠️注意：自定义错误码仅在Nginx内部流转，不会暴露给客户端。最终对外返回的仍是标准HTTP状态码（200/503等）。

四、Lua层与error_page的桥接

4.1 在Lua中触发error_page

Lua代码不能直接“调用”error_page，但可以通过设置特定状态码来间接触发：

-- cache_handler.lua 增强版 local redis = require "resty.redis" local _M = {} function _M.get(key) local red, err = get_redis() if not red then -- ⭐ 设置自定义状态码，触发error_page 590 ngx.status = 590 ngx.log(ngx.WARN, "redis connect failed, triggering fallback: ", err) return nil, "REDIS_UNAVAILABLE" end local res, err = red:get(key) release_redis(red) if not res or res == ngx.null then return nil, "MISS" end -- 验证数据完整性 local data, decode_err = cjson.decode(res) if not data then -- ⭐ 数据损坏，触发error_page 591 ngx.status = 591 ngx.log(ngx.ERR, "cache data corrupted for key: ", key, " err: ", decode_err) return nil, "DATA_CORRUPTED" end return data, nil end return _M

4.2 content_by_lua_block中的错误处理范式

content_by_lua_block { local key = build_cache_key() -- 尝试缓存 local data, err = cache_handler.get(key) if err == "REDIS_UNAVAILABLE" or err == "DATA_CORRUPTED" then -- ⭐ 关键：exit让Nginx接管error_page处理 -- 此时ngx.status已被设为590/591 return ngx.exit(ngx.status) end if data then ngx.header["X-Cache"] = "HIT" ngx.say(cjson.encode(data)) return end -- MISS：回源并回填缓存 local res = ngx.location.capture("/internal/backend") if res.status ~= 200 then -- 源站失败，但缓存也不可用 → 触发592 ngx.status = 592 return ngx.exit(592) end -- 正常回填... cache_handler.set(key, cjson.decode(res.body), 300) ngx.say(res.body) }

4.3 三个关键陷阱

① ngx.exit必须在header发送前调用

一旦调用了ngx.say()或ngx.print()，响应头已发送，ngx.exit无法改变状态码，error_page也不会触发。所有错误判断必须在首次输出之前完成。

② error_page的=号语法决定状态码传递

# ❌ 保留原始错误码590，客户端看到非标准状态码 error_page 590 @cache_fallback_backend; # ✅ 使用=号重写为200，客户端看到正常响应 error_page 590 =200 @cache_fallback_backend; # ✅ 使用=号重写为503，客户端看到标准服务不可用 error_page 592 =503 @cache_static_degraded;

③ internal标记防止外部访问

所有降级location必须加internal;，否则攻击者可直接请求/@cache_fallback_backend绕过缓存和安全检查。

五、高级降级模式

5.1 多级降级瀑布

Redis可用 → 返回缓存数据 ↓ (590) 源站可用 → 返回实时数据（跳过缓存） ↓ (592) 本地stale可用 → 返回过期数据 ↓ (stale miss) 静态兜底 → 返回预设JSON/HTML ↓ (兜底失败) 标准503 → 最小化错误响应

实现要点：每一级降级处理器内部仍可触发下一级error_page，形成链式容错。

5.2 基于Header的条件降级

# 某些接口不允许降级（如支付、鉴权） map $uri $allow_degradation { ~^/api/payment/ 0; ~^/api/auth/ 0; default 1; } server { # 仅允许降级的接口走error_page if ($allow_degradation = 0) { set $no_fallback 1; } location /api/ { content_by_lua_block { if ngx.var.no_fallback == "1" then -- 禁用降级，直接透传错误 cache_handler.strict_mode(true) end -- ...正常逻辑 } } }

5.3 降级响应的缓存

降级响应本身也可以被短暂缓存，避免每次请求都执行降级逻辑：

location @cache_fallback_backend { internal; proxy_pass http://backend; # ⭐ 降级响应缓存5秒，减轻源站压力 proxy_cache fallback_cache; proxy_cache_valid 200 5s; proxy_cache_key "fallback:$request_uri"; proxy_cache_use_stale error timeout; }

📌注意：降级缓存的TTL必须极短（≤10s），否则会在源站恢复后仍返回旧数据，造成二次不一致。

六、可观测性：让降级可见

6.1 降级事件日志格式

log_format degradation '$remote_addr [$time_local] "$request" ' '$status $body_bytes_sent ' 'degrade_type=$http_x_cache_degraded ' 'original_status=$upstream_status ' 'response_time=$request_time'; # 仅在降级时记录 map $http_x_cache_degraded $log_degradation { "" 0; default 1; } access_log /var/log/nginx/degradation.log degradation if=$log_degradation;

6.2 Prometheus指标暴露

-- 在降级处理器中递增计数器 content_by_lua_block { local metrics = ngx.shared.metrics metrics:incr("cache_degradation_total", 1) metrics:incr("cache_degradation_" .. ngx.var.http_x_cache_degraded, 1) -- ...正常降级逻辑 }

Grafana面板应包含：

• 降级率趋势线（按类型分色）
• 降级持续时间分布
• 降级期间的源站QPS变化
• 降级恢复时间（从首次降级到完全恢复）

6.3 告警规则

- alert: CacheDegradationHigh expr: rate(cache_degradation_total[5m]) > 100 for: 1m labels: severity: critical annotations: summary: "缓存降级率超过100/s，持续1分钟" - alert: FullDegradationActive expr: cache_degradation_full_degradation > 0 for: 30s labels: severity: critical annotations: summary: "全量降级已激活，缓存和源站均不可用"

七、生产安全检查清单

八、常见踩坑速查表

九、结语

感谢您的阅读！如果你有任何疑问或想要分享的经验，请在评论区留言交流！