机窝
发布于 2026-10-11 / 5 阅读
0
0

1Panel 反代排坑:带下划线的请求头为什么没到应用

排查 Sub2API 的反向代理时,我发现配置里少了一个看起来不起眼的选项:underscores_in_headers on;。它涉及 session_id 这类带下划线的请求头。

这次记录最值得留下的,不只是这一行配置,而是怎么找到真正运行的 OpenResty、怎么避免检查错上游,以及怎样说明验证到底覆盖了什么。

应用健康,不代表所有请求信息都完整到达

健康接口返回 200,只能说明这个接口可以经当前路径访问。它通常不会验证业务请求里的每一个 Header。

因此,如果应用依赖某个特殊请求头,排查时除了看应用日志,也要检查请求从客户端到应用之间经过的反向代理。

反向代理请求路径及 Header 验证范围

Nginx 的 underscores_in_headers 默认关闭。关闭时,名称中包含下划线的请求头会被标记为无效,再由 ignore_invalid_headers 的配置决定如何处理;默认组合可能使它们被忽略。Nginx 官方指令说明

也就是说,客户端发出了 Header,不保证应用最终能收到它。配置片段如下:

http {
    underscores_in_headers on;

    # 这里仍然保留原有配置。
}

这不是一份完整的 nginx.conf,不要用它覆盖现有文件。该指令也支持 server 上下文,设置范围应按实际需求决定;我的那次修改按当时部署要求放在主配置的 http 块中。

先找到正在处理流量的进程

我的 OpenResty 由 1Panel 部署在 Docker 中。直接在宿主机运行 nginx -t,可能检查到另一套安装,也可能因为宿主机不具备容器内环境而失败。

我先确认容器和挂载,再进入实际运行的容器检查:

docker ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}'
docker inspect openresty --format '{{json .Mounts}}'
docker exec openresty /usr/local/openresty/nginx/sbin/nginx -T

这里的 openresty 是我的容器名,二进制路径也属于当时环境。复用时需要先确认自己的名字和路径。-T 会输出加载的配置,适合检查 include 文件和最终指令,也可能包含内部信息,分享前需要筛选。

域名相似,也可能指向完全不同的服务

当时服务器上有多个站点。有两个域名指向 Sub2API,另一个看起来相关的域名却指向另一套服务。

这个站点的健康路径返回了 502,但不能据此判断 Sub2API 故障。先看对应虚拟主机的 proxy_pass 和上游端口,才能确定正在测试哪个应用。

这一步让我以后更愿意先画出一条很短的路径:

本次测试的域名 → 对应虚拟主机 → 上游地址与端口 → 具体容器

如果第一步认错了服务,后面再多的重启和配置修改也可能没有意义。

修改只覆盖已经查明的缺项

确认配置缺少指令后,我备份主配置,并核对原文件校验和,避免在检查和写回之间覆盖别人的更新。修改只添加这一项,没有同时调整站点超时、缓存或其他参数。

对于 Docker 的单文件 bind mount,还要关注编辑器写文件的方式。某些编辑器通过“新文件替换旧文件”保存,容器可能仍持有旧挂载对象。我的那次处理保留了原文件 inode,随后以容器里看到的内容为准检查结果。

完成修改后,依次执行:

# 先测试语法。
docker exec openresty /usr/local/openresty/nginx/sbin/nginx -t

# 只有测试通过后才重载。
docker exec openresty /usr/local/openresty/nginx/sbin/nginx -s reload

# 重载后再查看实际配置。
docker exec openresty /usr/local/openresty/nginx/sbin/nginx -T

Nginx 的配置测试和重载行为可查阅官方控制文档。备份、修改、测试、重载和复查应按顺序执行,不宜为了方便串成一个遇到失败仍继续跑的脚本。

当时验证到了哪一步

这次记录确认了三个结果:配置语法测试通过;重载后生效配置包含新增指令;Sub2API 的公网健康接口仍返回 200。

这些结果证明改动已进入运行配置,而且健康接口可用。它们没有直接证明某次具体业务请求的 session_id 已被上游接收。

如果要进一步确认 Header 传递,应该在可控的测试环境里发一个不含凭据的标记值,再从上游日志或回显接口核对。不要为了测试临时公开真实业务 Header,也不要把 API 密钥写进日志。

我把这次排查记下来,是因为它同时涉及代理配置、容器运行环境和验证边界。以后再遇到“应用正常,但请求表现不对”,我会先沿请求路径逐层确认,而不是只看容器健康标记。


本文整理于 2026 年 10 月 11 日,复盘此前已完成的配置变更。未把健康接口成功扩大为完整业务链路验证。配图为 AI 生成的概念插画。


评论