OpenResty反向代理环境中请求头丢失，涵盖Nginx指令配置、Lua脚本处理、多级代理场景

一、问题现象与应用场景

在微服务架构中，我们经常会遇到这样的场景：某天突然接到前端团队反馈，通过OpenResty网关调用的用户身份信息全部丢失。通过抓包分析发现，原本应该携带的X-User-Token请求头在到达后端服务时神秘消失。这种请求头丢失问题在以下场景尤为常见：

1. 跨系统对接场景：当与第三方系统对接时，对方要求特定的认证头（如X-API-Key）
2. 灰度发布系统：需要携带X-Canary-Version标头进行流量染色
3. 全链路追踪系统：丢失X-Request-ID导致无法追踪请求链路

笔者曾处理过一个典型案例：某电商平台的购物车服务突然无法获取会员等级头信息，导致VIP用户无法享受折扣优惠。经排查发现，问题根源正是OpenResty反向代理配置不当导致请求头丢失。

二、基础配置问题与解决方案

（Nginx指令层）

2.1 最小化问题复现

# 问题配置示例（OpenResty 1.19.3）
server {
    listen 80;
    location / {
        proxy_pass http://backend;
        # 缺失关键的头信息传递指令
    }
}

此时通过curl测试：

curl -H "X-Magic-Token: 12345" http://gateway/api

后端服务接收到的请求中将完全丢失X-Magic-Token头信息。

2.2 基础修复方案

server {
    listen 80;
    location / {
        proxy_pass http://backend;
        
        # 强制保留原始Host头（关键配置）
        proxy_set_header Host $http_host;
        
        # 透传所有原始请求头（基础方案）
        proxy_pass_request_headers on;
        
        # 透传特定自定义头（精准方案）
        proxy_set_header X-Magic-Token $http_x_magic_token;
    }
}

指令解析：

• proxy_pass_request_headers on 是默认配置，显式声明确保继承原始请求头
• proxy_set_header 实现头信息的精确控制，注意名称转换规则（下划线转驼峰）

三、进阶问题处理

（Lua脚本层）

3.1 下划线头特殊处理

当遇到包含下划线的请求头时（如X_CUSTOM_HEADER），需要特殊处理：

http {
    # 允许头信息中使用下划线（关键配置）
    underscores_in_headers on;
    
    server {
        location / {
            access_by_lua_block {
                -- 动态处理含下划线的头信息
                ngx.req.set_header("X-Custom-Header", 
                    ngx.req.get_headers()["X_CUSTOM_HEADER"])
            }
            proxy_pass http://backend;
        }
    }
}

3.2 动态头信息处理

使用Lua脚本实现请求头的动态改写：

access_by_lua_block {
    -- 获取原始请求头
    local headers = ngx.req.get_headers()
    
    -- 添加调试头信息
    ngx.req.set_header("X-Proxy-Phase", "ACCESS")
    
    -- 过滤敏感头信息
    if headers["X-Auth-Secret"] then
        ngx.req.clear_header("X-Auth-Secret")
        ngx.req.set_header("X-Auth-Status", "filtered")
    end
    
    -- 头信息格式转换
    if headers["X-User-Id"] then
        ngx.req.set_header("User-Id", string.upper(headers["X-User-Id"]))
    end
}

四、二级代理头保持

location / {
    proxy_pass http://middleware;
    
    # 保留原始客户端信息
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    
    # 自定义头传递
    proxy_set_header X-Request-Chain $http_x_request_chain,proxy01;
}

# 中间件服务配置
server {
    location / {
        proxy_pass http://backend;
        
        # 继承并追加代理链信息
        proxy_set_header X-Request-Chain "$http_x_request_chain,proxy02";
        
        # 时间戳透传
        proxy_set_header X-Proxy-Time $msec;
    }
}

五、调试与诊断方案

5.1 全链路调试配置

server {
    location / {
        access_by_lua_block {
            -- 记录原始头信息
            ngx.log(ngx.INFO, "原始请求头: ", require("cjson").encode(ngx.req.get_headers()))
        }
        
        proxy_pass http://backend;
        
        header_filter_by_lua_block {
            -- 记录后端响应头
            ngx.log(ngx.INFO, "后端响应头: ", require("cjson").encode(ngx.resp.get_headers()))
        }
    }
}

5.2 专用调试路由

location /debug/headers {
    content_by_lua_block {
        ngx.header["Content-Type"] = "text/plain"
        ngx.say("原始请求头:\n", require("cjson").encode(ngx.req.get_headers()))
        ngx.say("\n透传头配置:\n", 
            require("ngx.proxy").get_proxy_headers())
    }
}

六、技术方案对比分析

6.1 不同方案的优缺点

6.2 性能影响测试数据

在4核8G虚拟机环境下进行压力测试：

七、注意事项与最佳实践

1. 头信息大小限制：单个头字段值不超过8KB，总头大小不超过32KB
2. 敏感信息过滤：使用map指令过滤Authorization等敏感头

   map $http_authorization $clean_auth {
       default "";
       "~(.*)" $1;
   }
   

3. 编码规范：统一采用kebab-case命名（如X-User-Id）
4. 性能优化：避免在Lua脚本中进行复杂的JSON解析操作
5. 版本兼容：注意不同OpenResty版本对头信息的处理差异

八、生产级配置模板

http {
    # 基础配置
    underscores_in_headers on;
    proxy_pass_request_headers on;
    
    # 头信息白名单
    map $http_user_agent $valid_ua {
        default 0;
        "~*" 1;  # 示例正则匹配
    }
    
    server {
        listen 80;
        
        location / {
            access_by_lua_block {
                -- 头信息预处理器
                local headers = ngx.req.get_headers()
                
                -- 验证必须头
                if not headers["X-Api-Version"] then
                    ngx.exit(ngx.HTTP_BAD_REQUEST)
                end
                
                -- 添加追踪头
                ngx.req.set_header("X-Request-Id", ngx.var.request_id)
            }
            
            # 标准头传递
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            
            # 自定义头传递
            proxy_set_header X-User-Id $http_x_user_id;
            
            # 安全头处理
            proxy_set_header Authorization $http_authorization;
            
            proxy_pass http://backend;
        }
    }
}

九、总结与展望

本文深入探讨了OpenResty反向代理场景下的请求头丢失问题，通过多个实际案例展示了从基础到进阶的解决方案。在微服务架构日益复杂的今天，正确配置头信息传递机制已成为保障系统可靠性的重要基础。建议开发者在以下方面持续优化：

1. 建立头信息规范文档：明确各服务的头信息契约
2. 实施自动化测试：通过E2E测试验证头信息传递
3. 监控报警建设：对关键头信息缺失进行实时监控

随着HTTP/3协议的普及，未来的头信息处理将面临新的挑战。例如QUIC协议中头信息的压缩算法优化、多路复用连接的头信息共享机制等，都需要我们持续关注技术演进。