做 Web 开发这几年我有一半以上的“线上事故”最后都在 Nginx 配置里找到了答案。无论是本机起一个多端口开发环境通过反向代理把内网服务暴露出去还是给站点替换 HTTPS 证书Nginx 几乎无处不在。它本身并不复杂复杂的是理解它在一条完整请求链路里的位置——客户端到 Nginx 是一段Nginx 到后端服务又是一段每一段都对应一组独立的配置。这篇文章是我在实际使用中沉淀下来的 Nginx 详解从核心原理、安装方式到多站点配置、反向代理、负载均衡、SSL 证书替换再到容器部署、监控和安全加固尽可能把高频的坑一次性讲透。适合刚接触 Nginx 的开发新手也适合已经用了两三年、但对某些异常告警仍然似懂非懂的运维同学。1. 先摸清Nginx的“人设”进程模型和配置结构决定你后面怎么写1.1 事件驱动不是空话它决定了并发上限很多人第一次听到 Nginx 的卖点是“高性能”但高性能到底从哪来答案就四个字事件驱动。传统的 Web 服务器处理请求时往往是一个进程或线程对应一个连接连接多了就得拼命开线程内存和上下文切换的开销很快就把机器拖垮。Nginx 不一样它的 worker 进程采用异步非阻塞的方式处理连接一个 worker 可以同时照看成千上万个连接哪个连接有数据可读、可写它才去处理哪个。我用一个餐厅的类比来解释传统 Apache 的做法是每个客人安排一个专职服务员客人多了服务员就爆炸Nginx 的做法是少数几个训练有素的服务员全场跑动谁举手就服务谁没需求的客人绝不打扰。这套机制决定了 Nginx 的并发能力并不取决于进程数而主要取决于worker_connections这个连接数配置。要估算一台 Nginx 大概能支撑多少并发业内有一个粗略公式最大并发连接数 ≈ worker_processes × worker_connections。假设你配置了 4 个 worker每个 worker 的连接数是 1024理论上就有 4096 的并发能力。但要注意这只是 Nginx 进程能够维持的连接上限最终还会受到 Linux 系统文件描述符限制、后端服务处理能力、内存等多重约束。后面讲 TCP 最大连接数时我会再展开。1.2 master和worker为什么reload比restart温柔安装完 Nginx第一件事是搞懂它的进程模型。Nginx 启动后会有一个 master 进程它主要负责读配置、管理 worker 进程的生死真正处理请求的是若干个 worker 进程master 不直接参与业务。这个设计不只是为了稳定性更是为了“平滑更新”——你修改了配置后执行nginx -s reloadmaster 会启动一批使用新配置的 worker然后让旧 worker 优雅退出正在处理的请求还能继续完成连接不会中断。很多新手习惯改完配置直接nginx -s stop再nginx等于把服务硬切一刀代价是线上用户掉线。我在生产环境里改配置默认只用两种方式改完执行nginx -t校验语法正确后再nginx -s reload。配置语法错误时 reload 不会生效所以先校验这个习惯一定不能省。提示restart无论你是用 systemctl 还是直接 kill 掉进程再启动和reload完全是两回事。非升级 Nginx 二进制文件的情况下能用 reload 解决的事就不要 restart。1.3 配置文件的组织骨架Nginx 的配置是树状的核心层级从大到小依次是main全局配置、events事件模型、httpHTTP 服务、server虚拟主机、location路由规则。指令放在哪个层级作用范围就覆盖到哪里。最常见的“配置不生效”问题八成是把指令放错了层级。比如worker_processes只能放在全局块listen只能出现在server里proxy_pass只在location或server里才有意义。写一个最简骨架worker_processes auto; events { worker_connections 1024; use epoll; } http { include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; server { listen 80; server_name example.com; root /var/www/html; } }mime.types是文件扩展名和 Content-Type 的映射表不引入的话所有静态文件都会被当成application/octet-stream下载而不是在浏览器里正常显示。sendfile开启后静态文件可以直接从内核态发出去不用拷贝到用户态性能提升非常明显。这些都属于“看起来不起眼、实际上影响体验”的细节。2. 安装Nginx这件事Linux、Windows和容器里藏了哪些坑2.1 Linux 下的三种安装方式先说最常用的 Linux 服务器。安装 Nginx 基本有三条路每条路的适用场景不一样。第一种是系统自带包管理器Debian/Ubuntu 系用apt install nginxCentOS/RHEL 系用yum install nginx。好处是安装快、和系统集成好坏处是版本通常偏旧比如 Ubuntu 20.04 自带的还是 Nginx 1.18 左右一些新模块比如 mirror 模块的默认开启行为和旧版本有差异。测试环境用这个最省事。第二种是添加 nginx.org 官方源然后从官方源安装。版本新模块齐全适合生产环境。CentOS 上大致是写一个/etc/yum.repos.d/nginx.repo内容指向官方仓库Ubuntu 则添加官方 apt 源并导入签名。第三种是源码编译。如果你需要自定义模块路径、编译特殊模块或者对性能有定制要求就走这条路。示例步骤简化如下./configure --prefix/usr/local/nginx \ --with-http_ssl_module \ --with-http_stub_status_module \ --with-stream make make install这里必须强调一个坑如果一开始编译时没带--with-http_ssl_module后面想用 HTTPS 是跑不起来的得重新编译整个 Nginx。虽然 Nginx 从 1.9.11 以后默认就带 SSL 模块但很多老教程和旧系统包不是这样nginx -V先看一下最稳妥。我把三种方式放一个表里方便对比安装方式优点缺点适用场景系统包管理器简单、与系统集成好版本可能偏旧本地测试、快速验证nginx.org 官方源版本新、模块全需要手动添加源生产环境推荐源码编译完全可控、可定制模块安装升级都麻烦特殊模块、嵌入式环境2.2 Windows 下怎么跑Windows 上跑 Nginx 通常是为了本地开发模拟线上环境。从 nginx.org 下载 Windows 版 zip 包解压到无中文、无空格的路径下我习惯放C:\nginx直接双击nginx.exe或者命令行执行start nginx就启动了。停止和重载分别是nginx -s stop和nginx -s reload。Windows 下最常见的坑有三个。第一是 80 端口被占用IIS、SQL Server Reporting Services、Skype 都可能占 80netstat -ano | findstr :80查一下找到 PID 再处理或者直接把listen改成 8080。第二是路径问题中文路径在某些情况下会导致静态文件 404。第三是 Windows 版没有真正的 master 进程进程管理相对脆弱nginx -s reload偶尔会失效遇到这种情况就直接重启进程。2.3 容器场景alpine挂载conf.d报错为什么这么常见用 Docker 跑 Nginx 已经是常态但docker run挂载配置文件时经常会出问题尤其是nginx:alpine镜像。典型的报错类似nginx: [emerg] unknown directive或者open() /etc/nginx/conf.d/default.conf failed (13: Permission denied)。我排查过几次根因集中在三处。第一是nginx.conf主配置文件里没有include /etc/nginx/conf.d/*.conf;这行导致挂载进去的文件根本没被加载。第二是宿主机挂载文件的属主和容器内 Nginx worker 的用户不一致alpine 镜像里运行用户是nginxUID 101宿主机文件如果权限过严就读不了。第三是挂载时只挂了一个文件到目录里但文件路径和容器内预期的路径不一致。正确的挂载方式是docker run -d \ -v /host/conf.d:/etc/nginx/conf.d:ro \ -v /host/nginx.conf:/etc/nginx/nginx.conf:ro \ -p 80:80 \ nginx:alpine挂载完后不要急着重启先在容器内执行docker exec 容器名 nginx -t看语法是不是真的通过。很多报错在宿主机上根本看不出来进容器看是最快的方式。2.4 卸载与残留卸载 Nginx 看起来简单但残留配置和日志很容易坑到后面的项目。Debian/Ubuntu 系用apt remove nginx只卸载二进制想连配置一起清掉要用apt purge nginx nginx-common。CentOS 系yum remove nginx也会留下/etc/nginx目录。如果是源码编译安装进入源码目录执行make uninstall但很多自定义编译路径下 Makefile 不一定带 uninstall 目标那就得手动删除/usr/local/nginx、日志目录和/etc/init.d/nginx脚本。卸载完我还会检查/var/log/nginx、/var/cache/nginx是否残留避免新装的 Nginx 被旧日志干扰判断。3. 多端口、多站点、自定义域名本地与虚拟机开发环境的一次完整搭建3.1 场景定义与整体拓扑先描述一个我反复用到的开发场景本地一台电脑外加一台 Linux 虚拟机。我希望访问http://project-a.local时走虚拟机上的 Nginx由它代理到后端的 8080 服务访问http://project-b.local时走本地机器的某个 Node 服务端口是 3000。两个域名都要能通端口可以不同配置还要互不干扰。这个需求拆开就是三件事Nginx 按域名区分站点server_name、按路径转发到不同后端proxy_pass、本地通过 hosts 文件把自定义域名指到对应机器。理解了这三件事多站点开发环境的骨架就搭起来了。3.2 server块监听、域名、目录Nginx 用server块表示一个虚拟主机。决定请求匹配到哪个 server 的关键有两个listen的端口以及server_name的域名。当请求到达时Nginx 首先按端口过滤再按域名匹配。如果两个 server 都监听 80 端口Nginx 会按“精确匹配 通配符 正则”的顺序找 server_name而不是你在配置文件里写的先后顺序。一个典型的多站点配置片段server { listen 80; server_name project-a.local; root /data/www/project-a; } server { listen 80; server_name project-b.local; location / { proxy_pass http://127.0.0.1:3000; } }这里project-a.local直接服务静态文件project-b.local走反向代理。两者互不干扰因为 server_name 已经把流量分开了。3.3 hosts与DNS的配合server_name只是 Nginx 侧的匹配规则真正让域名指向哪台机器要么走公网 DNS要么改本机 hosts。开发环境下改 hosts 最直接Windows 在C:\Windows\System32\drivers\etc\hostsLinux/macOS 在/etc/hosts加上两行192.168.1.10 project-a.local 127.0.0.1 project-b.local这样访问project-a.local时会去虚拟机访问project-b.local时走本地回环地址。虚拟机上 Nginx 的listen要注意监听地址如果 Nginx 只想被局域网访问listen 80没问题如果监听的是listen 127.0.0.1:80那局域网机器就进不来。开发环境里我一般直接listen 80 default_server;配合防火墙限制外部访问这样最不容易踩“外部访问不到”的坑。3.4 location匹配规则与alias/rootlocation是 Nginx 路由的核心也是新手最容易绕晕的地方。匹配规则可以归纳为一个优先级从高到低的顺序精确匹配比如location /login^~前缀匹配且不再检查正则比如location ^~ /static/正则匹配按书写顺序比如location ~ \.php$、location ~* \.(jpg|png)$普通前缀匹配比如location /api/理解优先级之后配置里最大的坑就是root和alias的区别。root会把请求 URI 拼在 root 路径后面比如root /var/www;请求/static/a.css时找的是/var/www/static/a.css。alias则是把 location 匹配到的前缀替换掉比如location /static/ { alias /data/files/; }请求/static/a.css会直接对应到/data/files/a.css而不是/data/files/static/a.css。很多人配置图片 404就是因为把该用alias的地方写成了root或者alias末尾少了一个斜杠。3.5 代理服务器文件访问除了当 Web 服务器Nginx 还经常被用来把服务器上的文件目录暴露给同事或外部系统下载。做法很简单location /files/ { alias /data/share/; autoindex on; charset utf-8; }autoindex on会生成目录列表访问/files/就能看到/data/share/下的所有文件。这里要说两个注意点一是目录列表默认不友好可以配合autoindex_format json或设置autoindex_localtime on让时间显示更直观二是如果目录里有敏感文件一定要做访问控制最轻量的是加auth_basic用户名密码认证location /files/ { alias /data/share/; autoindex on; auth_basic Restricted; auth_basic_user_file /etc/nginx/.htpasswd; }auth_basic虽然只走 HTTP Basic 认证但对于内部文件共享已经完全够用配置成本也低。4. 反向代理与负载均衡实战proxy_pass、CORS、超时和TCP最大连接数4.1 反向代理 vs 正向代理以及proxy_pass的隐形规则反向代理是 Nginx 最核心的日常工作。正向代理是替客户端访问外部资源反向代理是替后端服务接收外部请求。客户端只认识 Nginx不关心背后是哪台服务器在真正处理。最典型的就是内网部署了一个 Ollama 服务监听 11434不想直接暴露端口就在 80 端口上做一个反向代理。proxy_pass的写法有一个非常隐蔽但影响巨大的细节路径后面带不带斜杠URI。看两组对比location /api/ { proxy_pass http://127.0.0.1:8080; } location /api/ { proxy_pass http://127.0.0.1:8080/; }第一组不带斜杠Nginx 会把原始 URI 原样转发请求/api/user送到后端还是/api/user。第二组带斜杠Nginx 会用location匹配到的部分替换成/请求/api/user送到后端变成/user。这个差异直接决定后端接口能不能路由对我在排障时第一件事永远是确认proxy_pass末尾有没有/。4.2 upstream负载均衡与健康检查多后端实例时用upstream定义一组服务器然后proxy_pass指向组名upstream backend { server 127.0.0.1:8080 weight2; server 127.0.0.1:8081 max_fails3 fail_timeout30s; keepalive 32; } server { listen 80; location / { proxy_pass http://backend; proxy_set_header Host $host; } }默认的负载均衡策略是轮询round-robin每个请求按顺序分发。需要保持会话时可以用ip_hash让同一个客户端 IP 固定打到同一台后端请求处理时间差异大时用least_conn让 Nginx 把请求分给当前活跃连接数最少的后端。weight控制权重max_fails配合fail_timeout实现被动健康检查——连续失败达到次数后这台后端会在冷却时间内被摘除。开源版 Nginx 没有主动健康检查如果后端进程还在但接口已经变慢max_fails是兜底方案。4.3 CORSinvalid cors request的来龙去脉跨域问题是前端联调时的常客。浏览器里报invalid cors request时多半不是 Nginx 的问题而是请求的Origin头或者Authorization头触发了预检但服务端返回的响应里缺少对应的Access-Control-Allow-*头。后端如果不好改Nginx 层可以直接补location /api/ { add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS always; add_header Access-Control-Allow-Headers Authorization, Content-Type always; add_header Access-Control-Allow-Credentials true always; if ($request_method OPTIONS) { return 204; } proxy_pass http://backend; }这里有两个细节值得注意。第一$http_origin比写死*更安全也支持携带 Cookie 的跨域请求第二add_header不是简单的叠加——一旦某个location块里出现了add_header它就会覆盖从server层继承下来的所有add_header。所以我习惯把跨域头写在最具体的location里避免出现“外层的没生效”这种困惑。4.4 代理超时与mirror的坑反向代理默认连接后端超时是 60 秒但真实场景往往更复杂。proxy_connect_timeout控制建立连接的超时proxy_read_timeout控制读取响应的超时proxy_send_timeout控制发送请求体的超时。如果你的后端是 AI 模型推理接口单次请求可能跑好几分钟必须调大proxy_read_timeout否则 Nginx 会提前断开客户端收到 502。mirror模块用于把请求流量复制一份给另一个后端常用于线上流量回放验证。配置很简单location / { mirror /mirror; proxy_pass http://backend; } location /mirror { internal; proxy_pass http://mirror_backend; proxy_read_timeout 10s; proxy_connect_timeout 5s; }镜像请求的超时主要看proxy_read_timeout和proxy_connect_timeout但即使镜像后端超时主请求一般不受影响只会记录到 error 日志里。实际排查时可以看 error log 里的upstream timed out是否对应/mirror路径如果是说明主链路是健康的问题集中在镜像后端。4.5 TCP最大连接数不只是nginx.conf很多人以为把worker_connections调到 65535 就能支撑几万并发结果压测时连接数还是上不去。原因在于系统层限制。worker_connections只是单 worker 能维护的连接上限最终能打开的 socket 数还受进程文件描述符限制控制也就是ulimit -n。Linux 默认软限制通常是 1024要调大需要改/etc/security/limits.conf同时内核参数net.core.somaxconn监听队列长度和本地端口范围net.ipv4.ip_local_port_range也会成为瓶颈。作为反向代理时Nginx 到后端的连接也要占文件描述符。所以我调优的顺序是先ulimit -n再worker_rlimit_nofile最后才是worker_connections。worker_rlimit_nofile 65535; events { worker_connections 4096; }worker_rlimit_nofile让 worker 进程的 fd 上限脱离 shell 限制这两个配合才有效果。另外开启 HTTP/2 和 keepalive 复用连接能大幅降低 fd 占用因为同一客户端可以复用同一个连接发多个请求Nginx 和后端之间的连接也可以保持不断。5. SSL证书替换不生效与浏览器证书报错的完整排查链路5.1 一次让人着急的证书替换有次线上需要把旧证书换成新证书我当时把两个.pem文件覆盖到原路径执行nginx -s reload然后用 curl 验证却还是旧证书。第一反应是 Nginx 没有加载新文件后来才发现问题远比想象的复杂。证书替换不生效常见的诱因有三个配置文件里写的路径不是你以为的那个路径证书文件确实换了但证书链不完整浏览器或长连接缓存了旧证书状态。这类问题必须按链路逐级排查我整理了一个亲测有效的顺序。5.2 逐级排查从配置到实际握手第一步用nginx -T输出当前加载的全部配置grep 一下ssl_certificate相关配置确认当前生效的证书文件路径到底是什么。这一步能立刻排除“改错了文件”的问题。第二步确认磁盘上的证书文件真的被替换了用openssl x509 -in 证书路径 -noout -subject -dates查看证书主体和有效期。第三步执行nginx -t确认语法没问题再 reload。第四步用 OpenSSL 直接对线上端口做一次握手openssl s_client -connect example.com:443 -servername example.com \ 2/dev/null | openssl x509 -noout -subject -dates这一步看到的是浏览器真实会收到的证书信息。如果这里显示的证书是新证书但浏览器还是报错那问题就不在 Nginx而在证书链、域名匹配、或者浏览器缓存。5.3 证书链不完整Godaddy证书的典型坑很多云厂商给的是 nginx 格式的证书下载包里面通常包含一个主证书.crt和一个或多个中间证书bundle。Nginx 的ssl_certificate需要的是“主证书 中间证书”拼在一起的内容而不是只填主证书。我从 Godaddy 下载 Nginx 证书时踩过一次只把主证书填进去部分桌面浏览器正常但在手机上就报NET::ERR_CERT_AUTHORITY_INVALID。解决方法是把两个文件合并成一份cat example_com.crt gd_bundle-g2-g1.crt combined.crt然后在配置里引用combined.crt。合并的时候顺序一定不能反主证书在前中间证书在后。这样客户端才能通过中间证书逐级回溯到根证书完成信任链校验。5.4 NET::ERR_CERT_COMMON_NAME_INVALID 到底在说什么这个报错翻译成人话就是证书上的域名和你在浏览器地址栏里输入的域名对不上。Nginx 配置的server_name是example.com但证书只签发了www.example.com或者证书的 SANSubject Alternative Name列表里没有当前访问的这个域名浏览器就会拒绝建立信任。排查时用上面的openssl s_client命令看证书的 subject 和 extensions 里的 SAN 列表再把它们和访问域名逐一对比。很多情况下不是你配置错了而是证书申请时域名就填漏了。现代证书普遍用 SAN 支持多个域名所以申请时一定要把example.com和www.example.com都列进去。另外注意用 IP 直接访问和用域名访问是两个完全不同的概念IP 证书和域名证书不能互相替代。5.5 强制跳转与HSTS的后续影响证书没问题之后最常见的下一步是把 HTTP 流量都跳到 HTTPSserver { listen 80; server_name example.com; return 301 https://$host$request_uri; }$host变量会自动带上访问时使用的域名避免把www和根域名跳串。这里要提醒一点如果之前配过 HSTS 头Strict-Transport-Security浏览器会在一定时间内强制走 HTTPS此时你想临时关闭 HTTPS 排查问题会发现怎么都回不到 HTTP。那不是配置没生效而是 HSTS 策略还在生效期。需要回退时要么等过期要么让用户清浏览器站点数据。6. 进阶玩法AI服务代理、容器部署、监控与安全加固6.1 用Nginx代理Ollama并设置API Key本地装了 Ollama 之后我经常需要通过 CherryStudio 这类 AI 客户端去调用但直接暴露 11434 端口既不方便也不安全。用 Nginx 反代一层既能隐藏端口又能在入口处加一层 API Key 鉴权。server { listen 80; server_name ollama.example.com; location / { if ($http_authorization ! Bearer your-secret-key) { return 401; } proxy_pass http://127.0.0.1:11434; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这样客户端在请求头里带上Authorization: Bearer your-secret-key就能访问不带直接 401。注意if指令在 Nginx 里有很多限制像这种简单的鉴权场景用法没问题但不要在里面写复杂的业务逻辑。更稳妥的做法是用map指令预先比较但这套简单场景已经够用。如果 Ollama 只是本机访问我还会在listen上限制绑定 127.0.0.1彻底不对公网开放。6.2 容器与K8s里的NginxKubernetes 里用 Nginx 主要有两种姿势一是借ingress-nginx作为集群入口流量网关二是把 Nginx 作为业务 Pod 自己跑。前者本质上是给你部署好的ingress-nginx-controller通过 Ingress 资源配置路由后者往往是把站点镜像打进nginx:alpine里再挂载自定义的default.conf。容器里最容易踩的配置坑和 2.3 节讲的一致挂载文件权限不对、路径不对、include缺失。在 K8s 里一般会把这些配置放到 ConfigMap 里挂载修改 ConfigMap 之后 Nginx 进程不会自动重载要么原地nginx -s reload要么滚动重启 Pod。排查时最方便的就是进 Podkubectl exec -it pod -- nginx -t先把语法和解析结果确认了再谈别的。6.3 用Zabbix 7监控NginxNginx 自身有一个stub_status模块开启后能暴露连接数、请求数等核心指标。在 server 块里加一个内部 locationlocation /basic_status { stub_status on; access_log off; allow 127.0.0.1; deny all; }访问/basic_status会输出类似下面的内容Active connections: 291 server accepts handled requests 16630948 16630948 31079316 Reading: 6 Writing: 179 Waiting: 106Zabbix 7 里可以直接用 agent 抓取这个文本并解析出指标。其中Active connections是当前活跃连接数accepts是接收的连接总数handled是成功处理的连接数Reading是正在读请求头的连接数Writing是正在写响应的连接数Waiting是空闲 keepalive 连接数。Reading持续偏高说明有请求处理不过来Waiting高一般说明长连接复用得很健康。配置 Zabbix item 时用web.page或者system.run配合curl都可以但我会优先用web.page避免在 agent 上执行额外命令。6.4 从CTF安全加固题里学到的防御姿势看过一些 CTF 里的 Nginx 安全加固题目之后我最大的感受是很多“漏洞”并不是 Nginx 本身的 bug而是配置不当。防御侧的常规动作其实很朴素。第一隐藏版本号server_tokens off;防止扫描器通过Server响应头锁定具体版本。第二关闭目录列表确认没有autoindex on被误开。第三限制请求体大小client_max_body_size 10m;防止恶意大包把后端打挂。第四给管理接口加访问控制比如只允许内网网段访问/admin。第五配置默认 server 并拒绝未知域名访问防止别人直接用你的 IP 发起请求server { listen 80 default_server; server_name _; return 444; }return 444是 Nginx 特有的“直接断开连接”响应码扫描器碰到这种配置通常会被拖慢不少。再配合limit_req_zone做接口限流基本能挡住大多数低成本的滥用请求。这些操作每一项都很简单但组合在一起能明显降低被攻击面。6.5 我的维护习惯如果让我给现在的自己提一条建议那就是任何 Nginx 变更必须走“备份配置、nginx -t、reload 后观察 error 日志”这三步。尤其是 error 日志很多问题的真相都藏在里面。比如证书不生效error 日志里可能写着upstream prematurely closed connectionCORS 报错日志里会记录实际接收到的 Origin 头。Nginx 的本质是“路径 匹配 转发”绝大多数线上事故最终都能归因到这三者的组合出了问题。把每一层拆开验证问题就会无处遁形。