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操作就够了。但这有三个盲区：

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: "全量降级已激活，缓存和源站均不可用"

七、生产安全检查清单

八、常见踩坑速查表

九、结语

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