Nginx外置缓存error_page的实现示例

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}';
    }
}

-- 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

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)
}

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

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

# 某些接口不允许降级（如支付、鉴权）
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
            -- ...正常逻辑
        }
    }
}

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;
}

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;

-- 在降级处理器中递增计数器
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)
    -- ...正常降级逻辑
}

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