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让监控和降级策略可以精确识别故障层级：

自定义码	含义	降级动作	告警级别
590	Redis不可用	跳过缓存，直连源站	P2
591	缓存数据异常	返回过期数据或默认值	P3
592	源站+缓存均失败	返回静态兜底响应	P1

⚠️ 注意：自定义错误码仅在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: "全量降级已激活，缓存和源站均不可用"

---

七、生产安全检查清单

检查项	状态	说明
所有降级location标记internal	☐	防止外部直接访问
error_page使用=号重写状态码	☐	避免暴露自定义码给客户端
Lua中ngx.exit在输出前调用	☐	否则error_page不生效
降级超时比正常超时短	☐	避免降级本身成为瓶颈
降级响应有明确标识Header	☐	X-Cache-Degraded便于调试和监控
关键接口禁用降级	☐	支付/鉴权等不接受脏数据
降级日志独立采集	☐	不影响正常access_log性能
降级指标接入告警	☐	降级是事故，不是常态
定期演练降级流程	☐	模拟Redis故障验证链路
兜底响应经过测试	☐	确保JSON格式正确、客户端可解析

---

八、常见踩坑速查表

现象	根因	解决方案
error_page未触发	Lua已发送header后才set status	错误判断前置，首次输出前exit
客户端收到590状态码	error_page缺少=号重写	改为error_page 590 =200 @handler
降级location被外部访问	缺少internal指令	添加internal;
降级后源站被打垮	降级响应未做短时缓存	添加proxy_cache 5s
降级日志缺失	log_format未匹配自定义Header	检查map条件和变量名
循环降级	降级处理器内部又触发相同error_page	限制降级深度或使用不同错误码
Lua pcall吞掉错误	pcall成功但返回nil未检查	显式判断返回值并设置ngx.status
降级响应格式错误	未设置default_type	添加default_type application/json
监控看不到降级事件	指标未在降级处理器中递增	在每个@handler中添加计数逻辑
支付接口返回降级数据	未按URI排除降级	map配置no_fallback标记

---

九、结语

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