第二章【开源功能】—— HTTP 服务器（上）

irisart2025-12-18 8:22

本节目录

    • [一、HTTP 模块](#一、HTTP 模块)
    • [二、各 HTTP 处理阶段](#二、各 HTTP 处理阶段)
      • [（1）Post-Read 阶段](#（1）Post-Read 阶段)
      • [（2）Server-Rewrite 阶段](#（2）Server-Rewrite 阶段)
      • [（3）Find-Config 阶段](#（3）Find-Config 阶段)
      • [（4）Rewrite 阶段](#（4）Rewrite 阶段)
      • [（5）Post-Rewrite 阶段](#（5）Post-Rewrite 阶段)
      • [（6）Pre-Access 阶段](#（6）Pre-Access 阶段)
      • [（7）Access 阶段](#（7）Access 阶段)
      • [（8）Post Access 阶段](#（8）Post Access 阶段)
      • [（9）Try-Files 阶段](#（9）Try-Files 阶段)
      • [（10）Content 阶段](#（10）Content 阶段)
      • [（11）Log 阶段](#（11）Log 阶段)

一、HTTP 模块

ngx_http_module 是 nginx 中最核心的模块之一，它定义了 nginx 处理 HTTP 请求的基本框架和主要功能，所有的 HTTP 相关功能，包括请求解析、路由、内容处理、响应生成等，都是围绕这个模块及其众多的子模块展开的。

但 ngx_http_module 不是一个具体的模块，而是 HTTP 处理的上下文，它包含了众多 "子" 模块，而它只负责各个子模块的管理和注册，并驱动 HTTP 处理的各个阶段。

下面是 HTTP 的主要子模块及其用途：

子模块名 用途
ngx_http_core_module 核心，定义了最基本的 HTTP 配置块（http、server、location）和通用指令，如文件路径、连接限制、超时设置等
ngx_http_log_module 访问日志模块，负责记录客户端请求到日志文件
ngx_http_upstream_module 反向代理核心，定义了后端服务器组的配置，用于负载均衡、容错、被动检查和主动检查（商业版）
ngx_http_ssl_module SSL/TLS 模块，提供对 HTTPS 的支持
ngx_http_static_module 静态文件处理，负责从文件系统读取并传输静态文件（最常用的内容处理模块）
ngx_http_proxy_module 反向代理处理，将请求转发给上游的 HTTP 服务器并返回响应
ngx_http_fastcgi_module FastCGI 协议模块，将请求转发给 fastcgi 服务器（如 php-fpm）处理动态内容
ngx_http_limit_req_module 速率限制模块，基于请求的键值（如 ip 地址）限制处理请求的速率
ngx_http_rewrite_module URI 重写模块，基于正则表达式更改请求的 URI 或重定向请求
ngx_http_autoindex_module 目录列表模块，如果请求的是一个目录且没有指定 index 文件，则生成目录内容列表
ngx_http_header_filter_module 响应头过滤核心，负责发送 HTTP 响应头
ngx_http_chunked_filter_module chunked 编码过滤，对响应体进行 HTTP/1.1 chunked 传输编码
ngx_http_gzip_module gzip 压缩，对响应内容进行 gzip 压缩，以减少传输大小
ngx_http_sub_module 字符串替换过滤，在响应体中用一个字符串替换另一个指定的字符串
ngx_http_addition_module 响应体追加，在响应体的开头或结尾添加文本内容
ngx_http_dav_module webdav 模块，允许通过 HTTP 协议进行文件管理操作（PUT、DELETE、MKCOL 等）
ngx_http_auth_basic_module 基本认证模块，提供 HTTP Basic Authentication 方式的用户名/密码访问控制
ngx_http_auth_request_module 外部认证，通过向子请求发送请求来处理身份验证和授权
ngx_http_lua_module Lua 脚本支持模块，允许在请求处理的几乎所有阶段执行高性能的 Lua 代码
... ...

二、各 HTTP 处理阶段

nginx 处理 HTTP 请求的 11 个阶段是其高效率和高灵活性的核心所在，整个处理流程就像一条流水线，每个阶段都有特定的任务，并且允许不同的模块挂载到相应的阶段去执行相应的功能。

（1）Post-Read 阶段

此阶段（NGX_HTTP_POST_READ_PHASE）是 nginx 读取并解析完请求头后立即执行的第一个阶段，在这个阶段 nginx 可以对原始请求信息进行预处理，如 ngx_http_realip_module 获取真实 ip 等。

  • 注意，这是在 nginx 配置层面第一个用户可干预的阶段；
  • 此时 URI 尚未被解析，所以 location 块也未匹配；
  • 只能做预处理或修改请求上下文

任何需要在请求头完全读取后立即执行的模块都挂载在此处。

关于 ngx_http_realip_module 的配置示例如下：

nginx 复制代码 
set_real_ip_from 192.168.1.0/24;			# 声明可信的上游服务器 ip 段，只有这些 ip nginx 才会信任并处理，同时支持 ipv6
set_real_ip_from 192.168.2.3;
set_real_ip_from 192.168.11.1;				# 支持单个 ip 写法，写多行即可
set_real_ip_from unix:;						# 同时支持 socket 写法
 
 
real_ip_header X-Forwarded-For;			# 指定从哪个 HTTP 请求头中获取真实 ip，默认是 X-Real-IP，但更常见的是 X-Forwarded-For
# X-Forwarded-For 可以说是一个 ip 切片，没经过一次代理，此标志就会追加一个 ip，所以第一个 ip 即为客户端真实 ip
# 例如 X-Forwarded-For: 203.0.113.42（真实）, 192.168.1.10（一层代理）, 10.0.0.5（二层代理）


real_ip_recursive off;			# 控制如何从 X-Forwarded-For 列表中选择真实 ip，并更新相应变量值（默认为 off）
# off 选项：从右往左扫描 X-Forwarded-For，nginx 只信任直接连接它的对端 ip（前提是可信），然后继续读取下一个作为真实 ip
# on 选项：从右往左扫描，依次排除所有在 set_real_ip_from 列表中的可信 ip，直到遇到第一个不可信的 ip 作为真实 ip

警告：

  • 不要随意信任公网 ip，如果你把 set_real_ip_from 0.0.0.0/0，那么任何用户都可以伪造 X-Forwarded-For 头部，冒充任意 ip，导致日志、限流、访问控制全部失效。强烈建议只信任你自己的代理层（如负载均衡服务器、CDN 回源 ip、前端 nginx）；
  • 如果你想获取真实 ip，如果链路中只有一层代理，那么 real_ip_recursive off 可用；如果链路中存在多层代理，那么必须采用 on 模式。综合推荐无脑设置为 on 模式，这样更为安全和通用。

（2）Server-Rewrite 阶段

此阶段（NGX_HTTP_SERVER_REWRITE_PHASE）是 HTTP 请求处理中的第二阶段，它是在 server 块上下文中执行 URI 重写和变量操作的关键阶段，主要负责请求路由、协议跳转、域名标准化等场景。此阶段发生在 server 级上下文中，执行的是 server 级 rewrite 规则，执行完毕后将进入下一阶段 Find-Config，根据当前的 URI 匹配最合适的 location。

下面是此阶段的典型应用场景的最佳实践方案：

  1. 全站 HTTP 到 HTTPS 强制跳转：

    nginx 复制代码 
    server {
	listen 80;
	return 301 https://$host$request_uri;	# 用 return，不走正则引擎
}

  2. 统一主域名

    nginx 复制代码 
    server {
    listen 443 ssl http2;
    server_name example.com; 
    return 301 https://www.example.com$request_uri;		    # 用 return 实现永久重定向
}
server {
    listen 443 ssl http2;
    server_name www.example.com;

    # 正常业务...
    location / {
		...
    }
}

  3. 全局 api 版本路由（内部重写）

    nginx 复制代码 
    server {
    listen 443 ssl;
    server_name api.example.com;
    rewrite ^/v1(/.*)$ /api/v1$1 last;			# 全局重写 /v1/xxx → /api/v1/xxx
    rewrite ^/v2(/.*)$ /api/v2$1 last;
    location = / {
        return 200 "API Gateway\n";				# return 允许附加响应体为文本、json，完整 URI
    }
}
location /api/v1/ {								# 独立 location 处理不同版本
    ...
}

location /api/v2/ {
   	...
}

  4. 移动端自动跳转

    nginx 复制代码 
    map $http_user_agent $is_mobile {				# 用 map 预计算，避免 if 嵌套
    default          0;
    "~*Android"      1;
    "~*iPhone"       1;
    ...
}

server {
    listen 80;
    server_name example.com;
    if ($is_mobile = 1) {					 # 仅当是移动设备且未在移动端路径时跳转
        set $need_redirect "yes";
    }
    if ($uri ~ "^/mobile/") {
        set $need_redirect "no";
    }

    if ($need_redirect = "yes") {
        rewrite ^(.*)$ /mobile$1 last;
    }

    location /mobile/ {						# 移动端 location
        root /var/www/mobile;
    }
    location / {						    # PC 端
        root /var/www/pc;
    }
}

  5. 安全控制：

    nginx 复制代码 
    server {
    listen 80;
    server_name _;					  # 匹配任意 Host
    
    if ($request_uri ~ "^.{5000}") {						 # 拦截超长 URI（防 dos 攻击）
        return 414; 
    }
    if ($request_uri ~ "(?i)\.\./") {						# 避免路径遍历攻击
        return 403;
    }
    if ($request_uri ~ "(?i)/(\.git|\.env|config\.php)") {	#  禁止敏感文件访问
        return 403;
    }
    if ($host !~* ^(www\.)?example\.com$) {				# 非法 Host（防 IP 直接访问）
        return 444;  									# nginx 特有状态码，直接关闭连接，不返回任何响应
    }
    
    location / {
        proxy_pass http://backend;
    }
}

注意：

  • 在 server 块中，if 指令虽然可用，但仍需谨慎对待，推荐 map 替代，以避免 if 副作用，提高性能；

  • 优先使用 return 做简单跳转，复杂正则跳转时再使用 rewrite；

  • 避免在 rewrite 中做耗时操作，若使用复杂正则、大量变量拼接就会显著增加 CPU 开销，建议正则应尽量简单，尽量用前缀去匹配，同时避免在 rewrite 中调用外部服务；

  • 重定向时应指定完整 URI，避免某些客户端（curl、旧浏览器）可能无法正确处理相对 location 头；

  • 注意避免 rewrite 死循环（循环超 10 次会报 500 状态码）；

  • 对于复杂的逻辑业务，请不要在此阶段进行处理。

  • 如果你的服务暴露在公网，因避免对任意 host 或路径做 rewrite，应该仅对可信流量做重写。
    rewrite 指令标志位详解：（来自 ngx_http_rewrite_module 模块）

  • last：忽略后续 rewrite 指令，立即返回 Find-Config 阶段重新匹配 location；

  • break：忽略后续 rewrite 指令，并在此处继续处理；

  • redirect：返回 302 状态码，表示临时重定向；

  • permanent：返回 301 状态码，表示永久重定向；

（3）Find-Config 阶段

此阶段（ NGX_HTTP_FIND_CONFIG_PHASE）是 HTTP 请求处理 11 个阶段中的 第 3 个阶段，它是整个 nginx 路由机制的核心。在这个阶段，nginx 根据当前请求的 URI，从配置中查找最匹配的 location 块，从而决定后续如何处理该请求。

此阶段可被多次执行，每当发生内部跳转（如 rewrite ... last 或 error_page 触发重定向），nginx 会回到 Find-Config 阶段，用新的 $uri 重新匹配 location。

此阶段无法被跳过，用户也无法干预（无法在配置文件中通过代码影响它），其核心任务是根据当前 $uri 值，匹配最合适的 location 配置块：

此阶段的核心匹配Location 的算法按照如下逻辑严格执行：

  1. 检查精确匹配（location = /xxx）：如果 URI 完全等于某个 location = ... 的路径，则立即选中该 location，结束匹配；（优先级第一 ）

    • 适用于首页、API 入口等固定路径。

      nginx 复制代码 
      location = / {		# 只匹配通过 http://xxx.xxx.xxx/ 访问的路径，路径如果包含参数也不匹配
...
}

  2. 检测所有前缀匹配（包括 /xxx 和 ^~ /xxx）：找出所有以当前 URI 开头的 location 块，如 /static/a.png，则 /、/static/、/static/a 都是候选，最后在这些候选 URI 中选择字符串最长的一个作为最佳前缀匹配；（优先级第四 ）

    • 11

      nginx 复制代码 
      location / {					# 所有请求都匹配（兜底）
	...
}
location /images/ {				# 匹配 /images/logo.png 等
    ...
}
location /images/ico {			# 比 /images/ 更长，优先级更高
	...		
}

  3. 检查最佳前缀是否有 ^~ 标记：如果最佳前缀匹配使用了 ^~ 修饰符（location ^~ /static/），则直接选中它，并跳过所有正则匹配；（优先级第二 ）

    • 适用于静态资源目录（/static/, /assets/），明确不需要正则处理。

      nginx 复制代码 
      location ^~ /static/ {			# 所有 /static/ 开头的请求，直接处理，不跑正则
    root /var/www;
}
location ~ \.php$ {				# 即使 /static/test.php 符合此正则，也不会执行！
   ...
}

  4. 第三步如果失败，则尝试正则匹配（location ~ 或 ~*）：如果最佳前缀不是 ^~，则按配置文件书写顺序，依次测试所有 location ~ ... 和 location ~* ...，第一个匹配成功的正则 location 被选中，后续正则不再测试；（优先级第三 ）

    • ~*适用于图片、js、css 匹配等场景；

    • ~适用于动态脚本（php）等场景。

      nginx 复制代码 
      location ~ \.php$ {					# 区分大小写匹配
    fastcgi_pass backend;
}
location ~* \.(jpg|jpeg|png)$ {		# 不区分大小写匹配
    expires 30d;
}

6.如果第四步也没有成功，则最后才使用第二步的最长前缀匹配。

注意：

  • 匹配基于的是 $uri（规范化后不含参数的路径），而不是 $request_uri（原始路径）；
  • 内部跳转（如 rewrite ... last）会重新触发规则；
  • 内部跳转会重置部分变量，如 $args 保留，但 $is_args、$request_filename 等可能会更新；
  • 路由不是 "谁先写谁先生效"，而是严格遵循上述的匹配算法；
  • 避免模糊匹配，除非用于兜底。

（4）Rewrite 阶段

此阶段（NGX_HTTP_REWRITE_PHASE）是 HTTP 请求处理 11 个阶段中的 第 4 个阶段，是在已匹配的 location 上下文中执行 URI 重写和变量操作的关键阶段，常用于路径调整、参数处理、条件跳转等场景。与 Server-Rewrite 阶段不同，Rewrite 阶段发生在具体 location 已经确定之后，因此可以结合 location 级配置（如变量、上下文）进行更精细的控制。

下面是此阶段的典型应用场景：

  1. api 路径版本剥离（等于是 location 内部重写）

    nginx 复制代码 
    location /api/ {
    rewrite ^/api/(v[0-9]+)/(.*)$ /$1/$2 break;			# 将 /api/v1/users 重写为 /v1/users
    proxy_pass http://backend;  						# 实际请求 /v1/users
}

  2. 静态资源路径映射（配合 root）

    nginx 复制代码 
    location /assets/ {
    root /var/www;
    rewrite ^/assets/(.*)$ /static/$1 break;		# 将 /assets/logo.png 映射为 /var/www/static/logo.png，使用 break 停止后续检查
}

  3. 基于查询参数的访问控制

    nginx 复制代码 
    location /admin/ {
    if ($arg_token = "") {
        return 401;
    }
    if ($arg_token != "123qwe") {
        return 403;
    }

    proxy_pass http://admin_backend;			# 若上述没有通过验证，则无法执行这一句代理
}

  4. SEO 友好的 URI 重写

    nginx 复制代码 
    location /blog/ {
    rewrite ^/blog/([0-9]+)$ /blog.php?id=$1 last;		# 将 /blog/123 重写为 /blog.php?id=123，然后重写进入 find-config 阶段进行匹配
}

location ~ \.php$ {
    fastcgi_pass php-fpm;
}

注意：

  • if 在 location 中容易产生难以预期的执行路径（实际上是 rewrite 模块的一部分），在 location 中使用会破坏 nginx 的指令继承逻辑，所以非必要不建议使用，推荐用多个 location 替代或者通过 map + error_page 间接实现；
  • last 和 break 的选择至关重要，如果需要跨其他 location 处理则选 last，需要继续留在 location 中就选择 break；
  • URI 修改将直接影响到后续所有阶段，例如 proxy_pass、fastcgi_param 中的 $uri 都是重写后的；
  • 老生常谈，避免在 rewrite 阶段做耗时操作，避免性能损耗过大；
  • 内部跳转存在次数限制（最多 10 次），超过次数会返回 500 错误（为 nginx 内部保护机制，不是 rewrite 模块自身的逻辑）。

（5）Post-Rewrite 阶段

此阶段（NGX_HTTP_POST_REWRITE_PHASE）是 HTTP 请求处理 11 个阶段中的第 5 个阶段，与大多数阶段不同，Post-Rewrite 阶段对用户完全透明，你无法通过配置文件直接写指令影响它，也没有模块允许你注册自定义 handler。它的存在主要是为了内部逻辑协调，特别是处理内部跳转后的 URI 标准化和 location 重新评估前的准备工作。

它是 Rewrite 回到 Find-Config 循环的桥梁，主要任务是检测是否发生了内部跳转（如 rewrite ... last），并准备进入下一轮 Find-Config。

如果发生了内部跳转，则此阶段的工作流程如下：

  1. 检查是否设置了 uri_changed 标志，如果 Rewrite 阶段修改了 $uri 并使用了 last，nginx 会标记 r -> uri_changed = 1；
  2. 重置部分请求状态，清除已匹配的 location 上下文，重置某些变量（如 $document_root 可能更新），准备回到 Find-Config 阶段；
  3. 防止无限循环，内部维护一个 redirect counter（默认最大 10 次，NGX_HTTP_MAX_URI_CHANGES = 10），如果超过限制，在此阶段返回 500 状态码；
  4. 标准化新 URI，确保新 URI 是合法的。

此阶段只在需要时才激活，如果上阶段没有发生内部跳转（如只用了 break 或 return），则此阶段几乎无操作，快速通过。

（6）Pre-Access 阶段

此阶段（NGX_HTTP_PRE_ACCESS_PHASE）是 HTTP 请求处理 11 个阶段中的第 6 个阶段，与上一阶段类似，Pre-Access 阶段对大多数用户也是透明的，你无法直接在配置中写指令触发它，但它为某些关键模块（如限流、连接控制）提供了执行时机。此阶段是 "轻量级准入控制" 的理想位置，能在消耗后端资源前快速拒绝部分非法或过载请求。

简单示例配置如下：

nginx 复制代码 
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;		# 定义限流 zone
    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;		# 允许突发流量上限为 20，并允许突发流量立即被响应（无延迟感知）
            limit_conn addr 5;							# 限制并发连接
            proxy_pass http://backend;
        }
    }
}

Pre-Access 阶段的性能极高，设计它的目的就是为了保护资源，防止部分网络攻击。

注意：

  • 若多个模块都注册在此阶段了，则它们按编译、加载的顺序来执行；
  • 此阶段中一旦有模块失败，就会立即终止连接（默认返回 503 状态码）；
  • 此阶段不能使用由 rewrite 阶段之后才生成的复杂变量（除非已定义），只能使用一些基础变量；
  • 如果发生内部跳转了，此阶段会重新执行，限流规则会被多次触发。

（7）Access 阶段

此阶段（NGX_HTTP_ACCESS_PHASE）是 HTTP 请求处理 11 个阶段中的第 7 个阶段，这是 nginx 实现访问控制的核心阶段，主要用于判断当前客户端是否有权限访问该资源。它支持 ip 黑白名单、HTTP 基础认证、子请求认证等多种授权机制。核心作用是在消耗后端资源（如 proxy_pass、fastcgi）之前，先确认客户端身份和权限。

以下是此阶段的典型用例：

  1. 基于 ip 地址的访问控制：（由 ngx_http_access_module 模块提供）

    nginx 复制代码 
    location /admin/ {
    allow 192.168.1.0/24;			# 支持 ipv4、ipv6、cird 网段
    allow 10.0.0.5;
    deny all;  					# 拒绝其他所有 ip，如果前面允许，最后一定要拒绝其他所有!!!
}
# 如果当前 nginx 前面还有反向代理，则需要配合阶段一来获取真实 ip

  2. HTTP Basic 认证：（由 ngx_http_auth_basic_module 模块提供）

    nginx 复制代码 
    location /private/ {
    auth_basic "Restricted Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}
# 认证成功后，变量 $remote_user 可用
# 适合内部工具、临时保护，不适用于生产环境（除非是 HTTPS）

  3. 子请求认证：（由 ngx_http_auth_request_module 提供，需要后端提供认证服务）

    nginx 复制代码 
    location /api/ {
    auth_request /auth;
    proxy_pass http://backend;
}

location = /auth {						# nginx 向 /auth 发起子请求以获取认证
    internal;  							# 此 location 仅允许 nginx 内部调用
    proxy_pass http://auth-service/validate;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}
# 可传递 header、cookie，支持 OAuth、jwt、session 等复杂认证逻辑，是一种企业级的推荐方案

注意：

  • 如果任一 handler 拒绝请求了，nginx 将立即终止当前连接并返回对应模块定义的状态码（401、403等）；
  • 如果存在 ip 地址访问控制，最后必须写 deny all，否则前面的 allow 将形同虚设；
  • location 下所有认证条件都必须满足才能继续下一步，但 satisfy 指令可以改变这种逻辑关系（默认是 AND，使用此指令和改为 OR）；

（8）Post Access 阶段

此阶段（NGX_HTTP_POST_ACCESS_PHASE）是 HTTP 请求处理 11 个阶段中的第 8 个阶段，与前面几个阶段相比，Post-Access 是一个非常安静且极少被使用的阶段，在官方 nginx 核心模块中，没有任何内置指令或 handler 注册到此阶段，它的存在主要是为第三方模块（尤其是 OpenResty 中的 ngx_lua）提供一个在权限检查完成之后、内容生成之前的执行钩子。

本质：既然用户已通过所有安全检查，那么在真正处理请求前，还能做些什么？？？

注意：

  • 不能用于权限控制，权限检查应在前一阶段完成，此阶段假设用户都已合法，不应再做拒绝操作；
  • 此阶段性能敏感，如果注册了 handler 模块，应避免 I/O 操作，否则会拖慢所有的合法请求；
  • 前面几个阶段设置和修改的变量这里都可用，要注意对后续阶段的影响。

（9）Try-Files 阶段

此阶段（NGX_HTTP_TRY_FILES_PHASE）是内容生成前的最后一道关卡。其核心任务是按顺序检查文件、uri 是否存在，并决定最终如何响应请求。

try_files 指令：try_files file1 file2 ... final_uri;

  • nginx 将从左到右一次检查每一个参数，对于文件路径 $uri 则检查是否存在，对于文件目录 $uri/ 则检查目录是否存在且有索引页，对于 /abc.html （URI 路径）不做检查，直接回到 Find-Config 阶段匹配对应 location。
  • 如果前面的参数有存在的，则直接进入下一阶段即可，否则执行最后一个参数（必须是一个 URI 或者返回状态码）

下面是示例配置：

nginx 复制代码 
# 如果访问的是 http://xxx.xxx.xxx/aaa
# 先检查 /var/www/html/aaa 是否存在
# 再检查 /var/www/html/aaa/ 是否存在且有索引
# 如果上面都失败了，最后跳转到 /index.php 的兜底页面（会触发内部重定向，回到 find-config 继续匹配）
location / {
    root /var/www/html;
    try_files $uri $uri/ /index.php?$query_string;				# 若前面的 $uri 或 $uri/ 都不存在，则返回指定 uri 处
}
nginx 复制代码 
location /static/ {
    root /data;
    try_files $uri =404;				# 若 $uri 文件不存在，则直接返回 404 状态码，没有兜底选项
}
nginx 复制代码 
location / {
    root /var/www/html;
    try_files $uri $uri/ @fallback;			# 若 $uri 和 $uri/ 不存在，则返回指定 location
}
location @fallback {					# 以 @ 开头的 location，不支持 try_files，它本身已是 fallback了因为
	...
}

注意：

  • 最后一个参数不能是文件路径；

  • @ 开头的 location（命名 location）不支持 try_files；

  • 每个 file 参数都会触发一次磁盘调用，对于高频接口建议减少尝试项或者启用 open_file_cache 缓存文件元数据。
    严重警告：

  • 尽最大可能在 try_files 场景下配合 root 使用！！！如果必须用 alias，确保 try_files 的最后一个参数是内部重定向（如 /index.php）而不是直接的文件路径！！！

请注意 try_files 最后一个参数也可能存在坑：

  • 即使最后一个参数是 URI，可以引发内部重定向，但如果这个重定向的目标 location 依然使用了 alias，那这个路径计算的噩梦可能会继续传递下去，非常恐怖。
  • 还有一个巨离谱的 bug（主要存在于旧版本），如果你在 alias 下使用 try_files，且最后一个参数是命名 location（如 @fallback），在某些版本中会丢失 script_name 或导致 FastCGI 参数传递错误

为什么会出行这种问题？？？

  • 这是 nginx 核心代码中存在的一个陈年老 bug，在 alias 块中，try_files 曾长期存在一个逻辑缺陷，既当 try_files 去检查 $uri 时，它应该使用 alias 处理后的路径（alias 是替换路径，root 是拼接路径）。但在很多历史版本（甚至某些特定配置下的新版本）中，try_files 会错误地重置 $uri 值，或者没有正确剥离 location 前缀，导致它去查找错误的路径。

现在的情况：

  • 虽然 nginx 官方在近几年的版本中修复了大部分 alias + try_files 的 bug，但由于其内部处理逻辑极其复杂（涉及 URI 字符串的截取、替换、重组），社区的一致共识依旧是：能用 root 就绝不用 alias 去配合 try_files！！！
  • 如果非要用 alias，现在的安全写法通常是不带 $uri 变量，直接依赖 alias 的映射（但这又失去了 try_files 检查文件存在的意义），或者确保 alias 结尾和 location 结尾的 / 严格一致。

（10）Content 阶段

此阶段（NGX_HTTP_CONTENT_PHASE）是整个 HTTP 请求处理流程中最核心、最关键的阶段，它是唯一负责生成最终响应内容的阶段。 简单说，前面所有阶段都在为此阶段做准备，只有此阶段才是真正的牛马。

nginx 本身并不生产内容，而是由各种模块注册成 content handler 来生产内容：

模块 指令 作用
ngx_http_static_module root、alias 返回静态文件
ngx_http_index_module index 返回目录下的索引页
ngx_http_proxy_module proxy_pass 反向代理到后端服务
ngx_http_fastcgi_module fastcgi_pass 与 PHP-FPM 等 FastCGI 服务通信
ngx_http_uwsgi_module uwsgi_pass 与 uWSGI 应用通信
ngx_http_scgi_module scgi_pass SCGI 协议支持
ngx_http_autoindex_module autoindex on 自动生成目录列表
ngx_http_memcached_module memcached_pass 从 Memcached 获取内容
ngx_http_addition_module add_before_body / add_after_body 在响应前后插入内容
... ... ...

注意：

  • 此阶段是终点站，一旦进入，不可返回到前面的阶段（除非使用 error_page 触发内部跳转）；
  • 性能优化的关键，所有高并发、低延时的优化几乎都集中在此阶段；

（11）Log 阶段

此阶段（NGX_HTTP_LOG_PHASE）是 HTTP 请求处理 11 个标准阶段中的最后一个阶段，它的核心职责就是记录访问日志和执行自定义日志逻辑。

注意：

  • 日志记录的是最终状态，如果你把 error_page 重写为 200，最后记录的也是 $status = 200；
  • 日志记录默认每次请求都写磁盘，建议配置缓冲以提高性能（access_log /var/log/nginx/access.log main buffer=64k flush=5s）
  • 此阶段无法改变响应，也不能阻止请求完成，如果你想根据日志记录再做出决策，应在 Access 或 Content 阶段处理；
  • 此阶段所有的变量均可使用。

下面是一个推荐日志配置：

nginx 复制代码 
http {
    map $http_x_request_id $trace_id {				# 唯一请求 id，用于链路追踪
        default $http_x_request_id;
        ""      $request_id;
    }

    log_format jsonLog escape=json '{'					# 配置为 json 格式，方便后期管理和分析
        '"timestamp":"$time_iso8601",'
        '"client_ip":"$remote_addr",'
        '"xff":"$http_x_forwarded_for",'
        '"host":"$host",'
        '"scheme":"$scheme",'
        '"method":"$request_method",'
        '"uri":"$uri",'
        '"status":$status,'
        '"bytes":$body_bytes_sent,'
        '"duration_sec":$request_time,'
        '"upstream_time":"$upstream_response_time",'	
        '"request_id":"$trace_id"'
    '}';
    access_log /dev/stdout jsonLog;				 							# 容器环境日志输出到 stdout，由容器收集
    # access_log /var/log/nginx/access.log jsonLog buffer=64k flush=5s;		# 非容器环境，启用缓冲和缓存
    # open_log_file_cache max=1000 inactive=1m valid=10m min_uses=1;
    log_not_found off;														# 关闭 404 错误记录
}
相关推荐
qq_455760858 小时前
docker - 虚拟化和容器化
linux·运维·服务器
fendouweiqian8 小时前
warm-flow 生产环境静态资源 404，本地正常的原因与 Nginx 配置解决方案
运维·nginx
lee5768 小时前
鄙人的 Vue 3.0 商业级开源甘特图已经发布到 npm
前端·vue.js·npm·开源·甘特图
阿里云云原生8 小时前
AgentRun Sandbox SDK 正式开源！集成 LangChain 等主流框架，一键开启智能体沙箱新体验
阿里云·langchain·开源·serverless·agentarun
源码师傅8 小时前
2025最新开源客户crm管理系统源码含搭建：无限多开独立账户、坐席 让生意更好做
开源·开源 crm 搭建·crm管理系统源码·crm系统源码·crm管理平台
洛阳泰山8 小时前
快速上手 MaxKB4J：开源企业级智能知识库系统在 Sealos 上的完整部署指南
java·开源·llm·agent·rag
云和数据.ChenGuang8 小时前
ELK 是一套**开源的日志收集、存储、分析与可视化的技术栈
服务器·数据库·elk·开源·运维技术·数据库运维工程师
艾莉丝努力练剑8 小时前
【Linux进程（二）】Linux进程的诞生、管理与消亡：一份基于内核视角的完整分析
大数据·linux·运维·服务器·c++·安全·centos
拾光Ծ8 小时前
【linux】环境变量（详解）
linux·运维·服务器
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03Linux下V2Ray安装配置指南04在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）05Neo4j（一） - Neo4j安装教程（Windows）06【AutoGLM部署】本地私有化部署AI手机Agent07Cursor 又偷偷更新，这个功能太实用：Visual Editor for Cursor Browser08Open-AutoGLM Windows 安装部署教程09安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）10BongoCat - 跨平台键盘猫动画工具