这周又接到一个“帮忙看看Nginx配置”的活。项目跑了三年conf文件几百行里面代理、缓存、重写三类指令混在一起注释掉的、临时补丁、旧版本规则各占一半。说真的这种配置能跑但没人能保证它明天还正常。Nginx的最大特点是指令简单、组合复杂。单独看代理、缓存、重写每一项都不算难难的是它们组合起来后的行为是否符合预期。下面我基于这些年配Nginx、查Nginx、被Nginx坑过的经验把这三块核心能力从头到尾梳理一遍重点是配置文件里看不出来的执行顺序和边界条件。适合两类人刚接手Nginx想系统入门的以及配置全靠复制粘贴、出了故障不知道怎么下手的同学。1. 代理配置的三个关键细节location匹配、proxy_pass与header透传1.1 location匹配规则先记住优先级再谈转发代理配置的第一步不是写proxy_pass而是确定请求到底会落到哪个location。很多“诡异”的转发根源都是location匹配优先级和直觉不符。Nginx的location匹配顺序不是按配置文件里的书写顺序决定的而是按类型优先级精确匹配最高一般用于健康检查、固定路径^~前缀匹配命中后不再检查后面的正则正则匹配按书写顺序执行~区分大小写、~*不区分普通前缀匹配取最长的那一个。下面这个例子覆盖了四种常见写法location /api/health { ... } location ^~ /static/ { ... } location ~ \.(js|css|png)$ { ... } location /api/ { ... }请求/api/health走第一个/static/app.js走第二个因为^~阻止了后面的正则/api/user走第四个。最容易踩的坑是/api/如果只是普通前缀而后面有一条能匹配到/api/的正则比如location ~ /api/那即使/api/前缀更长正则也会优先命中。所以当你希望某个前缀“锁定”不被正则干扰时必须写成^~或。我见过太多配置把/admin/写成普通前缀结果被一条很宽泛的正则劫持走后台地址打不开排查了大半天才找到原因。理解优先级之后再看转发就清楚多了。location只是入口选择真正的转发行为由proxy_pass决定这是第二个容易出错的地方。1.2 proxy_pass带不带URI的差别转发路径要怎么选同一个locationproxy_pass后面带不带斜杠转发结果完全不同。很多人觉得末尾斜杠是风格问题其实它直接改变转发路径。区别看这张表写法实际转发URI典型场景proxy_pass http://backend;完整保留原始URI后端接口路径与前端一致proxy_pass http://backend/;用“/”替换location前缀剥离前端统一前缀proxy_pass http://backend/v2/;用“/v2/”替换location前缀前后端版本号不一致举例说明。假设location /api/且请求是/api/userproxy_pass http://backend;转发到/api/user后端看到完整路径。proxy_pass http://backend/;转发到/user/api被“吃掉”了。proxy_pass http://backend/v2/;转发到/v2/user适合前端路径不变、后端已换版本号的场景。反过来如果你想要保留/api/前缀但proxy_pass带了末尾斜杠后端路由里没有/user就会一直404。这个坑在从单体拆微服务时尤其频繁前端路径没变后端路径全变了于是有人开始到处加rewrite最后配置就没法看了。更隐蔽的是如果proxy_pass的地址里带变量比如proxy_pass http://backend$request_uri;行为会变成“使用变量值作为完整转发URI”原来的“保留location前缀”逻辑不再适用。这种写法尽量少用除非你彻底清楚后果。提示proxy_pass 的末尾斜杠不是风格问题它直接改变转发路径。凡是改动proxy_pass都要用 curl 实测一次再收工。1.3 转发时的header与超时后端为什么拿不到真实IP代理转发不只是把流量导过去还要把客户端信息传递给后端。下面这段是生产环境最常用的header配置location /api/ { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 120s; proxy_pass http://api_backend; }为什么要层层设置因为不设置的话后端看到的是Nginx的IP而不是客户端IP日志分析、接口限流、异地登录判断全都会失效。$proxy_add_x_forwarded_for表示“已有的XFF值 当前连接的对端IP”这样在有多层代理时能追加而不是覆盖。Host也要还原成原始域名否则后端做虚拟主机、生成绝对链接时会出现奇怪的结果。超时参数需要分别理解。proxy_connect_timeout是Nginx与后端建立TCP连接的超时proxy_send_timeout是发送请求体到后端的超时proxy_read_timeout是等待后端返回响应的超时这是大多数504的来源。后端接口如果处理时间本身要几十秒比如导出报表、调用第三方接口read_timeout只给默认60秒就会定时炸。但反过来不要把read_timeout无限调大否则后端真挂死时Nginx的worker会一直占着连接不释放故障会从后端蔓延到前置入口。2. proxy_cache缓存链路从缓存键设计到命中率调优2.1 缓存目录与keys_zone两级缓存结构的作用Nginx的代理缓存是“内存索引 磁盘文件”的结构。配置核心就一行proxy_cache_path /data/nginx_cache levels1:2 keys_zonestatic_cache:50m max_size10g inactive60m use_temp_pathoff;/data/nginx_cache是缓存文件落盘目录。levels1:2表示缓存文件按MD5值建立两级子目录第一级1个字符第二级2个字符目的是避免几万个文件堆在同一个目录里否则文件系统查找效率会直线下降。keys_zonestatic_cache:50m是在共享内存里给缓存键建索引50m大约能存几万个到几十万个key按实际业务调整。max_size10g是磁盘缓存上限超过后按LRU淘汰。inactive60m表示缓存项在60分钟内没有被访问就会被清理注意它和max_size的淘汰机制不是一回事。use_temp_pathoff表示缓存文件直接写入最终目录而不是先写临时目录再重命名能少一次磁盘拷贝性能更好。实际使用时proxy_cache_path只能写在http块一个缓存区对应一个keys_zone。如果你既想缓存静态资源又不想让不同业务的key互相干扰可以配置多个缓存区业务之间互不污染。2.2 缓存键设计命中率上不去的真正原因缓存命中率上不去第一个要查的就是proxy_cache_key。默认配置是proxy_cache_key $scheme$proxy_host$request_uri;request_uri带了完整参数。问题来了如果接口URL带时间戳、随机数或者每页数据都要重新请求那每个URL都是全新key缓存永远MISS。我见过一个实际案例前端轮询接口/api/list?ts1720000000ts随每次请求变化结果Nginx缓存了成千上万份内容基本相同的响应缓存目录暴涨命中率却是0。调整方式很直接把动态参数从缓存键里剔除只保留业务上能区分内容的参数proxy_cache_key $host$uri$is_args$arg_page;这里$is_args在有参数时是“?”没有时是空$arg_page只取page参数作为区分。如果参数很多建议用“白名单”的思路而不是把整个query塞进key。还要警惕Cookie带来的串数据问题。Nginx默认不缓存带Set-Cookie的响应这是一层保护。如果你在缓存区里设置了proxy_ignore_headers Set-Cookie;把保护关掉了但缓存键里又没有用户信息那A用户登录后看到的页面可能被缓存B用户再访问就拿到了A的数据。这种问题上线后很难查因为它不是报错是逻辑串了。我的原则是涉及用户身份、权限、个性化内容的接口不要进缓存只把公开数据、静态资源、大列表这类真正无差别的响应放进代理缓存。2.3 缓存失效主动清理与被动过期的取舍缓存失效是比缓存命中更麻烦的问题。被动的过期靠proxy_cache_valid和上游返回的响应头控制比如proxy_cache_valid 200 301 302 24h; proxy_cache_valid 404 1m;意思是200/301/302状态缓存24小时404只缓存1分钟。404缓存时间设短是故意的既避免频繁回源又不会把错误页面长期固化成“永久404”。主动清理方面开源版Nginx默认不提供缓存清理接口这是众所周知的痛点。社区有一个ngx_cache_purge模块可以用配置类似location ~ /purge(/.*) { allow 127.0.0.1; deny all; proxy_cache_purge static_cache $host$1; }加了这个模块后访问/purge/路径就能定向清除缓存但生产环境要严格限制来源IP否则任何人拿着这个地址都能把缓存清空等于给攻击者开了一扇门。没有这个模块的情况下也可以写脚本按缓存key的MD5去定位文件删除。方向是先确定你完整的缓存key字符串比如example.com/assets/app.js算MD5再结合levels1:2的目录规则找到文件。这个方案能应急但每次改缓存键格式都要同步改脚本我一般只在没有purge模块的机器上兜底用。验证缓存是否生效用curl -I看响应头就行。X-Cache-Status的常见值HIT表示命中MISS表示未命中EXPIRED表示过期回源BYPASS表示跳过缓存。第一次请求看到MISS是正常的第二次同URL看到HIT才算配置成功。3. rewrite与try_filesURL改写背后的执行顺序陷阱3.1 四个flag的区别last、break、redirect、permanentrewrite的四个flag是很多人的知识盲区。它们表面只是“结尾加不加一个词”实际行为差别很大flagrewrite后行为浏览器地址栏是否变化典型场景last停止当前rewrite重新进入location匹配否改写后要落到另一个locationbreak停止rewrite留在当前location继续执行否改写后继续proxy_passredirect返回302临时重定向是临时迁移、调试期跳转permanent返回301永久重定向是旧域名、旧路径永久迁移last和break是重灾区。举个经典场景把/old/下的请求映射到/new/的文件location /old/ { rewrite ^/old/(.*)$ /new/$1 last; } location /new/ { alias /data/www/new/; }这里必须用last因为改写后需要重新匹配到/new/这个location才能用alias找到文件。如果你把last写成breakrewrite停止后就不会重新匹配当前/old/这个location里如果没有对应的root/alias最终会404。反过来如果在location里写rewrite目的只是把URL改成后端真正需要的路径然后同一location继续往下走proxy_pass那应该用break而不是last否则last重新匹配时可能命中另一个location再来一次代理链路就乱套了。redirect和permanent的坑在于301的缓存效应浏览器会对301永久重定向做本地缓存之后直接访问旧地址会跳过请求直接跳新地址。如果你的重定向规则后续要调整千万别在生产环境用permanent测试。先用302确认无误后再切301。3.2 try_files与SPA路由比rewrite更安全的方案前后端分离项目前端路由用的是history模式时用户直接访问/user/123这个地址后端并没有这个文件Nginx需要把它交给index.html去处理。很多人第一反应是rewrite但其实try_files更合适location / { root /data/frontend/dist; index index.html; try_files $uri $uri/ /index.html; }try_files的逻辑是先按顺序尝试文件。$uri存在就直接返回静态文件$uri/存在就尝试目录下的index都不存在就内部重写到/index.html。它比rewrite ^(.*)$ /index.html last安全的地方在于文件真实存在时直接返回不会因为rewrite规则写得宽泛而误伤静态资源。这里有一个很常见的404场景前端项目部署在子路径比如访问/admin/但配置写成了location /admin { root /data/frontend/dist; try_files $uri /index.html; }结果/admin/被当成文件找自然404。root和alias的差别也是这里的核心root会把location前缀拼到路径后面alias则是直接替换。如果项目不在根路径我建议明确用alias /data/frontend/dist/而不是 root。3.3 重写与代理结合rewrite之后URI到底变成什么rewrite和proxy_pass组合时很多人以为rewrite改的是“最终转发出去的URL”其实它改的是Nginx内部的URI后面的proxy_pass接受到的就是这个改写后的URI。举个例子对外保持/v1/路径不变但后端实际已经升级到/v2/location /v1/ { rewrite ^/v1/(.*)$ /v2/$1 break; proxy_pass http://backend; }这里用break因为我们要停留在当前location内继续执行下面的proxy_pass如果写成lastNginx会用改写后的/v2/xxx重新匹配location万一有一个location /v2/就变成二次代理了链路反而更长。顺带说一个容易误解的知识点Nginx的mirror模块在做流量复制时很多人以为镜像请求会影响主请求的响应时间或超时。实际上mirror是独立子请求主请求的proxy_read_timeout只取决于真实后端的响应速度。线上偶发504优先查主后端耗时而不是甩锅给mirror。另外Nginx的rewrite正则语法基于PCRE但不支持部分高级断言写法我见过有人在规则里直接用(?!...)结果编译都过不了。写rewrite之前先在本地用小样本路径验证正则本身的正确性。4. 一个前后端分离项目的代理、缓存、重写组合配置4.1 完整配置模板从HTTP到HTTPS把前面三章的东西串起来最有代表性的场景是前后端分离项目。前端通常是打包后的静态文件后端是一组API静态资源还要考虑缓存。下面这套配置我改过很多版是目前比较稳的组合upstream api_backend { server 192.168.1.10:8080 max_fails3 fail_timeout30s; keepalive 32; } proxy_cache_path /data/nginx_cache/static levels1:2 keys_zonestatic_cache:50m max_size10g inactive60m use_temp_pathoff; server { listen 80; server_name example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; http2 on; server_name example.com; ssl_certificate /etc/nginx/certs/example.com.pem; ssl_certificate_key /etc/nginx/certs/example.com.key; root /data/frontend/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /assets/ { proxy_cache static_cache; proxy_cache_valid 200 301 7d; add_header X-Cache-Status $upstream_cache_status; expires 7d; proxy_pass http://asset_server; } location /api/ { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass http://api_backend; proxy_connect_timeout 5s; proxy_read_timeout 60s; } }几个设计点说一下location /用try_files处理SPA路由location /assets/专门做长缓存location /api/做代理且不缓存。静态资源是“适合长缓存”的页面是“必须实时”的API大多是“不能缓存”的三类流量分开处理比一个location里堆所有指令清晰得多。4.2 执行顺序代理、缓存、重写到底谁先发生组合配置里的“诡异问题”大多来自对执行顺序的错误理解。一个请求到达Nginx后主要经历的顺序大致是选择server - 匹配location - 执行rewrite阶段 - 执行access/内容生成阶段 - 输出过滤。proxy_cache在内容生成时生效rewrite在它之前。这带来几个实际结论rewrite先于proxy_pass执行所以proxy_pass转发的是改写后的URI。proxy_cache_key基于改写后的URI计算。如果你在location里做了rewrite缓存键和原始URL可能对不上。try_files的内部重写会重新选择location可能走第二遍rewrite阶段。举一个我实际排查过的故障项目在/api/的location里做了rewrite把/api/user改写为/v1/user但proxy_cache_key里没有把rewrite后的URI考虑进去缓存键只看域名和原URI结果不同接口共用了一个key。用户访问/api/user拿到的是/api/order的缓存数据线上数据串了。这个案例的本质就是缓存键没有忠实反映响应内容来源。所以组合配置时我建议每个location只做“一件事”要么代理、要么缓存、要么重写。非要做两件以上先在测试环境把两三次请求的响应头、返回体都打出来确认一遍。4.3 验证与压测curl和JMeter确认转发行为配完配置别急着上线。先用工具验证三件事转发路径是否正确、缓存是否命中、重写是否到位。curl是最快的验证手段curl -I http://example.com/assets/app.js curl -I http://example.com/api/health-I只看响应头X-Cache-Status的值一眼就能确认缓存状态。想看完整转发结果用curl -v或直接不带-I看返回体。域名跳转也是一样curl -I http://example.com/应该看到301和Location头。JMeter这边调试Nginx时可以用它自带的HTTP代理服务器录制脚本。思路是本地开JMeter代理浏览器走这个代理把一组真实请求录下来之后在JMeter里回放用来反复验证Nginx行为。这个流程对排查“为什么这个接口缓存不命中”“为什么这个路径会跳转”很有效因为你能精准重放请求而不是手工一条条敲。压测时还有一个高频问题Nginx压测时CPU很高系统出现大量TIME_WAIT。这通常不是Nginx本身不行而是upstream没开keepalive每次请求都和Java/PHP后端新建TCP连接。上面配置里upstream后面的keepalive 32就是为了复用连接。后端也要支持HTTP/1.1 keepalive否则配置了也没效果。5. 排错链路与运维动作502/504、缓存失效、证书与平滑升级5.1 从502到504代理故障到底坏在哪一层502和504是Nginx代理场景下最常见的报错但很多人分不清它们的区别。502是“Nginx与后端建立连接失败”比如后端进程没起来、端口不对、防火墙拦截error.log里通常能看到connect() failed (111: Connection refused)。504是“连接建好了但后端在规定时间内没返回响应”error.log里出现upstream timed out (110: Operation timed out)。排错时我会按下面这个顺序来先看error.log的报错关键字区分是连接失败还是读超时。从Nginx机器上直接curl后端的地址确认后端本身通不通curl -w time_total:%{time_total}\n -o /dev/null -s http://127.0.0.1:8080/api/health如果后端通但慢对比Nginx的proxy_read_timeout是不是设置得太小。如果后端不通检查后端进程、监听端口、防火墙、upstream里的IP和端口是否写对。一个容易忽略的点如果upstream配置的是unix socket错误可能是connect() failed (2: No such file or directory)这时优先检查socket文件路径和运行Nginx的用户有没有访问权限。还有就是504频繁出现时不要无脑调大proxy_read_timeout。超时时间调大只是把症状往后推后端如果本身有性能瓶颈该排查的是数据库慢查询、第三方接口、GC停顿这些根因。5.2 缓存失效的主动清理purge模块与脚本兜底缓存“清不掉”是生产环境很尴尬的问题。前面第2章提到被动过期和purge模块这里补一个更落地的做法。如果你编译Nginx时带上了ngx_cache_purge配置一个受保护的清理入口location ~ /purge(/.*) { allow 127.0.0.1; deny all; proxy_cache_purge static_cache $host$1; }然后通过curl http://127.0.0.1/purge/assets/app.js定向清理注意只允许本机访问。如果没有purge模块可以用脚本按缓存key的MD5去删文件。缓存key是example.com/assets/app.js这类完整字符串md5sum计算后取相应位作为目录和文件名。由于不同Nginx版本的缓存文件组织方式有差异用脚本前先在一个缓存文件上验证路径规则别拿生产数据试错。还有一个“暴力但有效”的办法直接清空缓存目录然后nginx -s reload。代价是清空后的第一波请求全部MISS回源压力会突然变大适合业务低峰期操作。日常发布如果只是更新静态资源更推荐给文件名加版本号或hash让浏览器和代理层都自然换新资源而不是每次发布都去清一遍缓存。缓存失效要解决的问题一部分其实可以通过命名策略规避掉。5.3 HTTPS证书替换与HTTP跳转别让证书问题拖垮站点代理层做了HTTPS终止后证书管理就落到Nginx身上。替换证书的流程不复杂拿到新证书文件替换ssl_certificate和ssl_certificate_key指向的文件nginx -t检查再reload。openssl s_client可以快速验证线上证书是否正常openssl s_client -connect example.com:443 -servername example.com -brief常见问题是证书链不完整。很多机构签发的证书是“服务端证书中间证书”两份需要拼接成一份pem拼接顺序要先服务端证书、后中间证书。顺序反了或漏了浏览器可能提示证书不受信任但curl在部分系统上又正常很容易漏排。另一个常见问题是HTTP跳转HTTPS尽量用return 301 https://$host$request_uri;而不是rewrite来实现return在rewrite阶段直接结束请求开销比走一遍规则小得多。如果你用的是自签名证书做内网测试记得只在测试环境用别把自签名证书推向生产。公网站点证书无论从哪个机构购买更新流程都是“验证签发 - 替换文件 - reload - 用s_client复查”差异只在申请渠道。5.4 平滑升级与reload线上配置变更的安全操作最后聊一下操作层面的事。修改Nginx配置后第一步永远是nginx -t它能提前发现语法错误、路径错误、指令块不匹配。通过后再执行nginx -s reload。reload不是重启它的机制是主进程重新读取配置拉起新配置的worker进程旧worker进程处理完已有的连接后自然退出。所以线上连接不会被粗暴切断适合频繁发配置的场景。如果你要升级Nginx版本平滑升级的流程稍微复杂一些kill -USR2 $(cat /var/run/nginx.pid) kill -WINCH $(cat /var/run/nginx.pid)USR2信号让旧主进程启动新版本的可执行文件作为新主进程WINCH让旧worker开始优雅退出。确认新版本工作正常后再对旧主进程发QUIT信号完成收尾。如果新版本有问题旧主进程还在可以通过向旧主进程发送HUP信号让它重新拉起worker实现回滚。这套流程我建议在测试环境完整演练一遍再上生产因为涉及信号顺序敲错一个就可能出现两个master并存线上负载被分走一半却不自知。我个人这几年的习惯是每次改Nginx配置都会把旧路径、新路径、带参数、不带参数、带Cookie、不带Cookie的请求分别用curl打一遍确认跳转、转发、缓存都符合预期后才敢说这次改完了。Nginx的指令单看都不难难的是组合后的行为与其靠直觉不如靠验证。