NGINX 指令

说明

'master_process' 指令是一个标志，用于确定 NGINX 是否以主模式运行或以单进程模式运行。当设置为 'on' 时，启用主进程，允许 NGINX 管理 worker 进程。 这是 NGINX 的标准运行模式，在该模式下主进程负责管理 worker 进程，包括根据流量需求创建和终止它们。 如果 'master_process' 被设置为 'off'，NGINX 将在没有主进程的情况下以单进程模式运行。在这种模式下没有 worker 进程；NGINX 会在单个进程中处理所有请求。这在调试或不需要多进程的轻量级环境中可能有用，但效率低于典型的主-worker 模型。配置此指令对于确保 NGINX 在预期的多线程环境中正常工作至关重要，在该环境中多个 worker 进程可以提高性能和资源利用率。 此指令的参数是一个简单标志——"on" 或 "off"——用于指示是否应启用或禁用主进程。它通常出现在 nginx 配置文件的 main 上下文中，其用法可能根据具体部署要求（例如资源限制或运行目标）而有所不同。

配置示例

master_process on;

说明

NGINX 中的 `timer_resolution` 指令允许你指定事件计时器的分辨率（以毫秒为单位）。该指令在核心模块中定义，对于优化 NGINX 的事件处理系统中的计时操作至关重要。通过调整 `timer_resolution`，用户可以影响事件的处理方式，从而可能提高对时序要求较高的应用的性能。 `timer_resolution` 指令的参数是一个表示以毫秒为单位计时器分辨率的单一数值。对于具有高频事件的应用来说，这一点尤其重要，因为更精细的计时器分辨率可能改善这些事件的执行时机。然而，将其设置得过低可能由于更频繁的计时器检查而增加 CPU 开销。因此，找到适合服务器工作负载的平衡至关重要。 请注意，该指令必须在 main context 中设置，也就是说它应该只出现在 NGINX 配置的顶层（例如，在 main configuration block 内，而不是出现在 events 或 http blocks 内）。了解应用对时序精度的需求将帮助你有效地利用该指令来提升整体性能。

配置示例

timer_resolution 100;

说明

`pid` 指令在 NGINX 核心中用于定义一个文件的位置，该文件在 NGINX 启动时将包含主进程的进程 ID (PID)。这个 PID 文件对于管理 NGINX 进程至关重要，允许管理员轻松跟踪和控制进程，尤其是在执行诸如平滑关闭或重新加载等操作时。通过为该指令提供一个文件路径，NGINX 会在启动时创建该文件并将其 PID 写入其中。这有助于进程管理，确保系统管理员无需猜测进程 ID 就能有效管理服务。 `pid` 指令的参数是一个单一的参数，用于指定存储 PID 的文件路径。通常，该路径应设置为由运行 NGINX 进程的用户可写的位置，因此确保正确的权限很重要。如果由于权限问题或路径错误导致无法创建或写入指定的 PID 文件，NGINX 将报告错误并退出而不启动。因此，务必确保所提供的路径有效且可访问。`pid` 指令必须出现在主配置上下文，通常位于配置文件的顶层，在任何 server 或 location 块之前，因为它涉及整个 NGINX 进程而不是单个服务器进程。

配置示例

pid /var/run/nginx.pid;

说明

`lock_file` 指令在 NGINX 中用于定义一个特定文件，作为锁以防止多个 NGINX 实例同时启动。当 NGINX 启动时，它会尝试使用指定的文件创建锁。如果该文件已存在，表明另一个 NGINX 实例正在运行，则新的实例不会启动，并会记录相应的错误消息。该机制对于维护配置完整性并确保同一时间只有一个主 NGINX 进程在运行至关重要。 传递给 `lock_file` 的参数是一个文件路径，可以设置为任何可写位置。通常，这会是一个临时目录或指定的配置目录。通过仔细选择锁文件的位置，系统管理员可以更有效地管理多实例环境。在自动化脚本或服务管理器可能无意中尝试启动多个 NGINX 实例、从而导致冲突及其他不良状态的场景中，使用锁文件尤其有用。 需要注意的是，如果由于权限问题或文件系统错误无法创建指定的锁文件，NGINX 将无法启动并会显示与无法创建锁文件相关的错误消息。因此，管理员应确保 NGINX 进程具有创建并写入该锁文件的适当权限。

配置示例

lock_file /var/run/nginx.lock;

说明

`worker_processes` 指令决定 NGINX 将创建多少个 worker 进程来处理请求。每个 worker 进程可以同时处理多个连接，使 NGINX 能够根据可用的 CPU 核心数量和传入请求的数量高效扩展。指定的 worker 进程数量会显著影响服务器的整体性能，尤其在高流量情况下。 该指令可以接受表示固定 worker 进程数量的整数值，或关键字 `auto`，指示 NGINX 根据可用的 CPU 核心自动设置数量。当设置为 `auto` 时，NGINX 会根据服务器上检测到的 CPU 核心数量计算 worker 进程数。建议根据硬件和具体应用需求设置此值以获得最佳性能。 在实际配置 `worker_processes` 指令时，系统管理员应监控其应用的负载和性能指标以确定合适的值。将 worker 进程数设置得过低或过高都可能导致性能下降。在某些环境中，可能需要仔细调优以匹配预期负载的特性。

配置示例

worker_processes auto;

说明

`debug_points` 指令面向希望为调试目的操纵 NGINX 服务器执行流程的开发者和高级用户。该指令可以在主上下文中配置，并接受一个指定应触发哪个调试点的单个参数。该指令可用的操作数是 `stop` 和 `abort`，在执行过程中达到时它们会以不同方式影响 NGINX 进程。 当设置为 `stop` 时，NGINX 会在定义的调试点暂停执行，允许用户在需要时附加调试器。这对于对应用在响应特定请求或系统事件时的行为进行逐步分析尤为有用。另一方面，选择 `abort` 会导致进程立即终止，这对于调试致命错误或在特定不良状态下确保系统完整性很有帮助。 `debug_points` 指令的行为可以大大增强在开发或排查 NGINX 模块和配置时的调试体验。它作为一种在不修改实际源代码的情况下在代码中引入有意断点的机制，从而促进更有效的调试工作流。

配置示例

debug_points stop;

说明

`user` 指令在 NGINX 中指定工作进程的用户和组权限。 这对安全非常重要，因为 NGINX 会以非特权用户而不是 root 身份运行，从而降低漏洞可能造成的影响。 该指令接受一个或两个参数：第一个参数是用户名，第二个（可选）是组名。 如果只提供一个参数，NGINX 将使用该用户关联的默认组。 例如，`user nginx;` 将用户设置为 'nginx'，并使用该 'nginx' 的默认组。 当同时指定两个参数时，格式为 `user username groupname;`。 该指令必须在 NGINX 配置文件的主上下文中声明，通常在 `nginx.conf` 文件中，在定义 `events` 或 `http` 上下文之前。 该指令的更改仅在 NGINX 启动或重启时生效。如果进程已启动，更改此指令需要完全停止并重新启动 NGINX 才会生效。 应注意确保所指定的用户具有访问必要文件、目录和资源（例如日志或文档根目录）的足够权限，但不要拥有过于宽泛的访问权限，以保持最小权限原则。

配置示例

user www-data;
user nginx nginx;

说明

`worker_priority` 指令允许你为 NGINX 的工作进程指定 nice 值，这可以影响操作系统在多核环境中如何调度这些进程。nice 值是一个整数，范围从 -20（最高优先级）到 19（最低优先级），可以细致地控制 CPU 资源如何分配给你的 NGINX 工作进程。该指令在需要相对于其他系统进程优先处理 web 流量的环境中特别有用，能确保 web 服务器在负载下快速且高效地响应。 默认情况下，NGINX 的工作进程继承系统的默认优先级设置。当你使用 `worker_priority` 指令设置特定优先级时，目的是通过减少与可能占用 CPU 资源的其他进程发生争用的可能性，使服务器的响应时间更可预测、更高效。需要注意的是，为 NGINX 工作进程设置较高优先级可能会导致其他系统进程的资源争用，因此需要谨慎考虑整体系统负载和需求。 在配置 NGINX 时，更改 `worker_priority` 设置后务必进行充分测试，因为其效果会根据工作负载和服务器架构有很大差异。此外，并非所有操作系统都支持 nice 的所有取值，因此建议参阅你所使用操作系统的文档以确保兼容性。

配置示例

worker_priority 10;

说明

`worker_cpu_affinity` 指令在 main 上下文中使用，用于指定哪些 CPU 核心可以执行 worker 进程。这样可以通过确保 worker 进程在特定核心上运行来优化性能，从而避免进程在核心之间迁移时可能发生的上下文切换和缓存未命中。该指令接受一个或多个参数来定义 CPU 核心的亲和性。它在多核系统中尤其有用，能够最大化资源利用并最小化延迟。 该指令的参数以 CPU 列表的形式提供，可以用多种形式指定，包括单核指定（例如 '0'）、范围指定（例如 '0-3'）或两者的组合。每个附加的值表示对应 worker 可使用的允许 CPU 核心。当定义多个 worker 时，CPU 核心可以在这些 worker 之间分配，从而进一步增强并行处理。该配置有助于在高负载场景下保持性能，并能带来更可预测的响应时间。 实现 `worker_cpu_affinity` 可能需要一些试验以根据具体的工作负载和硬件架构确定最优配置。应通过仔细观察系统性能来指导这些决策，因为核心亲和性的有效性会根据工作负载模式和可用 CPU 核心数量等因素而变化。

配置示例

worker_cpu_affinity auto;  
# Example with specific core assignment for 4 workers:  
worker_cpu_affinity  0001 0010 0100 1000;

说明

'worker_rlimit_nofile' 指令指定工作进程可以打开的文件描述符数量限制。这对于最大化 NGINX 能处理的并发连接或文件访问数量至关重要。当达到此限制时，工作进程将无法打开更多文件或连接，可能导致请求失败或连接被中断。对于高流量的网站和应用程序，该指令非常重要，因为默认限制可能不足。通过设置更高的值，管理员可以优化 NGINX 服务器的性能和响应性。该值在主上下文中设置，应根据预期流量和服务器的资源可用情况进行配置。

配置示例

worker_rlimit_nofile 65536;

说明

`worker_rlimit_core` 指令用于设置 NGINX 中工作进程生成的 core 文件的最大大小。core 文件是在进程崩溃时捕获其内存镜像的文件。该指令允许 NGINX 管理员指定用于调试和分析的 core 转储文件的最大大小。该指令中指定的值直接对应于 `ulimit` 对 core 转储的设置，从而实现有效的资源管理，并在开发或生产故障场景中便于排查问题。 通过指定非零数值，管理员可以根据需求配置 core 大小限制。但请注意，设置过大的 core 文件大小可能会占用大量磁盘空间，尤其是在进程崩溃频繁的环境中。另一方面，将其设置为 0 则完全禁用 core 转储，这可能在出现问题时妨碍调试工作。通常建议设置一个在捕获有价值调试信息与高效管理磁盘资源之间取得平衡的限制。 该指令必须在 NGINX 配置文件的主上下文中定义，通常在全局配置文件（例如 `nginx.conf`）中设置。管理员应确保拥有修改 core 文件生成设置的相应权限，并在使用此指令时考虑操作系统对 core 转储文件的限制与配置。

配置示例

worker_rlimit_core 512M;

说明

`worker_shutdown_timeout` 指令在 NGINX 中指定在接收到终止信号后，NGINX 将等待工作进程优雅关闭的时长（以毫秒为单位）。这允许工作进程在被强制终止之前完成正在进行的请求并清理资源。在存在长连接或大型请求等可能需要额外时间完成处理的场景中，这一点尤其有用。 如果工作进程未能在指定的超时时间内完成其操作，NGINX 将强制终止这些进程。将此值设置得过低可能导致活动请求被中断，从而造成潜在的数据丢失或事务不完整；反之，设置得过高可能会延迟应用重启或关闭，影响维护或更新期间的可用性。实际上，在此处设置一个合理的值可以在服务连续性与在升级或优雅重启期间的高效资源管理之间取得平衡。

配置示例

worker_shutdown_timeout 30000;  # Set a 30 seconds timeout for worker shutdown

说明

NGINX 中的 `working_directory` 指令用于指定工作进程运行的目录。该设置很重要，因为它决定了在执行时没有指定特定目录的进程的默认工作目录。通过指定工作目录，可以确保配置或其他指令中使用的相对路径相对于该目录正确解析。 该指令接受单个参数，参数应为要设置为 NGINX 工作进程工作环境的目录路径。它必须在 NGINX 配置文件的主上下文中使用。当 NGINX 工作进程启动时，它们会继承此设置，并用于解析相对路径、处理文件操作和管理日志等任务，这有助于有效管理权限和组织文件存储。 重要的是要确保指定的目录对 NGINX 进程可访问，并且已设置适当的权限。如果未提供可访问的目录，可能会在 NGINX 运行期间导致错误，尤其是在处理依赖于工作目录路径的日志或配置文件等文件时。

配置示例

working_directory /var/www/html;

说明

'env' 指令在 NGINX 配置文件的主上下文中使用，用于指定应传递给工作进程的环境变量。这对于设置工作进程在运行时可能需要访问的配置值尤其有用，例如 API 密钥、数据库连接字符串或其他可随部署环境变化的设置。'env' 指令的语法很简单；它接受一个参数，用于指定要设置的环境变量名称。您可以使用多个 'env' 指令来设置多个变量，因为每个指令都是独立生效的。 在底层的 C 代码中，'env' 指令在 NGINX 启动阶段被处理。指定的变量会被添加到 NGINX 工作进程的环境变量中，允许像访问任何标准环境变量一样访问它们。'env' 指令在将应用部署到容器化环境（如 Docker）或编排系统（如 Kubernetes）时尤其有用，因为它补充了部署的配置管理实践，使得无需修改应用代码即可轻松修改设置。 需要注意的是，通过 'env' 指令设置的值在 NGINX 进程重新加载时不会持续生效，除非它们在配置文件中被再次显式包含。此外，在启动 NGINX 之后通过系统对环境变量所做的任何更改都不会生效，除非重新启动 NGINX 进程。因此，理解如何有效使用此指令对于在各类部署中维护配置至关重要。

配置示例

env MY_DATABASE_USER;
env MY_API_KEY;

说明

`load_module` 指令允许用户在不重新编译整个 NGINX 二进制文件的情况下动态加载指定的 NGINX 模块。该指令必须放在主配置上下文中，并接受一个参数：要加载模块的共享对象文件的路径（通常以 .so 后缀结尾）。当 NGINX 工作进程启动时，该指令会指示 NGINX 尝试加载其参数中指定的模块，从而在不需重启或重新编译的情况下向服务器加入额外功能。 该指令对于启用可选功能或扩展核心 NGINX 能力的第三方模块（例如额外的认证机制或性能改进）可能至关重要。如果该模块依赖于其他模块或共享库，则这些依赖也必须在运行时满足，加载才能成功。用户应确保指定的模块文件可被访问，并且 NGINX 进程具有加载它所需的权限。如果模块加载失败，NGINX 会报告错误，并可能拒绝启动，具体取决于所遇错误的严重性。 为了有效使用该指令，用户通常在 NGINX 主配置块中定义它，该块会在任何其他配置设置之前被处理。重要的是要注意，应事先解决模块的任何依赖关系以避免运行时错误。

配置示例

load_module modules/ngx_http_custom_module.so;

说明

error_log 指令在配置 NGINX 的日志行为方面非常重要。它允许管理员定义一个或多个日志文件来记录错误消息，包括关键错误、警告以及有关服务器运行的通知性信息。该指令可使用不同的日志级别，例如 "debug"、"info"、"notice"、"warn"、"error" 和 "crit"，用于确定记录消息的严重性。这些日志有助于诊断问题并监控服务器的性能与可靠性。 在最简单的形式中，error_log 指令接受一个参数，用于指定日志的文件路径。如果多次指定，NGINX 会将消息记录到多个文件中，每个文件可以有不同的日志级别。此功能使得可以对日志进行细粒度控制；例如，你可以将一般错误消息写入一个日志文件，而将关键错误写入另一个。默认情况下，日志级别设置为 "error"，这意味着除非另行配置，否则只有错误及更严重的消息会被记录。

配置示例

error_log /var/log/nginx/error.log warn;

说明

`pcre_jit` 指令控制是否对使用 PCRE（与 Perl 兼容的正则表达式）库处理的正则表达式使用 Just-In-Time (JIT) 编译。当启用 JIT 时，正则表达式会被转换为本地机器代码以提高模式匹配性能，这可以显著加快依赖正则表达式进行 location 匹配或 server 指令处理的请求处理速度。 该指令可在 `main` 上下文中使用，并可设置为 `on` 或 `off`。默认情况下，JIT 编译是禁用的（off）。然而，启用后，它可以提高使用正则表达式的 NGINX 操作的效率，尤其是在高负载条件下。必须确保系统上安装的 PCRE 库支持 JIT 编译，因为并非所有 PCRE 构建都包含此功能。 在使用 `pcre_jit` 指令时，管理员应注意，尽管它可以提升性能，但由于需要存储已编译的正则模式，可能会导致内存使用量增加。此外，在某些边缘情况下，使用复杂正则表达式可能会引发兼容性问题；因此，建议在启用此指令后对配置进行充分测试。

配置示例

pcre_jit on;

说明

`thread_pool` 指令用于定义一个线程池，允许 NGINX 将异步请求的处理卸载到线程中，这可以通过更好地利用多核处理器来提高性能。该指令接受两个到三个参数：线程池的名称、线程池的大小，以及可选的线程栈大小参数。参数允许对为使用线程处理并发连接分配的资源进行微调，有助于在服务器资源之间平衡工作负载分配。\n\n当设置了 `thread_pool` 指令时，NGINX 会在池中创建指定数量的线程，这些线程可用于处理 I/O 受限或需要阻塞操作的任务。线程独立于工作进程进行管理，允许高效地处理操作而不会阻塞主事件循环。这在诸如 Lua 脚本、文件上传或其他长时间运行的操作等场景中特别有用，这些操作如果直接在工作进程中处理通常会阻碍性能。可选的栈大小参数定义为每个线程分配的栈内存量，当将执行深度递归或占用大量栈的操作时，这一点尤为重要。\n\n应当谨慎管理线程池的大小和工作进程的数量，因为线程过多可能导致过度的上下文切换、性能收益递减，并最终造成资源耗尽。

配置示例

thread_pool my_pool 32;

说明

`devpoll_changes` 指令在 NGINX 中用于配置在使用 devpoll 事件方法时，任何时候可以监视多少个文件描述符 (file descriptors) 的事件 (events)。这一技术在可能存在大量同时连接 (connections) 的环境中尤其有用，例如高流量 Web 服务器。为其设定一个合适的值使 NGINX 能够高效处理更多连接，而不会遇到可能降低性能的限制。 `devpoll_changes` 指令的参数是一个单一的整数值，指定每次 system call 返回的最大 events 数量。如果达到该限制，任何额外的变更在有可用空间之前都不会被处理。该指令的实际行为会显著影响网络操作与客户端处理的效率，尤其是在并发量高的系统中。配置不当可能导致资源浪费或连接丢失。 重要的是在配置该参数时要考虑系统的能力和预期负载，以实现最佳性能。确保此值与环境规格（例如可用的内存和 CPU）一致，有助于最大化服务器的吞吐量。

配置示例

events {
    devpoll_changes 1024;
}

说明

`devpoll_events` 指令在 `events` 上下文中指定时，会在 NGINX 的事件驱动架构中启用 DEVPOLL 机制来处理连接。DEVPOLL 可在 Solaris 及其他类 Unix 系统的某些变体上使用，提供了一种可扩展的方法来处理大量并发连接。通过使用 DEVPOLL，NGINX 可以高效地监视并响应文件描述符上的事件，而无需执行 O(n) 线性扫描——这种扫描在诸如 select() 或 poll() 等其他事件模型中可能成为瓶颈。 该指令不接受任何参数，通常用于在高负载条件下优化服务器应用的性能。它允许 worker 进程进入睡眠并以响应方式处理传入连接或其他事件，从而由于较少的上下文切换和整体系统响应性的提高而促进更好的 CPU 使用率和性能指标。它主要有利于预期会有大量并发连接的环境，例如处理数千用户的 Web 服务器。

配置示例

events {
    devpoll_events;
}

说明

`epoll_events` 指令在 NGINX 的 `events` 上下文中使用，允许管理员指定由 epoll 系统处理的事件数量和类型。它通过优化事件的排队和处理方式，提高了 NGINX 在同时处理大量连接时的性能和可扩展性。该指令接受一个参数，用于定义应如何管理事件。通过利用 epoll 的能力，NGINX 可以实现 non-blocking I/O，同时高效管理 read and write events 的回调，从而降低延迟并提高吞吐量。 在配置 `epoll_events` 时，用户可以调整诸如最大 file descriptors 数量或特定 event masks（指示 file descriptors 在何种条件下触发回调）的参数。这种可定制性对高并发环境尤为有用，通过调优事件模型可以带来显著的性能提升。用户应熟悉 Linux 中的 epoll interface，以及不同配置对系统资源使用和应用行为的影响。因此，该指令使得异步事件处理能够更精细化，从而有助于 NGINX 在 Web 服务方面保持快速和高效的声誉。 在 NGINX 需要处理大量并发连接的场景下，通常会使用 `epoll_events` 指令，例如高流量的 Web 应用，通过优化事件循环可以在负载下维持响应性和性能。

配置示例

events {
    epoll_events 1024;
}

说明

'worker_aio_requests' 指令在 'events' 上下文中使用，用于指定每个 NGINX worker 进程可处理的同时异步 I/O (AIO) 请求数上限。该指令在 NGINX 用于传输静态文件或通过异步机制高效处理大型媒体文件的场景中特别有用。通过设置此指令，管理员可以更好地管理 worker 进程的资源使用，并根据服务器能力和工作负载的性质优化性能。 设置时，指定的值应为正整数，表示 worker 可排队的最大 AIO 请求数。如果某个 worker 超过该数，它将无法接受更多的 AIO 请求，直到部分排队请求完成。该指令有助于调整大量使用异步文件操作的 NGINX 应用的性能，在吞吐量与资源消耗之间取得平衡。因此，其值应基于具体工作负载和测试来确定，以保证在不使 worker 进程过载的前提下实现最佳性能。 'worker_aio_requests' 的行为会显著影响服务器的响应时间和整体容量，尤其是在高负载场景下。因此，必须监控服务器性能并根据应用需求和底层硬件能力在必要时调整该值。

配置示例

events {
    worker_aio_requests 1024;
}

说明

'eventport_events' 指令在 NGINX 中用于指定在事件处理模型中使用的事件端口的行为。它主要用于支持 event port API 的系统，通过采用一种可扩展的连接处理方法，实现更高效的事件驱动 I/O。该指令允许用户优化其 event loop 以获得更好的性能，尤其是在高并发场景中。 当指定 'eventport_events' 指令时，NGINX 将利用操作系统的 event port 机制，这可以极大地提升性能，因为它允许同时处理多个事件。在并发连接较多的环境中，这尤其有用，因为它减少了管理多个独立线程或进程的开销。与该指令相关的参数通常包括配置超时或其他相关属性的选项，以便根据需要调整性能。 应谨慎考虑是否使用此指令，因为它可能影响 Web 服务器的整体可扩展性和响应性。对其参数进行适当调优，可能显著提高高流量应用的吞吐量和响应时间。

配置示例

events {
    eventport_events;
}

说明

`iocp_threads` 指令特定于 NGINX 在 Windows 上的运行时，允许用户配置用于通过 IOCP (I/O Completion Ports) 模型处理 I/O completion 的线程数量。该模型提供了一种可扩展的方法来处理多个并发 I/O 操作，对于高性能负载尤其有益。默认情况下，线程数设置为 CPU cores 的数量，但可以根据应用需求显式定义以优化性能。每个 I/O completion 线程独立运行，在 I/O 请求完成并发出完成信号时对其进行处理，从而实现对系统资源的更好利用。\n\n在使用 `iocp_threads` 时，管理员应考虑线程数与预期工作负载之间的相关性。线程数过少可能在高负载下造成瓶颈，而过多则可能导致上下文切换开销。因此，建议进行性能测试以确定最佳配置。此外，该指令主要在使用 IOCP 模型的 Windows 平台上生效，在不实现该模型的 Linux 或其他操作系统上不会产生任何效果。该指令在 NGINX 配置的 'events' 上下文中定义，那里是大多数与性能相关的配置设置所在。

配置示例

events {
    iocp_threads 4;
}

说明

'post_acceptex' 指令是一个配置选项，允许用户在 NGINX 的 event processing loop 中在成功的 accept 操作之后定义要执行的自定义函数。这在扩展连接被接受后如何处理连接的行为时特别有用。通过指定一个函数，开发者可以在特定场景下对连接处理获得更深的控制，例如记录连接细节或动态修改连接设置。 该指令接受一个参数，即 NGINX 将调用的函数名。该函数应符合 NGINX 可以识别并正确执行的预期签名。该机制为开发者和系统管理员提供了灵活的方法来定制 NGINX 配置以满足特定需求。此外，由于它在 event module 的低级别运行，因此效率很高并且允许在不显著开销的情况下实现自定义行为。 在实际操作中，定义一个 'post_acceptex' 函数不仅涉及实现函数本身的细节，还需要确保它能与 NGINX 架构的其他部分良好协作。正确实现后，可以实现高级功能，如处理特殊协议、自定义日志记录，或在连接建立后立即与第三方服务集成。

配置示例

events {
    post_acceptex my_custom_accept_function;
}

说明

`acceptex_read` 指令在 NGINX 的 `events` 上下文中使用，用于控制 NGINX 在接受传入连接时是否利用 AcceptEx 套接字函数。AcceptEx 是 Windows 专用的 API，允许服务器在接受连接后立即读取传入的数据，同时减少上下文切换并提高性能。当设置为 'on' 时，NGINX 将尝试在接受连接时使用此功能，因其在处理套接字连接方面的高效性，可能在高负载下带来更好的性能。然而，该功能仅适用于支持 AcceptEx 的 Windows 平台。 此指令的参数是一个标志，可以为 'on' 或 'off'。将其设置为 'on' 时，NGINX 在管理新连接时会使用 AcceptEx 功能。相反，设置为 'off' 则会使用常规的连接接收方法。需要注意的是，尽管利用 AcceptEx 可以提升性能，但可能会在某些网络配置下引入兼容性问题，从而影响应用行为。 评估服务器的负载、处理的流量类型以及底层基础设施，有助于决定是否启用此选项。应注意，此功能仅针对 Windows，并不会影响非 Windows 平台上的 NGINX 安装。在启用 AcceptEx 前应进行适当测试，以确保不会在环境中产生任何意外的副作用。

配置示例

events {
    acceptex_read on;
}

说明

`kqueue_changes` 指令用于 NGINX 的事件处理上下文，尤其在使用特定于 BSD 风格操作系统（包括 macOS）的 kqueue 事件机制时优化性能。该指令允许用户设置在监控 file descriptors 时可排队的最大更改数，从而帮助在高负载情况下微调 NGINX 服务器的响应性。该参数指定一次可处理的挂起 file descriptors 更改的数量上限，这会影响在流量高峰期间处理连接的效率。 在设置此指令时，需考虑服务器上运行的应用类型和预期负载。较低的值可能在高流量下导致事件丢失，而较高的值则可能消耗更多内存和处理资源。平衡这些方面以确保最佳性能非常重要。例如，如果您的应用经常向监控中添加或移除 file descriptors，您可能希望增加此值以适应更高的传入连接速率。有效管理此参数可改善性能，特别是对于经历超出典型负载的连接突发的应用而言。 NGINX 默认值在许多用例中是合理的，但管理员可以根据应用的具体行为和需求调整 `kqueue_changes` 的值，以实现性能提升或降低事件队列饱和的风险。

配置示例

events {
    kqueue_changes 256;
}

说明

kqueue_events 指令专为在 NGINX 配置的 events 上下文中使用而设计。它指示 NGINX 使用 kqueue 事件通知机制，该机制效率很高，特别适合在像 FreeBSD 和 macOS 这样的与 BSD 兼容的操作系统上处理大量并发连接。通过利用 kqueue，NGINX 可以主动监视多个文件描述符，减少与轮询相关的 CPU 开销，从而在负载下实现更具扩展性的性能。 启用 kqueue_events 指令后，会影响工作进程处理事件的方式：只有在发生实际事件（例如有数据到达或连接被关闭）时，才唤醒空闲连接。这不同于可能需要定期轮询的旧事件机制，后者在连接增多时会消耗大量资源。请确保你的 NGINX 安装是以 kqueue 支持进行编译的，如果底层操作系统或构建不支持 kqueue，该指令将无法工作。 该指令接受一个参数，用于切换是否使用 kqueue。如果配置正确，优点包括由于更快的事件处理而降低的资源消耗和提高的速度。务必在暂存环境中测试该配置，确保其按预期工作且不会引入意外问题。

配置示例

events {
    kqueue_events;
}

说明

events 指令是 NGINX 架构中的关键组成部分，用于管理服务器如何处理连接。它使 NGINX 能够采用事件驱动模型，显著提升性能和可扩展性，因为与传统的多线程方法相比，能够用更少的资源处理更多的连接。在 events 块中，可以设置各种参数来优化连接处理，例如 worker_connections，它定义了每个工作进程可以处理的最大并发连接数。 该指令本身不接受任何参数，而是作为一个容器，用于包含影响 NGINX 事件循环的配置选项。在 events 块下可配置的最重要的参数是 'worker_connections'，它指定了每个工作进程允许的最大连接数。通过谨慎调整这些设置，管理员可以实现针对服务器工作负载的最佳资源管理和响应性。

配置示例

events {
    worker_connections 1024;
}

说明

worker_connections 指令对于优化 NGINX 中每个工作进程所管理的并发连接数至关重要。该指令本质上定义了单个工作进程可处理的连接上限，从而影响 Web 服务器的整体可扩展性。在确定该指令的值时，重要的是考虑服务器上的资源可用性，包括内存、CPU 和网络带宽。 为达到最佳效率，worker_connections 的值应与 worker_processes 指令一起配置。NGINX 可处理的最大潜在连接数可以计算为 `worker_processes * worker_connections`。通过调整这些参数，可以有效控制有多少客户端能够同时连接并与您的应用程序交互。 在高负载场景下，将该值设置得过高可能导致资源枯竭，从而引起服务器性能下降。根据流量模式监控并调整此指令有助于保持服务器的最佳状态。

配置示例

events {
    worker_connections 1024;
}

说明

'use' 指令允许用户指定 NGINX 在处理连接时使用的事件处理方法。根据平台以及 NGINX 内已编译的模块，该指令支持实现事件驱动架构的多种选项，例如使用 `epoll`、`kqueue` 或 `select` 方法。每种选项在服务器的运行环境下具有不同的性能特性和可扩展性。 该指令接受一个参数，用于指定所需的方法。正确的使用可确保 NGINX 有效地处理多个并发连接，优化资源使用并提高整体吞吐量。选择与服务器操作系统能力相匹配的方法至关重要；例如，在 Linux 系统上建议使用 'epoll'，而在 BSD 系统上则优先使用 'kqueue'。 配置不当，例如为特定平台指定不支持的事件方法，可能导致启动时出错或严重影响性能。了解各事件方法的权衡和能力对于在生产环境中部署 NGINX 至关重要。

配置示例

events {
    use epoll;
}

说明

`multi_accept` 指令在 NGINX 中用于优化连接处理流程，通过允许工作进程一次接受多个新连接，而不是每次仅接受一个。当启用该指令时，工作进程可以通过减少与上下文切换相关的开销以及单个连接处理的延迟来有效提高其吞吐量。 该指令可以设置为 `on` 或 `off`。当设置为 `on` 时，它指示工作进程尽可能接受操作系统套接字层允许的所有新连接。该行为在预计会有大量并发连接的高负载场景中特别有用。另一方面，当 `multi_accept` 设置为 `off` 时，默认行为是一次只接受一个连接。这可能导致传入连接的延迟增加，因为后续连接必须等待工作进程空闲以处理它们。 需要注意的是，在所有情况下启用 `multi_accept` 并不能保证带来性能提升。其效果在很大程度上取决于底层操作系统对套接字操作的处理方式以及服务器的具体负载情况。服务器管理员应监控服务器的性能，以判断启用该指令是否能达到预期的性能效果。

配置示例

events {
    multi_accept on;
    worker_connections 1024;
}

说明

NGINX 中的 `accept_mutex` 指令用于通过管理工作进程在高负载时如何处理传入连接来提高基于事件的服务器的性能。当设置为 `on` 时，该指令一次只允许一个工作进程接受新连接，从而减少竞争并提高资源利用率。在并发连接数超过单个工作进程处理能力的情况下，这尤其有用，因为它有助于防止惊群问题，即多个进程同时尝试接受新连接。 `accept_mutex` 指令依赖于 `accept_mutex_delay` 参数，该参数指定当有其他工作进程可用时，工作进程在尝试接受新连接前应等待的延迟（以毫秒为单位）。如果适当设置此延迟，它可以实现工作进程间的同步，降低资源被过载的可能性。这种同步通过确保一个工作进程“赢得”接受新传入连接的权利来实现，而其他进程则等待轮到它们。最佳配置会根据服务器的负载和底层基础设施的不同而有很大差异。

配置示例

events {
    accept_mutex on;
    accept_mutex_delay 500;
}

说明

'accept_mutex_delay' 指令在 NGINX 中指定了当 worker 进程尝试接受新连接但无法立即获取 accept mutex 时所应用的延迟。这个 mutex 对于在多个 worker 进程之间同步访问至关重要，以避免服务器因大量快速的连接请求而不堪重负。如果 worker 无法获取该 mutex，它会在再次尝试接受连接之前暂停由此指令指定的时长，从而在各 worker 之间平衡负载并提高效率。\n\n'accept_mutex_delay' 的参数以毫秒为单位定义，允许管理员根据服务器容量和预期负载进行精细调整。例如，设置 'accept_mutex_delay 500;' 允许 worker 最多等待半秒再重试。此设置会显著影响连接在多个 worker 进程之间的分配，尤其是在高并发场景下。适当的调优可以在最大化吞吐量和减少延迟的同时最小化资源争用。\n\n需要注意的是，虽然增加延迟可以在高负载时通过允许其他 worker 接受连接来改善公平性，但在低负载情况下也可能导致接受的连接数量减少，因此需要根据实际流量模式进行设置。

配置示例

events {
    accept_mutex on;
    accept_mutex_delay 300;
}

说明

`debug_connection` 指令允许用户指定某些 IP 地址，从这些地址发起的传入连接会被专门记录到调试日志中。在排查 NGINX 实例的问题时，此指令非常重要，因为它能提供来自指定客户端请求处理的详细洞见。默认情况下，如果不使用此指令，任何 IP 都不会获得增强日志记录——而这对于有效调试至关重要。 使用该指令时，指定的 IP 可以是单个 IP 地址或子网的 CIDR 表示法，从而在各种网络场景中具有灵活性。该指令必须放在 NGINX 配置的 `events` 上下文中，因为它与连接处理相关。详细的日志不仅包含标准的请求信息，还会包含额外的调试细节，帮助系统管理员识别配置错误或连接异常。 需要注意的是，如果开启大量的调试连接，会产生大量日志文件，在生产环境启用时可能需要运维上的管理。因此，该指令通常用于临时诊断针对受控用户集的特定问题，而不是对全部传入流量全面启用。 总之，`debug_connection` 指令为有选择地增强特定客户端连接的日志记录提供了一个强大的工具，从而实现更有效的调试和系统监控。

配置示例

events {
    debug_connection 192.168.1.0/24;
}

说明

'ssl_engine' 指令允许用户定义 NGINX 应该使用哪个 SSL 引擎来处理安全连接。默认情况下，NGINX 使用 OpenSSL 库，除非另有配置。当用户希望使用不同的 SSL 实现（例如 GnuTLS 或自定义 SSL 库）以获取更多功能或更高性能时，该指令非常有用。该指令仅接受一个参数，该参数对应于所需 SSL 引擎的名称。 在使用该指令时，必须确保指定的 SSL 引擎已编译进 NGINX，否则在运行时该命令将失败，可能导致启动错误。这种灵活性使系统管理员能够根据其基础设施或应用需求微调 NGINX 对 SSL/TLS 请求的处理方式。用户应始终验证所选 SSL 引擎与当前 NGINX 配置之间的兼容性，以及其整体性能和安全特性。

配置示例

ssl_engine 'openssl';

说明

指令 `ssl_object_cache_inheritable` 是一个标志，用于控制 NGINX 中 SSL 对象缓存设置的继承。 当该指令设置为 'on' 时，允许 SSL 对象缓存设置被子上下文继承，例如 server 或 location 块，从而实现对 SSL 缓存行为更灵活和集中化的管理。这在包含多个 server 块且需要共享相同 SSL 对象缓存设置的复杂配置中尤其有用。 默认情况下，SSL 缓存机制通过存储 SSL 会话参数和对象来提升性能，从而减少建立新 SSL 连接时的开销。继承这些设置的能力可确保开发者不必在各个块中重复缓存设置，简化配置过程，并将因设置不一致可能导致的错误降到最低。 如果省略 `ssl_object_cache_inheritable`，则行为默认是不允许继承，保持旧的行为，即需要在每个相关块中显式定义缓存设置。该指令在 SSL 性能至关重要的环境中尤为重要，可在不同服务器配置之间实现一致的缓存策略。

配置示例

ssl_object_cache_inheritable on;

说明

'quic_bpf' 指令在 NGINX Core 模块中用于控制是否启用用于处理 QUIC 数据包的 BPF 机制。BPF 是一个强大的功能，允许在底层对网络数据包进行过滤和操作，为 QUIC 协议提供高效的处理能力，从而通过降低延迟和改进拥塞控制来提升 Web 性能。通过使用 BPF，NGINX 能够实时分析流量模式并做出更好的决策，从而增强使用 QUIC 协议的应用程序的性能。 该指令接受一个标志参数，可设置为 'on' 或 'off'。设置为 'on' 时，NGINX 将对所有传入的 QUIC 连接应用 BPF，这可能通过更好地处理出入数据包来提高吞吐量并降低延迟。相反，设置为 'off' 则禁用此功能，恢复到没有任何 BPF 优化的 QUIC 数据包的默认处理。需要注意的是，为了使 BPF 有效工作，NGINX 必须在编译时包含支持该功能的必要库，并且底层操作系统也必须支持 BPF。

配置示例

quic_bpf on;

说明

'http' 指令是 NGINX 配置中的一个基本组成部分，提供配置 HTTP 相关设置的上下文。定义该指令后，它会封装所有其他与 HTTP 相关的指令，这些指令用于配置 Web 服务器如何处理请求和响应。此类设置包括用于 'server' 块、'location'、日志记录等的配置，允许管理员定义在不同服务器上下文和配置中如何处理传入的 HTTP 请求。 在 'http' 上下文中，管理员可以指定诸如 'server' 块之类的参数，从而启用虚拟主机设置，并配置协议设置、缓冲行为和访问控制。该结构允许对服务器行为进行细粒度控制，支持在高层应用优化和设置，影响所有已配置的服务器或选择性定义的块。该指令没有参数也表明它仅作为一个组织边界，而不需要特定选项来运行。 使用 'http' 指令意味着在其作用域内定义的后续指令与 HTTP 处理相关。例如，'server'、'location' 和 'client_max_body_size' 等指令通常嵌套在 'http' 块中，展示了其作为相关配置集合点的作用，最终有助于提高 NGINX Web 服务器的整体性能和灵活性。

配置示例

http {
    server {
        listen 80;
        server_name example.com;
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

说明

'mail' 指令在 NGINX 中对于启用 mail 模块提供的邮件处理功能至关重要。当在配置的主上下文声明时，它会激活 NGINX 作为邮件代理服务器的能力，处理诸如 IMAP、POP3 和 SMTP 等协议。该指令不接受任何参数；其在配置中仅凭存在即表示应在 NGINX 操作中包含邮件功能。 初始化时，mail 模块会根据配置文件中跟在 'mail' 指令之后的其他与 mail 相关的专用指令来设置其配置。这些指令包括定义服务器和用户凭据、认证方法以及上游服务器的指令。值得注意的是，仅有该指令本身并不会处理任何邮件；它为后续指定 NGINX 如何与邮件客户端和邮件服务器交互的配置奠定了基础。 该指令在确保 NGINX 能有效地管理和转发电子邮件请求、并与现有 mail 基础设施无缝交互方面起着关键作用。通过集成 mail 协议，NGINX 将其功能扩展到静态和动态网页内容服务之外，包含强大的电子邮件处理能力，这在负载均衡环境或将多项服务整合到统一架构时尤其有益。

配置示例

mail {
    server {
        listen 110;
        protocol pop3;
        proxy on;
    }
    server {
        listen 143;
        protocol imap;
        proxy on;
    }
}

说明

`google_perftools_profiles` 指令位于 NGINX 核心配置中，用于启用使用 Google Performance Tools (gperftools) 收集性能分析信息。该性能分析有助于监控和分析 NGINX 进程的性能，使管理员能够定位性能瓶颈并相应地优化配置。启用该指令后，NGINX 会生成可用诸如 'pprof' 等工具分析的性能剖析信息。 具体来说，该指令接受一个参数，该参数是用于存放分析数据的输出文件路径。该信息包括 CPU 使用情况、内存分配统计和调用图，这些可以为 NGINX 工作进程的运行情况提供洞察。通过仔细检查生成的分析文件，可以识别并解决性能问题，从而改善 NGINX 服务器的性能和资源利用率。 该指令必须放在 NGINX 配置的主上下文中，并应以有效路径作为其参数。如果指定的路径对 NGINX 工作进程不可写，则不会启用性能分析，这可能导致对性能得出误导性的结论。它通常与其他性能相关指令配合使用，以获得对服务器状态的全面了解。

配置示例

google_perftools_profiles /var/log/nginx/perf_data;

说明

'stream' 指令允许 NGINX 处理非 HTTP 流量，使其能够传输 TCP 和 UDP 流。这项指令可以在主上下文中配置，允许用户为各种类型的流式数据指定不同的服务器或 upstreams。在 'stream' 块内，用户可以定义多个 server 块，每个 server 可以处理与常规 HTTP 处理不同的协议、端口或 upstream 配置。 通过引入该指令，用户可以在 'stream' 上下文中使用诸如 'server' 和 'proxy_pass' 等指令来处理流。例如，可以直接在此块中设置 TCP 负载均衡，根据 round-robin、least connections 或 IP hash 等算法将资源使用偏向不同的后端服务器。此外，还可以配置连接数限制、超时设置和错误处理，以确保流处理既高效又具有弹性。 'stream' 指令使 NGINX 成为更为通用的代理，支持诸如对 TCP 服务进行 SSL 终止之类的应用，从而简化安全传输。因此，它扩展了标准 HTTP/HTTPS 范式之外的用例，允许数据库和游戏服务器等应用有效地利用 NGINX 的网络管理能力。

配置示例

stream {
    upstream backend {
        server backend1.example.com:12345;
        server backend2.example.com:12345;
    }

    server {
        listen 12345;
        proxy_pass backend;
    }
}

说明

'include' 指令旨在通过允许包含其他配置文件来增强 NGINX 配置的模块化性和可维护性。这有助于将大型配置文件拆分为易于管理的部分，便于更新和组织。通过使用 'include' 指令，用户可以在单独的文件中定义公共设置，并在不同的配置上下文中按需包含这些文件，从而促进 DRY (Don't Repeat Yourself) 原则。 'include' 指令的参数由一个或多个配置文件的路径组成。该路径可以指定为绝对路径，也可以相对于当前工作目录的相对路径。也支持通配符，从而能够包含匹配指定模式的多个文件。当 NGINX 处理主配置文件时，会按出现的顺序解析并读取 'include' 指定的文件。这些文件中的指令随后会合并到当前上下文中，允许它们相应地影响配置设置。 'include' 包含的配置文件可以定义 NGINX 的各个方面，例如 location 块、server 设置或 upstream 配置。但是，应注意避免与主配置文件中现有设置发生冲突。如果包含的文件包含更改已定义配置的指令，则在合并后的配置中最后定义的值将优先。该灵活性使 'include' 指令成为结构化复杂 NGINX 配置的强大工具。

配置示例

# Example of using the 'include' directive
include /etc/nginx/conf.d/*.conf;

说明

'allow' 指令指定哪些 IP 地址被授予对指定的 server 或 location 块的访问权限。它可以接受 IPv4 和 IPv6 地址，也可以接受用于指定 IP 地址范围的 CIDR Notation。当存在多个 'allow' 指令时，可以将它们组合以对谁可以访问资源进行细粒度控制。如果请求来自匹配某一 'allow' 规则的 IP 地址，则授予访问，除非该地址也匹配 'deny' 指令。这种设置允许将特定客户端地址列入白名单，同时拒绝或限制其他地址的访问。 通常 'allow' 指令与 'deny' 指令一起使用，后者指定应被阻止的 IP 地址。该指令可以在不同的上下文中配置，如 http、server、location 和 limit_except，从而根据应用架构灵活地执行访问规则。配置后，请求的处理将根据评估顺序决定：如果存在任何 'allow' 规则，则将在任何 'deny' 规则之前进行检查。 提供给 'allow' 指令的参数可以是单个 IP 地址或 CIDR 块，CIDR 块是一种以类似 "192.168.1.0/24" 的格式表示的地址范围。例如，'allow 192.168.1.1;' 会允许来自特定 IP 192.168.1.1 的访问，而 'allow 10.0.0.0/8;' 会允许 10.0.0.0 至 10.255.255.255 范围内的所有 IP。

配置示例

location /protected {
    allow 192.168.1.1;
    deny all;
}

说明

'deny' 指令在 NGINX 中用于根据客户端的 IP 地址控制对服务器资源的访问。它可以在多个上下文中定义，包括 http、server、location 和 limit_except，从而在定义访问规则时提供灵活性。该指令需要一个参数，即要拒绝访问的客户端的 IP 地址（或 CIDR 表示法）。当来自与某个 'deny' 规则匹配的 IP 地址的请求到达时，NGINX 将返回 403 Forbidden HTTP 状态码，从而阻止对该请求的进一步处理。 该指令可以与 'allow' 指令配合使用，后者指定被授予访问权限的 IP 地址。在同时使用这两个指令的情况下，NGINX 会按定义的顺序评估规则，如果存在匹配的 'deny' 规则，则请求将被拒绝，而不考虑后续的 'allow' 规则。此外，'deny' 指令可以为 IPv4 和 IPv6 地址定义拒绝规则，使其能够适应不同的网络环境。

配置示例

location /protected {
    deny 192.168.1.0/24;
    deny 10.0.0.1;
}

说明

指令 `add_before_body` 在 NGINX HTTP core module 中使用，用于在响应体发送给客户端之前追加特定内容。这在无需修改应用或后端服务器的情况下，直接将脚本、注释或其他标记注入响应载荷时特别有用。插入的内容可以定义为字符串字面量，在请求处理阶段作为 HTTP 响应的一部分输出。 该指令可在 `http`、`server` 和 `location` 等上下文中指定，从而实现对内容插入位置的细粒度控制。该指令的参数是一个字符串值，表示要添加的内容。配置后，`add_before_body` 在输出阶段处理请求，确保指定内容位于原始响应体之前。 由于这会修改响应结构，因此必须确保插入的内容不会干扰响应的内容类型或结构。应仔细考虑所添加的内容，以保持有效的 HTTP 响应格式。

配置示例

http {
    server {
        location /example {
            add_before_body '';
        }
    }
}

说明

`add_after_body` 指令在 NGINX 中用于定义应在 HTTP 响应结束时包含的内容，即在响应主体传输完成之后。这对于注入脚本、跟踪或分析代码，或任何需要在主要内容传送到客户端后加载的额外数据非常有用。 该指令需要一个参数，即将要追加的内容。该内容可以是纯文本、HTML，或服务器可以提供给客户端的任何有效数据片段。对于依赖客户端脚本的 Web 应用来说，这尤其有用，允许开发者添加必要的 JavaScript 片段或应在主要响应渲染后出现的 HTML 元素。通过使用该指令，可以在不直接修改原始响应主体的情况下进行内容修改，从而保留所交付内容的完整性。

配置示例

location /example {
    add_after_body '';
}

说明

'addition_types' 指令在 NGINX 中用于将文件扩展名映射到应添加到 HTTP 响应的 Content-Type 头中的自定义 MIME 类型。该指令使得 Web 服务器管理员可以处理默认 MIME 类型定义未涵盖的文件类型，确保根据文件类型正确传递内容。 'addition_types' 的语法至少需要一个参数，该参数由文件扩展名后跟 MIME 类型组成。可以在单个指令中为多个扩展名及其对应的 MIME 类型进行定义。当文件被提供时，NGINX 会将指定的扩展名与请求的文件进行匹配。如果找到匹配项，则相应的 MIME 类型会被包含在响应中，以补充 NGINX 配置中预定义的类型。 该指令可用于诸如 http、server 或 location 块等不同上下文，从而在为 Web 应用的不同部分配置 MIME 类型时提供灵活性。添加自定义 MIME 类型可以帮助避免客户端在处理文件时出现问题，确保浏览器正确解释所传送文件的内容。

配置示例

http {
    addition_types .json application/json;
    addition_types .xml application/xml;
}

说明

`auth_basic` 指令允许通过要求客户端进行 HTTP 基本认证来保护 NGINX 服务器内的位置或资源。当启用此指令时，客户端必须提供有效的用户名和密码，服务器会将其与配置中设置的凭据进行核对。该指令主要用于需要简单访问控制的场景，例如限制对网站特定部分的访问。 该指令接受一个参数，即 realm 名称。该名称是认证过程中重要的一部分，会显示在浏览器向用户呈现的认证对话框中。要完整实现基本认证，您还应将 `auth_basic_user_file` 指令与 `auth_basic` 配合使用，以指定包含允许的用户名和哈希密码的密码文件的位置。否则，该指令将无法生效，因为服务器不知道应验证哪些凭据。 在更高级的部署中，您可能希望使用 `allow` 和 `deny` 等其他指令进一步控制访问，这些指令可与 `auth_basic` 结合使用，根据客户端 IP 地址或其他条件细化哪些用户可以访问受保护的内容。

配置示例

location /private {
    auth_basic "Restricted Content";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

说明

该 `auth_basic_user_file` 指令通常与 `auth_basic` 指令结合使用，后者在特定上下文中启用基本认证。 当用户向配置了基本认证的 NGINX 服务器发出请求时，服务器会检查是否存在 `auth_basic_user_file` 指令。如果存在，服务器会读取指定的文件，将客户端提交的用户名和密码与存储的哈希进行校验。该文件必须采用特定格式，每一行包含用户名及随后跟随的密码哈希，这些哈希可以使用诸如 `htpasswd`（来自 Apache HTTP Server 套件）等工具生成。认证过程旨在限制对特定资源的访问，确保只有有效用户可以访问这些资源。 重要的是确保用户文件被安全存储并且不可公开访问，以防止未授权访问其中的敏感凭据。此外，NGINX 通过支持各种密码学哈希算法来增强安全性，从而使攻击者更难以攻破用户账户。

配置示例

location /secret {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

说明

`auth_request` 指令允许 NGINX 通过向指定位置发起子请求来处理认证。该位置用于处理认证请求；如果子请求返回 2xx 状态码，则授予对原始请求的访问权限。若响应不是 2xx 状态，则拒绝访问，原始请求不会被处理。 该指令可在多种上下文中使用，包括 `http`、`server` 和 `location`，便于在不同服务器配置中灵活集成。该参数期望一个单一的位置名或路径，NGINX 将使用它来执行认证检查。通常，这会是一个专门的端点，用于处理检查用户凭据或对所评估请求的访问条件的逻辑。 在使用 `auth_request` 时，必须确保子请求位置已正确配置，以根据认证结果返回正确的状态码。若需要，子请求还可以携带原始请求的头部，从而允许更复杂的认证检查（例如考虑客户端信息）。

配置示例

location /protected {
    auth_request /auth;
}

location = /auth {
    internal;
    # Authentication logic here
    if ($http_authorization = "Bearer valid_token") {
        return 200;
    }
    return 401;
}

说明

`auth_request_set` 指令在 NGINX 中用于定义一个变量，该变量用于存储内部认证请求的结果。通常该指令接受两个参数：要设置的变量名以及要检查的响应（可以是状态码或特定变量）。在内部认证请求成功的情况下，该变量会被设置；如果失败，则该变量保持未设置状态或重置回初始状态。 该指令与 `auth_request` 指令结合使用时尤其有用，它通过评估认证请求的结果来实现更细粒度的访问控制。例如，基于 `auth_request_set` 设置的变量的值，可以执行附加逻辑，从而实现不同的访问级别或错误处理。如果认证请求返回 2xx 响应，则表示成功；任何 4xx 或 5xx 响应均表示失败，从而可以对未授权访问尝试做出可配置的响应。`auth_request_set` 指令的位置灵活，可在 `http`、`server` 或 `location` 上下文中使用，从而为配置提供了广泛的灵活性。 此外，确保内部认证请求配置正确且可达非常重要。该变量的行为以及它与其他指令的交互可能会显著影响 NGINX 的路由和访问控制行为，因此在生产环境中实现时需要进行充分测试。

配置示例

location /protected {
    auth_request /auth;
    auth_request_set $auth_status $upstream_status;
    error_page 401 = @error401;
} 
location = /auth {
    internal;
    proxy_pass http://backend_auth;
}

说明

'autoindex' 指令允许 NGINX 在目录中没有索引文件时生成并显示文件列表。当启用时，如果用户请求一个没有索引文件（例如 index.html 或 index.htm）的目录，NGINX 将返回该目录中文件的可排序列表。 该指令可在不同上下文中设置：http、server 和 location。通过设置 'autoindex on'，用户可以暴露目录内容，这在调试时可能有用，但如果敏感文件被无意中暴露，则可能带来安全风险。输出可以通过相关指令定制，例如 'autoindex_format'，以使用不同的输出格式（如精简或完整列表）。 重要的是要适当配置目录权限以避免未经授权的访问。当 'autoindex' 与像 'allow' 和 'deny' 这样的访问控制指令结合使用时，NGINX 会先应用访问规则以决定是否拒绝或允许该请求，然后才处理索引。

配置示例

location /files {
    autoindex on;
}

说明

`autoindex_format` 指令用于指定在启用 NGINX 的 autoindex 功能时目录列表的输出格式。该指令允许用户更改生成的 HTML 的外观，以提高可读性或实现自定义。NGINX 支持若干预定义格式，例如 `html` 和 `json`，每种格式对应不同的呈现风格。当在配置文件中设置该指令时，NGINX 会使用指定的输出格式，而不是回退到默认配置，从而增强目录索引对可能依赖响应中特定数据结构的客户端或应用程序的可用性。 在实际场景中，`autoindex_format` 可用于以友好的 HTML 方式展示目录内容（例如包含链接和文件大小），或以 `json` 格式用于 API 消费，这样可以被程序化地解析。该格式必须在有效的上下文中设置，具体为 `http`、`server` 或 `location` 级别，从而允许根据 NGINX 配置的作用域进行全面控制。该指令主要支持与各种客户端应用的集成，这些应用根据其期望的格式以不同方式处理目录列表。

配置示例

location /files {
    autoindex on;
    autoindex_format json;
}

说明

NGINX 中的 `autoindex_localtime` 指令会影响在启用目录索引时目录列表的生成方式。当该指令设置为 'on' 时，NGINX 会在目录列表中显示文件的最后修改时间为本地时区，而不是 UTC，这对更习惯于本地时间而非协调世界时的用户更直观。 该指令可放在多个上下文中，包括 'http'、'server' 和 'location'，从而根据请求的作用域对其行为进行细粒度控制。该指令的参数只是一个标志：'on' 用于在目录列表中启用本地时间显示，'off' 用于禁用，且默认为 'off'。启用此功能可以提升用户体验，尤其是对于需要以用户友好方式显示文件元数据的应用，因为它让用户看到与其地理位置相关的时间格式，而无需从 UTC 进行转换。 需要注意的是，启用 `autoindex_localtime` 并不会更改存储在服务器上的文件的实际时间戳；它只是改变了这些时间戳在目录列表中向终端用户显示的方式。

配置示例

location /files {
    autoindex on;
    autoindex_localtime on;
}

说明

`autoindex_exact_size` 指令用于 NGINX HTTP 服务器中，用以决定在自动生成的目录列表中如何显示文件大小。当此指令启用（设置为 'on'）时，NGINX 将以字节显示文件的精确大小。如果设置为 'off'，在提供目录列表时会将大小转换为更易读的格式（例如 KB、MB 等）。此设置对于需要精确文件大小数据的用户尤其有用，特别是在需要密切监控文件大小的环境中。 此指令适用于 `http`、`server` 和 `location` 上下文，允许根据应用架构灵活放置。该指令接受一个标志参数：可以是 'on' 或 'off'。这些选项的存在允许服务器管理员根据特定服务器位置或整个服务器配置的需求自定义 autoindex 的行为。

配置示例

location /files {
    autoindex on;
    autoindex_exact_size on;
}

说明

'modern_browser' 指令在 NGINX 配置中使用，用于指定哪些浏览器应被视为现代浏览器并在处理请求时区别对待。它可以通过根据客户端能力启用或禁用某些功能或行为来提升 Web 应用的性能。该指令可以接受一个或两个参数，允许用户定义在何种具体条件下对现代浏览器应用某些优化或规则。例如，如果请求来自被识别为现代浏览器的客户端，NGINX 可以相应地调整其响应或路由行为。 在配置该指令时，如果指定一个参数，则表示浏览器版本；第二个可选参数可定义额外的兼容性设置。该指令适用于多种上下文，包括 HTTP、server 和 location 块，允许管理员根据用户的浏览器优化服务器响应，可能通过利用诸如 HTTP/2 或特定缓存机制等现代技术来提升整体用户体验。要有效利用此指令，正确理解 user-agent strings 和浏览器能力至关重要。

配置示例

server {
    location / {
        modern_browser Firefox 90;
    }
}

说明

'ancient_browser' 指令在 NGINX 中用于管理来自被视为过时或与现代 web 标准不兼容的浏览器的入站请求。通过指定 'ancient_browser' 指令，服务器管理员可以决定是否提供特殊内容、将用户重定向到不同的 URL，或对这些旧版浏览器应用具体策略。当处理安全问题或确保使用过时浏览器的用户了解其技术限制时，这一点尤其有用。 该指令可以接受多个参数，每个参数代表一个被识别为过时浏览器的特定浏览器或 user-agent 字符串。其行为可以包括自定义错误页面、重定向至升级提示，或为这些过时客户端提供专门设计的简化版站点。在定义哪些浏览器属于此类别时的灵活性，使得 NGINX 服务器能够对旧客户端进行细粒度控制，从而在可访问性与现代 web 性能之间取得良好平衡。 在配置该指令时，重要的考虑因素包括确保指定了正确的 user-agent 模式，并理解不同上下文（http、server 和 location）会影响指令的有效性。同时也要在支持旧技术与维护服务器的安全性和性能标准之间取得平衡。

配置示例

http {
    ancient_browser "MSIE 5.0";
    ancient_browser "Mozilla/4.0";
    location / {
        # Normal processing
    }
}

说明

`modern_browser_value` 指令用于设置或修改与现代浏览器发起的请求相关的 HTTP 响应。它将处理特定浏览器行为的配置集中化，允许根据请求是否来自被识别的现代浏览器进行针对性的优化和响应调整。 配置后，该指令提供了一种指定值的方式，以修改服务器的响应头，特别为现代网页浏览器量身定制。这可以改善网站某些功能的浏览器兼容性和性能，或通过向现代浏览器提供有关如何处理特定资源的专门指示来增强安全性。参数可以包含用于指定缓存策略或响应格式的值，这些值是专为支持先进技术的新浏览器版本设计的。

配置示例

modern_browser_value "joyful_response";

说明

`ancient_browser_value` 指令在 NGINX 中用于为被识别为 'ancient' 的过时网页浏览器发起的请求指定响应设置。基本上，此指令表明 NGINX 应如何处理这些请求，使其能够优化响应或应用特定规则以提升用户体验或保持兼容性。该指令可以放置在诸如 `http`、`server` 或 `location` 等不同上下文中，根据配置范围提供灵活的应用。 该指令接受单个参数，通常是用于表示在检测到此类请求时应采取的操作或设置的数值或字符串。指令的行为会影响资源的提供方式，尤其适用于旨在支持广泛用户代理的网站。对于仍依赖旧版浏览器技术的遗留系统，这尤其有用，可确保这些系统接收潜在的补丁或指向更新资源的提示，而不是被直接拒绝访问。 例如，如果服务器判断 用户代理 符合被归类为 'ancient' 浏览器的条件，服务器可以返回自定义消息或重定向到建议用户升级浏览器的页面。总之，该指令是为希望在多样化用户群中保持可访问性的 Web 开发者提供的一个实用工具。

配置示例

http {
    ancient_browser_value "Upgrade your browser";
}

说明

'charset' 指令用于在 NGINX 发送给客户端的 HTTP 头中定义应使用的字符集。它通过告诉浏览器传输数据的编码方式，在确保内容在客户端正确显示方面起着关键作用。这对于需要准确处理不同语言或符号的 Web 应用程序非常重要。 该指令接受一个参数，用于指定要使用的字符集，例如 'utf-8'、'iso-8859-1' 或 'windows-1251'。当设置该指令时，NGINX 会在响应的 'Content-Type' 头中包含 'charset'，从而将此编码传达给客户端的浏览器。这可以帮助防止与字符显示不正确相关的问题，例如乱码或意外符号。 此外，'charset' 指令可以按上下文进行配置，也就是说可以在 HTTP、server 或 location 块中设置。这允许对 Web 应用不同部分如何处理字符编码进行细粒度控制，使其在网站各部分提供的内容上更具适应性。

配置示例

http {
    charset utf-8;

    server {
        location / {
            charset iso-8859-1;
        }
    }
}

说明

`source_charset` 指令在 NGINX 中用于为处理传入请求体建立字符集。该指令在处理表单和 POST 数据内容时尤为重要，可确保服务器根据指定的编码正确解释字符。该指令可应用于多种上下文，包括 `http`、`server`、`location` 和 `if in location`，从而允许根据不同的服务器位置或请求类型进行灵活配置。 在定义 `source_charset` 时，必须提供一个单一的字符集值作为参数，例如 'utf-8'、'iso-8859-1' 等。如果在处理传入数据时未指定字符集，NGINX 将默认以可能导致字符误表示的方式来解释数据，尤其是包含非-ASCII 字符的内容。对于处理多语言文本或来自编码标准各异地区的数据的应用程序来说，确保合理设置 `source_charset` 是至关重要的。 此外，某些字符集可能具有特殊的处理说明或限制，因此应查阅 NGINX 文档以了解支持的字符集以及它们在不同上下文中实现时的任何细节差异。错误配置或不正确的字符集值可能导致数据损坏、请求失败或服务器错误，因此在 NGINX 配置中测试和验证字符集设置非常重要。

配置示例

# Set the source charset to UTF-8 for proper encoding handling
source_charset utf-8;

说明

NGINX 中的 `override_charset` 指令用于控制服务器所提供内容的响应字符编码。默认情况下，会遵从响应的 Content-Type 头中指定的字符集。然而，有些情况下管理员可能希望强制使用不同的字符集，而不管后端服务指定了什么。将 `override_charset` 设置为 `on` 可实现此目的。 当 `override_charset` 设置为 `on` 时，NGINX 会用服务器配置的字符集替换响应的 Content-Type 头中指定的任何字符集。这在来自不同来源的内容可能使用不一致字符集的环境中尤其有用，或者当服务器需要对所有 HTTP 响应应用统一字符集策略时。相反，当该指令设置为 `off`（默认设置）时，NGINX 将允许 Content-Type 中指定的字符集优先，从而可能导致不同响应之间的字符编码不一致。 该指令可以在多种上下文中配置，即 `http`、`server`、`location`，以及 `location` 内的 `if` 块中。每种上下文都允许根据不同的请求处理场景细化字符集行为。强制使用特定字符集可以提高与期望特定编码的客户端的兼容性，从而避免字符误解读相关的问题，尤其是在多语言内容中。

配置示例

http {
    override_charset on;
    server {
        location / {
            root   html;
            index  index.html index.htm;
        }
    }
}

说明

NGINX 中的 `charset_types` 指令允许管理员指定哪些内容类型将应用特定的字符编码。该指令接受一个或多个 MIME types 作为参数，并且必须在 `http`、`server` 或 `location` 区块中使用。当响应匹配所定义的某一 MIME types 时，NGINX 会自动为该字符集添加相应的 `Content-Type` 头，从而告知客户端如何正确解释响应数据。 例如，如果您定义了 `charset_types text/html application/json;`，对于任何带有 `Content-Type: text/html` 或 `Content-Type: application/json` 的响应，NGINX 都会发送由 `charset` 指令定义的字符集。通过为不同的文件类型定义默认字符集，这在确保客户端正确渲染文本方面尤其有用，并提升与诸如 UTF-8 之类的多字节字符编码的兼容性。 如果请求的内容类型不匹配 `charset_types` 中指定的任何类型，NGINX 将不会对这些响应应用由 `charset` 指令定义的默认字符集，从而对不同内容类型如何处理字符编码提供更精细的控制。

配置示例

http {
    charset UTF-8;
    charset_types text/html application/json text/css;
}

说明

`charset_map` 指令允许用户指定在 NGINX 的 `http` 上下文中，不同字符集应如何映射到 MIME 组件。这对于确保 NGINX 所提供的内容正确标识其字符编码尤其有用，字符编码会影响浏览器如何显示内容。`charset_map` 块中的每一项由源字符集和目标字符集组成，提供了一种在需要时在不同编码之间转换的方法。 该指令在 `http` 上下文中生效，使用一个块结构进行配置，包含一系列格式为 `charset source_charset destination_charset;` 的条目。例如，如果某个字符集应被视为另一个字符集（例如将 `latin1` 映射到 `utf-8`），可以在该块中声明。当 NGINX 处理请求时，会查阅此映射以确定如何为发送给客户端的内容处理字符编码。 需要确保所定义的映射是准确且必要的，因为错误的配置可能导致客户端浏览器上的内容渲染不正确。此外，这对国际化也非常重要，内容可能需要根据用户位置和偏好以不同语言和编码进行提供。

配置示例

charset_map {
    charset windows-1251 utf-8;
    charset iso-8859-1 utf-8;
};

说明

`dav_methods` 指令用于定义客户端通过 WebDAV 与资源交互时被允许的 HTTP 方法集合。该指令对于管理通过 HTTP 请求操作的资源权限至关重要。通过允许诸如 `GET`、`PUT`、`DELETE` 和 `PROPFIND` 等特定方法，管理员可以控制客户端在服务器上能执行哪些操作，从而增强安全性和功能性。 例如，如果该指令配置为允许 `PUT`，客户端将能够上传文件；而禁止 `DELETE` 则会阻止它们删除文件。这种细粒度的控制对于严重依赖 WebDAV 的服务来说非常重要，能够让服务器根据交互的方法做出适当响应。该指令可以接受一个或多个参数，这些参数对应于您希望允许的 HTTP 方法，从而在设置权限时提供灵活性。 总之，`dav_methods` 指令可在 `http`、`server` 或 `location` 上下文中使用，对于确保仅允许期望的 HTTP 操作从而有效保护您的 WebDAV 服务非常关键。

配置示例

location /dav {
    dav_methods PUT DELETE PROPFIND;
}

说明

'create_full_put_path' 指令是 NGINX 中的一个配置选项，用于指定在 PUT 请求期间是否为客户端上传的文件创建完整路径。将其设置为 'on' 时，NGINX 不仅会创建 PUT 请求中指定的目标文件，还会确保通向该目标文件的所有目录都已存在。在客户端可能尝试将文件上传到服务器上尚未创建的路径的场景中，这一点尤为重要，从而通过确保必要的目录结构就位来增强对文件上传的处理能力。 将指令设置为 'off'（默认）时，如果 PUT 路径中指定的某个目录不存在，NGINX 会返回 403 Forbidden 错误。然而，如果启用了 'create_full_put_path'，在 PUT 操作期间如果中间目录缺失，NGINX 会尝试自动创建这些目录，从而允许上传成功。这在管理文件上传时非常方便，并且可以帮助防止客户端使用 PUT 请求时因目录缺失而导致的失败。 就期望行为而言，当该指令放在 http、server 或 location 上下文中时，其行为是一致的，使其在需要文件上传的各种配置中具有灵活性。

配置示例

location /uploads {
    create_full_put_path on;
    root /var/www;
}

说明

指令 `min_delete_depth` 在 NGINX 的文件系统处理过程中用于指定进行删除操作所需的最小目录深度。当设置该指令时，NGINX 只允许删除深度大于或等于指定级别的目录。通过对删除操作施加更严格的条件，这对于防止意外删除根目录或顶级目录特别有用。 在 NGINX 的分层配置中，目录深度根据路径中斜杠 (/) 的数量来计算。例如，路径 `/var/www/html` 的深度为 2。该指令通过确保只有满足最小深度条件的目录才能被删除，从而有助于防止不可逆的删除。这样，管理员在管理服务器文件结构时可以降低与数据丢失相关的风险。 该指令可以在多个级别设置，包括 `http`、`server` 和 `location`，根据配置需要提供灵活性。分配给 `min_delete_depth` 的值必须是一个正整数，对应允许删除所需的目录深度。

配置示例

http {
    min_delete_depth 2;
}

说明

在 NGINX 的 HTTP 模块中，`dav_access` 指令用于根据客户端 IP 地址指定规则，以控制对 WebDAV 资源的访问。通过允许或拒绝特定的 IP 地址或地址范围，站点管理员可以管理谁可以访问通过 WebDAV 提供的资源。该指令可以包含一到三个参数，具体取决于所需的操作，通常涉及指定 'allow' 以授予访问或 'deny' 以限制访问。它通过将传入请求的 IP 地址与提供的规则进行比较来相应地允许或阻止该请求。 在配置 `dav_access` 时，管理员可以定义多个规则，这些规则可以是包含性的（allow）或排他性的（deny）。规则可以按层级结构组织，这意味着当冲突发生时，deny 规则可以覆盖 allow 规则。需要注意规则的顺序，因为 NGINX 会按顺序处理它们，并应用与第一个匹配规则相对应的操作。用户还可以组合 IPv4 和 IPv6 的规则，这些规则在配置中会被分别处理。

配置示例

location /webdav {
    dav_methods PUT DELETE MKCOL COPY MOVE;
    dav_access allow 192.168.1.0/24;
    dav_access deny all;
}

说明

`degradation` 指令允许用户根据服务器处理期间指定的条件自定义请求的处理。当使用该指令时，它会配置影响服务器行为的参数，这对需要优先处理某些流量类型或在不同负载条件下进行调整的应用尤其有用。该指令接受一个参数，该参数会影响请求的评估和处理方式，但关于该参数的有效选项和运行上下文的具体细节需要参考相关模块文档和系统资源。 该指令在基于实时负载或访问模式动态管理服务质量时尤其有用。通过实施 degradation 参数，管理员可以确保在更高负载下，应用仍能通过限制访问、调整响应行为或定义回退策略等方式继续运行。该机制对于在高峰使用时段或处理不稳定网络条件时保持服务连续性和性能至关重要。示例场景可能包括降低某些类型请求的优先级、启用详细日志以便故障排查，或调整响应时间。

配置示例

http {
    degradation 1;
}

说明

'degrade' 指令在 NGINX 中允许管理员指定当主后端服务器不可用时服务器应如何表现。该指令在可能有多个 upstream 服务器或服务的负载均衡设置中特别有用。启用 'degrade' 指令后，NGINX 会允许将服务器请求路由到指定的二级服务器或预定义的服务器集合，即使一个或多个 upstream 服务器宕机。这有助于保持服务可用性，并确保在故障情况下用户仍能收到响应。 启用该指令后，它会通过允许从二级资源提供请求而不是直接拒绝请求来实际改变失败时的行为。这在需要保持高可用性的环境中尤其有用。管理员必须确保已配置适当的回退设置，例如在 upstream 上下文中定义备用服务器，以有效利用该指令。此外，成功使用该指令还依赖于整体的健康检查和对 upstream 服务器的正确配置。

配置示例

http {
    upstream backend {
        server primary_server;
        server backup_server backup;
    }
    server {
        location / {
            proxy_pass http://backend;
            degrade;
        }
    }
}

说明

'empty_gif' 指令在 NGINX 配置的 location 上下文中使用，用于指示服务器在请求匹配该 location 时返回一个小的透明 GIF 图像。该指令在用作跟踪像素或占位符时特别有用——在内容不可用但客户端跟踪需要响应的场景中。该指令不接受任何参数，并且会启用一个内置的 URL 响应来返回该空 GIF 图像，该图像尺寸为 1x1 像素且完全透明。 当对包含 'empty_gif' 指令的 location 发出请求时，NGINX 将不会在该 location 中继续处理该请求的其他指令；相反，它会生成一个包含 GIF 图像数据的 HTTP 响应。NGINX 的默认行为是执行典型的请求处理，除非像 'empty_gif' 这样的指令另有指定。因此，要有效使用该指令，需要在服务器的 location 定义中谨慎放置，以确保它不会无意中覆盖其他配置设置。 该指令增强了服务器在无需在服务器上保存实际图像文件的情况下提供多种功能的能力，从而在分析跟踪或视觉占位等用例中优化资源使用并简化配置。

配置示例

location /tracking {
    empty_gif;
}

说明

NGINX 中的 `fastcgi_pass` 指令用于指定将负责处理请求的 FastCGI 服务器的位置。它可以把流量指向 TCP 套接字、Unix 套接字，或带指定端口的 IP 地址。该指令通常在 `location` 块中配置，使 NGINX 能够根据 URL 路径和其他参数管理请求的处理方式。当接收到请求时，请求会被转发到已定义的 FastCGI 服务器，该服务器处理请求并将相应的响应返回给 NGINX，随后 NGINX 将该响应发送给客户端。 在使用场景中，你通常会将 `fastcgi_pass` 指令与其他指令（例如 `fastcgi_param`）一起配置，`fastcgi_param` 用于为 FastCGI 应用设置参数（例如脚本文件名、请求方法等）。FastCGI 服务器会返回已处理的数据，NGINX 将该响应转发回客户端。该机制对于 Web 应用中的动态内容生成至关重要，因为后端处理被卸载到 FastCGI 服务器，从而提升性能和可扩展性。

配置示例

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

说明

NGINX 中的 `fastcgi_index` 指令指定当对不包含文件名的 `location` 发起 FastCGI 请求时要提供的默认文件。当客户端请求一个目录时，NGINX 会检查该目录中是否存在指定的 `fastcgi_index` 文件。如果请求中没有提供具体文件，NGINX 会自动将 `fastcgi_index` 的值附加到请求中，以便 FastCGI 服务器生成响应。 该指令通常与 `fastcgi_param` 和 `include` 设置配合使用，从而更无缝地集成 PHP 或其他基于 FastCGI 的应用。它通过确保在预期有索引文件（例如 `index.php`）时自动提供该文件，从而提升用户体验，而无需客户端显式指定。该指令可以在多个配置层级设置：`http`、`server` 和 `location`，这使得在不同 NGINX 上下文中可以进行更细粒度的控制。

配置示例

location / {
    index index.php;
    fastcgi_index index.php;
    fastcgi_pass 127.0.0.1:9000;
    include fastcgi_params;
}

说明

`fastcgi_split_path_info` 指令允许你指定一个正则表达式，用来匹配请求 URI 的一部分并将其分为两个部分："script" 部分和 "path info" 部分。这对于 FastCGI 应用至关重要，在这些场景中你可能希望将某些 URI 请求路由到特定脚本，同时传递剩余的路径信息进行处理。该指令定义了 URI 的解析方式，使底层应用能够有效地处理请求。 当设置该指令时，服务器会根据指定的模式处理请求 URI，并将 script 与 path info 分别捕获到环境变量 `SCRIPT_NAME` 和 `PATH_INFO` 中。此功能允许开发者创建简洁的 URL，同时仍使脚本能以预期的输入正确运行。作为参数提供的正则（regex）应被慎重构造以充分捕获所需内容，否则不当的模式可能导致意外行为或请求路由错误。 该指令可用于 `http`、`server` 和 `location` 上下文，使其在 NGINX 配置的不同层级都非常灵活。重要的是确保所提供的正则表达式符合 NGINX 使用的语法，并且不会与服务器中已存在的路由冲突。

配置示例

location ~ \.php$ {
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_pass 127.0.0.1:9000;
    include fastcgi_params;
}

说明

`fastcgi_store` 指令用于定义 NGINX 在存储从 FastCGI 服务器接收的响应时的行为。当设置该指令时，它指示 NGINX 将 FastCGI 应用的响应主体保存到磁盘上的文件，从而提高对相同 FastCGI 资源的重复请求的处理效率。 指定时，第一个参数应为响应应被存储的有效文件路径或 URI。该功能支持各种文件系统能力；例如，它可以是基于请求变量动态生成的文件路径，或是静态路径。存储方式还可以涉及根据所需配置设置文件权限——在为从 FastCGI 响应提供静态文件而设置文件权限时非常有用。 此外，该指令对缓存有影响，因为它将响应作为文件存储，从而比标准的内存缓存提供更持久的缓存机制。然而，在配置这些存储文件的存储路径、权限和清理策略以在运行期间适当管理磁盘空间时，需要谨慎考虑。

配置示例

location /example {
    fastcgi_pass backend;
    fastcgi_index index.php;
    fastcgi_store on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

说明

'fastcgi_store_access' 指令指定使用 FastCGI 模块存储的文件的访问权限。该指令允许操作人员根据客户端的 IP 地址定义哪些客户端可以访问存储的文件，使用 allow 或 deny 规则。它最多可以接受三个参数，每个参数表示根据指定的 IP 地址生效的不同访问规则。该指令在可能将敏感数据存储于 FastCGI 响应生成的文件的场景中特别有用，因此必须严格控制访问以防止未授权访问。 当设置此指令时，NGINX 会将传入请求与指定的访问规则进行比对。如果客户端的 IP 与任何 'allow' 规则匹配，则授予访问；如果匹配 'deny' 规则，则拒绝访问。如果没有规则适用，则由默认配置决定访问行为。该指令提供了灵活的控制，允许管理员根据应用需求精细调整访问级别。例如，可以配置为仅允许来自特定网络或 IP 地址的访问，同时拒绝其他访问，从而增强存储的 FastCGI 响应的安全性。

配置示例

location /store {
    fastcgi_store on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_pass backend;
}

说明

当 `fastcgi_buffering` 指令设置为 `on` 时，它会在将响应发送给客户端之前对来自 FastCGI 服务器的响应进行缓冲。该缓冲机制允许 NGINX 通过先将来自 FastCGI 服务器的整个响应体读取到缓冲区，然后再转发给客户端，从而更高效地处理响应。相反，当设置为 `off` 时，响应在接收后会立即传递给客户端，这可以提高响应速度，但可能以资源管理为代价，尤其是在高负载下。 当该指令设置为 `on` 时，NGINX 使用若干预设的缓冲区大小，这些大小可以使用诸如 `fastcgi_buffers` 和 `fastcgi_buffer_size` 等其他指令进行调整。总体的缓冲策略可以降低客户端的延迟，因为一旦完整响应被获取，NGINX 可以更快地发送更大的数据块，这对较大的响应体尤其有用。然而，缓冲需要谨慎管理；过度缓冲可能导致内存使用增加。 该指令可以在 `http`、`server` 或 `location` 上下文级别进行配置，根据具体需求实现灵活配置。理解两种设置（`on` 与 `off`）的影响对于基于应用需求对 NGINX 进行性能优化至关重要。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_buffering off;
    include fastcgi_params;
}

说明

在 NGINX 中，指令 `fastcgi_request_buffering` 允许管理员在 FastCGI 模块处理请求时启用或禁用对请求体的缓冲。默认情况下，当该指令设置为 'on' 时，NGINX 会在将请求体传递给 FastCGI 进程之前缓冲整个请求体。这可以提升性能，尤其是在应用需要在处理前获得完整请求数据的场景中。 但是，将 `fastcgi_request_buffering` 设置为 'off' 允许请求直接流式传输到 FastCGI 应用，而无需在 NGINX 中进行中间缓冲。对于处理大文件上传或应用实时处理数据的情况，这尤其有用。使用此设置后，数据可以在接收时开始被处理，可能降低内存消耗并提高大型有效载荷或长时间运行请求的响应性。 该指令可以在 `http`、`server` 或 `location` 上下文级别指定，从而根据特定位置或 `server` 块的需要对请求处理行为进行细粒度控制。

配置示例

location /upload {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_request_buffering off;
}

说明

`fastcgi_ignore_client_abort` 指令是 NGINX 中的一个配置选项，用于管理通过 FastCGI 接口处理的请求的行为。启用时（设置为 'on'），即使发起请求的客户端在响应完全发送之前断开连接，NGINX 仍会继续处理来自后端 FastCGI 服务器的响应。相反，如果将该指令设置为 'off'，当客户端断开连接时 NGINX 将终止 FastCGI 请求；在需要优先考虑资源节约的某些用例中，这一点尤为重要。该指令可用于控制在客户端可能放弃请求的情况下资源如何被使用，从而有可能减少正在进行的后端处理带来的成本。 需要注意的是，如果您有预期即使在客户端断开后仍需完成的长时间运行的 FastCGI 请求，启用此指令可能会有利。但在响应是动态生成并且与客户端会话相关的场景中，保留默认值（off）可能更为谨慎，以避免不必要的处理和资源分配。此指令可以在 `http`、`server` 或 `location` 上下文中设置，从而决定客户端断开连接行为的作用范围。

配置示例

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_ignore_client_abort on;
}

说明

`fastcgi_bind` 指令在 NGINX HTTP 服务器中用于指定在处理请求时 FastCGI 服务器应绑定的地址或套接字。该指令可以接受一个或两个参数。第一个参数是地址（IPv4 or IPv6）或 Unix 套接字路径，表示 FastCGI 服务器可以在该处监听连接。可选的第二个参数可以指定要绑定的端口，从而允许对 FastCGI 进程使用的网络接口和端口进行更细粒度的控制。 当使用 Unix 套接字时，语法通常仅为套接字的路径，不带任何端口指定。对于可能运行多个 FastCGI 服务器的场景，该绑定机制至关重要，因为它允许 NGINX 将流量定向到正确的 FastCGI 实例。然后可以根据提供的绑定有效地分配 FastCGI 服务器，从而通过减少不必要的网络开销来提升性能。 在将依赖 FastCGI 的应用部署到 NGINX 时，正确配置 `fastcgi_bind` 指令至关重要，它可确保根据应用的需求正确分配服务器资源并保持对客户端请求的响应能力。作为参考，该指令可在 `http`、`server` 或 `location` 块中使用，这为在 NGINX 安装的不同部分配置 FastCGI 处理器提供了很大的灵活性。

配置示例

location ~ \.php$ {
    fastcgi_pass   127.0.0.1;  # Example FastCGI server address
    fastcgi_bind   127.0.0.1:9000;
}

说明

`fastcgi_socket_keepalive` 指令可用于控制是否应保持与 FastCGI 服务器的持久连接。设置为 'on' 时，NGINX 会在请求处理完成后保持 FastCGI socket 打开，从而允许额外的请求重用现有连接，而不是建立新的连接。通过减少 socket 创建和销毁的开销，特别是在对同一 FastCGI 服务器发起大量请求的高负载情况下，这可以提升性能。 该指令可以在 `http`、`server` 或 `location` 上下文中指定，因而非常灵活，可以全局应用或应用于特定的 server 块或 location。该标志也可以设置为 'off'，如果禁用 keepalive 行为，则每个对 FastCGI 服务器的请求都会建立新的连接。调整此设置时需仔细考虑 FastCGI 服务器处理持久连接的能力以及可能影响性能的任何超时配置。

配置示例

http {
    server {
        location / {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_socket_keepalive on;
        }
    }
}

说明

The `fastcgi_connect_timeout` 指令指定 NGINX 在连接到 FastCGI 服务器之前等待的最长时间，然后才会使请求失败。这个超时在你的 FastCGI 服务器负载很高或响应较慢时尤为关键，因为它有助于防止 NGINX 在等待建立连接时无限期挂起。如果在指定的时间范围内无法建立连接，请求将被中止，并向客户端返回 504 Gateway Timeout 错误。 此指令在 `http`、`server` 或 `location` 的配置上下文中设置，允许全局配置或针对某些 server 块或 location 路径进行特定配置。`fastcgi_connect_timeout` 的值以秒为单位指定，可以设置为正整数。根据 FastCGI 服务器的预期响应时间选择合适的值很重要，既不能太长（会导致不必要的延迟），也不能太短（会导致过早超时）。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_connect_timeout 30s;
    include fastcgi_params;
}

说明

`fastcgi_send_timeout` 指令指定 NGINX 等待 FastCGI 服务器发送响应的最长时间。如果超过此限制，NGINX 将终止与 FastCGI 服务器的连接并向客户端返回错误。该值以毫秒为单位指定，可帮助防止由无响应的 FastCGI 应用引起的延迟。该指令可以在 `http`、`server` 或 `location` 块级别设置，根据具体用例实现灵活配置。 在配置 `fastcgi_send_timeout` 时，应根据 FastCGI 后端的预期响应时间设置适当的值。超短的超时可能会对正常请求导致不必要的错误，而超长的超时可能会延迟对无响应请求的处理。可以配合 `fastcgi_read_timeout` 和 `fastcgi_buffering` 等指令进一步细化此指令的行为，从而有效地同时控制响应处理和超时策略。

配置示例

location /app {
    include fastcgi_params;
    fastcgi_pass backend;
    fastcgi_send_timeout 30s;
}

说明

`fastcgi_send_lowat` 指令用于通过为发送数据指定阈值来优化 NGINX 向 FastCGI 服务器发送数据的方式。当待发送数据的总字节数低于该阈值时，进程可以在不阻塞的情况下发送更多数据，从而在高负载情况下提高性能。该指令在低延迟至关重要的场景中很有用，例如依赖于 FastCGI 后端频繁且较小响应的 Web 应用程序。 `fastcgi_send_lowat` 的参数是一个表示字节数的单一整数值。当设置该值后，如果排队准备发送到 FastCGI 服务器的数据量超过此阈值，NGINX 将开始阻塞或限制后续发送操作。这样可以确保在不使服务器过载的情况下，网络资源被更合理地利用，从而维持连接效率。根据应用需求和后端的性能特性对该值进行微调通常尤其有益。

配置示例

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_send_lowat 16384;
}

说明

`fastcgi_buffer_size` 指令指定用于从后端服务器读取 FastCGI 响应头部的缓冲区大小。当 NGINX 与 FastCGI 应用通信时，会缓冲响应头以在传输主体之前有效处理它。适当大小的缓冲区可以通过确保头部可以放入缓冲区而不需要多次读取，从而减少延迟，提升 NGINX 配置的性能。 缓冲区大小在 `http`、`server` 或 `location` 块上下文中定义，允许根据所需配置级别进行细粒度控制。它接受一个指定大小值的参数，例如 `16k` 或 `32`。如果缓冲区不足以容纳头部数据，NGINX 可能会切换到用于主体的单独缓冲区，这可能导致响应时间或资源使用增加。确保 `fastcgi_buffer_size` 与 FastCGI 应用的预期响应大小一致，对于获得最佳性能至关重要。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_buffer_size 32k;
    include fastcgi_params;
}

说明

'fastcgi_pass_request_headers' 指令用于 NGINX 配置中，用来决定是否将来自客户端请求的头部转发给 FastCGI 服务器。该指令接受一个布尔标志作为参数，允许你启用或禁用这些头部的传递。当设置为 'on' 时，NGINX 会传递来自客户端请求的所有头部，包括那些可能被中间代理或其他服务修改或添加的头部。相反，将其设置为 'off' 则表示不会向 FastCGI 服务器发送任何请求头。 有效使用此指令对于依赖某些头部才能正常工作的应用程序（例如 `HTTP_REFERER` 或 `USER_AGENT`）至关重要。不传递这些头部可能会导致期望特定请求头的 Web 应用或内容管理系统出现问题。同时，还应考虑转发某些头部的安全影响，因为这可能暴露客户端请求中的敏感信息，从而被滥用。 该指令可以在 http、server 或 location 上下文中设置，使其能够根据你的配置需求灵活应用。在将 NGINX 与 FastCGI 应用集成时，正确使用和理解此指令，特别是在性能和安全方面的影响，是关键。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_pass_request_headers on;
    include fastcgi_params;
}

说明

在 NGINX 配置中，指令 `fastcgi_pass_request_body` 用于指定是否将客户端 HTTP 请求的请求体发送到 FastCGI 服务器。该指令可接受一个标志作为参数，取值可以是 'on' 或 'off'。当设置为 'on' 时，请求体会作为请求处理的一部分被转发到后端 FastCGI 服务器。相反，当设置为 'off' 时，请求体不会被发送，等同于忽略客户端在请求体中提交的任何数据。 当请求的处理不需要来自请求体的任何输入数据时（例如 GET 请求，或在使用 FastCGI 服务器处理某些不处理输入数据的操作时），该指令尤其有用。正确使用可以在 NGINX 与 FastCGI 后端之间实现高效的数据处理和响应管理，减少不必要的数据传输。该指令通常与其他 FastCGI 指令（例如 `fastcgi_pass`）结合使用，以确保根据定义的请求上下文联系到合适的服务器。

配置示例

location /example {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_pass_request_body off;
}

说明

`fastcgi_intercept_errors` 指令通过控制 NGINX 如何处理 FastCGI 服务器返回的任何错误（例如 4xx 或 5xx HTTP 状态码）来与 FastCGI 协同工作。 当设置为 'on' 时，NGINX 会捕获这些错误响应，允许你定义自定义错误页面或执行额外处理，而不是直接将原始 FastCGI 错误响应返回给客户端。这在希望显示用户友好的错误信息或实现特定错误恢复机制的场景中特别有用。 该指令接受一个布尔标志作为参数，可以是 'on' 或 'off'。当为 'on' 时，来自 FastCGI 服务器的任何错误响应（例如状态码在 400 或 500 范围内的响应）可以由在 NGINX 配置中定义的特定错误页面配置处理。设置为 'off' 时，默认行为允许 NGINX 原样返回 FastCGI 响应，包括任何错误消息。该指令可以在 'http'、'server' 或 'location' 上下文中使用，根据所需的错误处理范围提供灵活的放置位置。

配置示例

location /app {
    fastcgi_pass backend;
    fastcgi_intercept_errors on;
    fastcgi_index index.php;
    include fastcgi_params;
}

说明

`fastcgi_read_timeout` 指令用于指定 NGINX 在发送请求后等待来自 FastCGI 服务器响应的时长。这在 FastCGI 处理可能比预期更长、且希望避免过早关闭仍可能最终返回响应的连接时非常有用。该超时对每个请求单独生效，并可以在诸如 `http`、`server` 和 `location` 块等不同上下文中指定。 该指令的参数是一个时间值，可以用秒 (s)、分钟 (m)、小时 (h) 或天 (d) 指定。如果超过超时时间且未收到响应，NGINX 将终止与 FastCGI 服务器的连接，并可能向客户端返回错误。调整 `fastcgi_read_timeout` 对于需要更长处理时间的应用（例如执行复杂数据库查询或文件操作的应用）而言，可能对性能优化至关重要。 需要注意的是，将此值设置得过低可能导致不希望的连接关闭，而设置得过高可能会使客户端在永远不会到来的响应上不必要地等待过久。因此，建议根据应用的性能特性对该值进行平衡设置。

配置示例

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_read_timeout 120s;
}

说明

`fastcgi_buffers` 指令对于配置 NGINX 如何处理来自 FastCGI 服务器的响应至关重要。它定义了 NGINX 在读取响应时使用的缓冲区数量以及每个缓冲区的大小。该指令通过管理在将数据发送到客户端之前可以一次性从 FastCGI 后端读取的数据量来优化性能和内存使用。 当你用两个参数指定 `fastcgi_buffers` 时，第一个参数表示缓冲区的数量，第二个参数指定每个缓冲区的大小。NGINX 将按指定分配总缓冲区空间，这有助于有效缓存较大的响应，从而防止过早向客户端发送部分响应。缓冲区可以容纳来自 FastCGI 服务器的完整响应大小，从而提升针对生成较大响应的应用（例如数据处理密集的 Web 应用）的性能。 还应注意，`fastcgi_buffers` 的值应根据应用可能产生的响应大小适当设置。将该值设置得过低可能导致性能下降或额外开销，因为 NGINX 可能需要比完成响应所必需的更频繁地从 FastCGI 后端读取。

配置示例

fastcgi_buffers 16 8k;

说明

在 NGINX 中，`fastcgi_busy_buffers_size` 指令定义了可用于处理响应的 FastCGI 缓冲空间的最大大小。该内存分配对于管理 FastCGI 在将来自上游服务器的数据传回客户端之前如何缓冲这些数据至关重要。当达到 `fastcgi_busy_buffers_size` 指定的大小时，NGINX 会根据配置的设置，要么开始将已缓冲的响应发送给客户端，要么以其他方式处理流量。 该指令接受一个参数，指定繁忙缓冲区的大小（以字节为单位）。如果分配的缓冲区不足，NGINX 可以配置为延迟处理或以其他方式管理数据流动，以确保响应的顺序和成功传递。该指令会影响性能，尤其是在高负载情况下，缓冲区过小可能导致响应时间下降和延迟增加，因为 NGINX 可能需要频繁地刷新缓冲区以容纳传入数据。 为获得最佳性能，在配置此指令时应考虑来自上游服务器的预期最大响应大小以及 NGINX 服务器的典型负载。配置不当可能导致性能瓶颈，因此监控和测试对于为您的具体应用找到合适的缓冲区大小至关重要。

配置示例

http {
    server {
        location /api {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_busy_buffers_size 16k;
            include fastcgi_params;
        }
    }
}

说明

`fastcgi_force_ranges` 指令在 NGINX 中用于处理发送到 FastCGI 后端的字节范围请求。默认情况下，一些 FastCGI 应用可能无法正确支持字节范围，导致对部分请求的内容传递不正确。当此指令启用（设置为 'on'）时，NGINX 将确保字节范围请求被正确解释并由 FastCGI 服务器处理，强制其在指定范围有效的情况下以 `206 Partial Content` 响应。 在实际应用中，该指令对通过 HTTP 提供视频或音频内容尤其重要，因为客户端可能会为流式播放功能请求特定的字节范围。通过指示 FastCGI 服务器确认这些字节范围请求，NGINX 提高了兼容性和内容传递效率。该指令可以全局应用，也可以在特定的 server 和 location 上下文中使用，为各种网站配置提供灵活性。 `fastcgi_force_ranges` 指令接受一个标志：可以设置为 'on' 或 'off'，其中 'off' 禁用强制响应行为。启用时，NGINX 会直接与 FastCGI 服务器交互以协商和管理字节范围，确保客户端接收它们请求的适当数据段。此行为增强了最终用户体验，尤其适用于富媒体应用。

配置示例

server {
    location /api {
        fastcgi_pass backend;
        fastcgi_force_ranges on;
    }
}

说明

'fastcgi_limit_rate' 指令用于控制分配给 FastCGI 响应的带宽，提供了一种限制 NGINX 到 FastCGI 后端发送数据速率的方法。这有助于在特定 FastCGI 应用可能产生过多流量的情况下（尤其是在高峰期）管理服务器负载并优化资源分配。设置该指令时，它指定可以发送到 FastCGI 服务器的最大每秒字节数。如果超过此速率，NGINX 将暂时暂停发送头部，并且仅在数据速率降至指定阈值以下时恢复发送。 需要注意的是，'fastcgi_limit_rate' 接受单个参数，通常以每秒字节为单位指定，也可以使用诸如 'k' 或 'm' 的后缀，分别表示千字节和兆字节，从而便于配置带宽限制。该指令可以放在 'http'、'server' 或 'location' 上下文中，灵活地根据应用或站点结构的范围应用不同的限制。管理员可以微调分配给 FastCGI 处理的带宽，以在不同条件下实现更好的性能管理。

配置示例

location /fastcgi {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_limit_rate 100k;
}

说明

`fastcgi_cache` 指令指定用于存储 FastCGI 响应的共享内存区，从而有效地缓存它们，以降低服务器负载并改善对经常请求内容的响应时间。当 FastCGI 服务器生成响应时，该响应可以根据请求参数被缓存，允许随后的相同请求从缓存中提供，而无需再次查询后端服务器生成新的响应。 该指令需要一个参数，表示使用 `fastcgi_cache_path` 指令预先定义的缓存区域的名称。它可以在诸如 `http`、`server` 和 `location` 块等各种上下文中使用，从而能够对不同位置如何处理缓存进行精细控制。结合像 `fastcgi_cache_key` 这样的相关指令，管理员可以确定什么构成唯一的缓存项，从而根据应用需求调整缓存机制的行为。 缓存行为还会受到相关指令的影响，例如 `fastcgi_cache_valid`，它定义缓存条目的有效时间；以及 `fastcgi_cache_bypass`，它允许动态控制何时绕过缓存，从而确保在必要时仍能提供已更新的数据。

配置示例

http {
    fastcgi_cache_path /tmp/cache levels=1:2 keys_zone=my_cache:10m;
    server {
        location / {
            fastcgi_pass backend;
            fastcgi_cache my_cache;
            fastcgi_cache_valid 200 1h;
        }
    }
}

说明

指令 `fastcgi_cache_key` 在确定在存储或检索缓存的 FastCGI 响应时应使用哪个唯一键方面起着关键作用。通过形成缓存键，NGINX 能够根据请求的具体信息区分不同的缓存项。该键可以由多个变量组合而成，从而使动态内容能够高效地存储和检索，确保缓存命中准确并且与正在发起的具体请求相关。 在定义缓存键时，你可以使用 NGINX 中可用的各种变量，这些变量可以表示诸如请求的 URI、请求方法或其他头信息等属性。该配置支持定制化的缓存策略，以优化性能和资源使用。该指令在 `http`、`server` 和 `location` 等上下文中有效，为 NGINX 配置的不同层级提供了灵活性。 需要注意的是，错误配置 `fastcgi_cache_key` 可能会导致缓存不匹配，从而向用户请求返回不正确的响应。因此，必须谨慎构造缓存键，以充分利用 NGINX 的缓存能力并避免出现意外行为。

配置示例

fastcgi_cache_key "$scheme$request_method$host$request_uri";

说明

`fastcgi_cache_path` 指令用于在 NGINX 中定义 FastCGI 缓存的存储配置。该指令在 `http` 块中指定，建立了缓存文件存放的路径，并包含缓存区大小、键以及其他参数的设置。它基本上创建了一个目录来保存来自 FastCGI 服务器的响应数据，通过提供缓存内容而不是每次将请求转发到后端服务器，可以显著加快响应时间。 该指令至少需要两个参数：缓存路径和缓存区配置字符串，后者通常包含缓存的名称和大小。缓存区是 NGINX 用来划分和管理缓存响应的地方。还可以包含像 `inactive` 或 `max_size` 这样的附加参数，分别用于指定项目在缓存中保留的时长或缓存的最大大小。该指令的重要性不可低估，正确配置 FastCGI 缓存能够提升性能并减少后端服务器的负载。

配置示例

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi_cache levels=1:2 keys_zone=fastcgi_cache:10m inactive=60m max_size=1g;
}

说明

`fastcgi_cache_bypass` 指令是 NGINX HTTP 模块的一部分，用于控制 FastCGI 缓存机制。配置该指令时，可指定一个或多个条件（变量或客户端请求属性），用于决定何时 NGINX 应跳过缓存的响应并从上游服务器获取新的响应。它在需要根据请求或某些条件（例如特定的头、cookie 或查询参数）确保向客户端返回最新数据而不是缓存数据的场景中尤其有用。 该指令可以在 `http`、`server` 或 `location` 上下文中设置，提供了应用范围的灵活性。通常，你会使用像 `$arg_argname` 这样的变量来引用特定的查询参数，使用 `$http_cookie` 来处理 cookie，或者使用自定义的应用专用头来构造合适的绕过条件。它可以通过在适当情况下允许返回过期数据来优化资源使用，同时在必要时确保提供最新数据。 当与其他与 FastCGI 缓存相关的指令（例如 `fastcgi_cache` 和 `fastcgi_cache_key`）组合使用时，它可以提供一种强健的缓存策略，以在提升性能的同时根据用户交互和数据敏感性保持内容的新鲜度。

配置示例

location / { 
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_bypass $http_cache_bypass;
}

说明

`fastcgi_no_cache` 指令用于告诉 NGINX 是否缓存来自 FastCGI 服务器（例如 PHP 处理器）的响应。该指令可接受一个或多个变量或条件来决定缓存策略。例如，如果某个变量的值为 true，NGINX 将不缓存响应，从而允许动态内容生成，而不会因缓存命中而导致性能问题。它与 `fastcgi_cache_bypass` 指令配合使用，以基于相似条件实现一致的缓存行为。该指令必须在 NGINX 配置文件的 `http`、`server` 或 `location` 上下文中设置，通常与缓存相关设置配合使用以获得最佳性能。在需要在特定情况下执行缓存失效的应用中它尤其有用，例如用户已登录时，或响应内容根据请求参数发生显著变化时。通过有效管理动态内容，`fastcgi_no_cache` 有助于保持应用数据的新鲜度并改善 Web 应用的用户体验。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_no_cache $http_cache_control;
}

说明

`fastcgi_cache_valid` 指令定义了缓存的 FastCGI 响应被视为有效的时间段，也就是说在此期间可以在不再次查询后端服务器的情况下直接提供该响应。该指令接受一个时间间隔以及一个特定的响应状态码或状态码范围。例如，使用 `fastcgi_cache_valid 200 10m;` 表示将 200 OK 响应缓存 10 分钟。可以为该指令定义多行，以为不同的状态码指定不同的有效期。 需要注意的是，该指令应放在合适的上下文中，例如 http、server 或 location 块，并与 `fastcgi_cache` 指令配合使用。当提供有效缓存时，可以使用 `fastcgi_cache_bypass` 指令有条件地绕过缓存。这在需要时能灵活保证内容的新鲜度，同时在重复请求时仍能受益于缓存。

配置示例

fastcgi_cache my_cache;
fastcgi_cache_valid 200 10m;
fastcgi_cache_valid 404 1m;

说明

`fastcgi_cache_min_uses` 指令指定在缓存某个 URI 的响应之前，需要对该 URI 发起的相同请求的最小次数。 这对于避免为低流量端点缓存响应特别有用，从而确保只有常被访问的内容才被存储到缓存中。 该指令的值应为正整数，因为它表示在考虑缓存响应之前，同一资源的请求必须被接收多少次。 当针对特定 URI 的请求次数达到或超过 `fastcgi_cache_min_uses` 所定义的数量时，该响应会触发缓存机制。这有助于优化缓存机制，防止不常见或不相关的响应占用缓存空间。该指令可以在 `http`、`server` 或 `location` 上下文中设置，根据应用需求实现细粒度控制。 通过减少来自很少访问的 URI 的潜在缓存污染，可以提高应用程序的性能以及缓存存储的效率。这在涉及动态内容的场景中尤其有用，因为某些响应不应被缓存，除非它们被频繁请求。

配置示例

http {
    fastcgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m;
    server {
        location /api {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_cache my_cache;
            fastcgi_cache_min_uses 5;
        }
    }
}

说明

`fastcgi_cache_max_range_offset` 指令定义了当客户端对由 FastCGI 缓存提供的资源发起范围请求时，作为偏移量可以指定的最大字节数。该指令有助于优化缓存行为和对部分下载资源的响应，确保当客户端仅请求文件的特定部分时，服务器不会过度提供过时或过多的数据。 将此指令设置为数值可以让您控制对缓存内容的范围请求响应的粒度。如果偏移量超过指定值，NGINX 可能会选择拒绝该范围请求或根据 FastCGI 模块的实现和现有的缓存策略对其进行不同处理。在需要尽量减少带宽使用的场景中，或在处理经常按部分访问的大文件时，这一点尤其有用，可提供更高效的响应。 此指令可以在 NGINX 配置文件的多个上下文中使用，包括 http、server 和 location 块，从而在不同的使用场景和服务器配置中具有灵活性。

配置示例

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi_temp levels=1:2 keys_zone=my_cache:10m;
    server {
        location / {
            fastcgi_pass backend;
            fastcgi_cache my_cache;
            fastcgi_cache_max_range_offset 1048576;  # 1 MB
        }
    }
}

说明

`fastcgi_cache_use_stale` 指令允许 NGINX 在特定条件下提供过期的缓存响应，通过在服务器出现问题时减少停机或延迟来改善用户体验和性能。你可以为多种情形启用此指令，包括 'error'、'timeout'、'invalid_header' 或 'updating'。当请求遇到这些问题时，NGINX 可以不返回错误，而是提供最近一次成功缓存的响应。这种行为对于需要在后端服务出现临时问题时仍维持用户参与度的高可用部署尤其有用。 该指令可以在多个上下文中指定：`http`、`server` 和 `location`，因此在不同配置中很灵活。你提供的每个参数都必须指定在何种情形下应返回过期数据。如果指定了多个条件，只要满足其中任何一个条件就会返回过期内容。该指令与 `fastcgi_cache` 指令配合工作，有效增强了缓存机制的鲁棒性，从而减轻上游中断或响应缓慢对客户端体验的影响。

配置示例

location /api {
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_use_stale error timeout;
}

说明

fastcgi_cache_methods 指令在 NGINX 配置中用于指定在使用 FastCGI 时应缓存哪些 HTTP 方法（例如 GET 或 POST）。默认情况下，NGINX 仅缓存对 GET 请求的响应，这适用于不经常变化并可以直接从缓存提供的页面。然而，在某些场景中，应用可能会对 POST 请求做出可受益于缓存的响应，以提高性能并减轻后端服务器负载。该指令允许管理员根据应用需求自定义缓存行为。 该指令接受一个或多个 HTTP 方法作为参数。例如，指定 "GET POST" 允许同时缓存 GET 和 POST 请求。必须考虑请求的性质及其关联的响应；并非所有 POST 请求都应被缓存，因为它们通常涉及状态更改。对这类请求的不当缓存可能导致应用行为不正确或向用户提供过时的内容。 在实现该指令时，可以将其放在 http、server 或 location 上下文中，从而根据所需控制的粒度实现灵活的缓存配置。如果指定的方法与应用的预期行为不一致，可能会无意中导致性能瓶颈或缓存失效的情况。

配置示例

location ~ \.php$ {
    fastcgi_pass   backend;
    fastcgi_cache  my_cache;
    fastcgi_cache_methods GET POST;
}

说明

'fastcgi_cache_lock' 指令可用于防止多个请求并发生成相同的 FastCGI 响应。启用时，如果对同一已缓存资源发起两个或更多请求，只有第一个请求会继续生成 upstream 响应。后续请求将被排队，直到响应生成并缓存，从而使它们能够使用缓存的响应，而不是触发多个 upstream 请求。 本指令接受一个标志（'on' 或 'off'）。设置为 'on' 时，NGINX 将应用锁定机制，允许仅有一个请求生成响应，其余请求则等待。设置为 'off' 则禁用此行为，对于同一资源的所有请求都可能同时生成新的 upstream 请求，这可能在高流量环境中导致负载增加和性能问题。 需要注意的是，在可能发生缓存风暴的场景中使用 'fastcgi_cache_lock' 可以提高效率，但应结合合适的缓存策略，以确保在最大化缓存使用的同时保持性能最佳。

配置示例

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_cache my_cache;
    fastcgi_cache_lock on;
    fastcgi_cache_key "$scheme$request_method$host$request_uri";
}

说明

`fastcgi_cache_lock_timeout` 指令配置了当另一个请求正在处理该缓存条目时，请求在尝试获取 FastCGI 缓存锁时将等待的持续时间。这在请求在尝试存储相同缓存内容时可能发生冲突的场景中特别有用。如果在获取锁之前超时到期，锁请求将失败，从而避免并发请求可能出现的长时间等待，并允许它们继续执行而不会无限期阻塞。 此指令可帮助提高应用的响应时间，尤其是在高负载时。通过设置 `fastcgi_cache_lock_timeout`，您可以精确控制一个请求等待另一个请求的允许时间，降低延迟并在高峰流量期间改善整体用户体验。它必须在适当的上下文中设置，例如 `http`、`server` 或 `location`，并接受一个指定超时时长的单个参数。 当配置的超时达到时，任何后续请求可能会收到替代响应，或根据应用的内部处理逻辑以不同方式被处理。因此，在决定此指令的值时应谨慎，以在锁定行为与整体性能之间取得平衡。

配置示例

location /api {
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_lock on;
    fastcgi_cache_lock_timeout 10s;
}

说明

NGINX HTTP 模块中的 `fastcgi_cache_lock_age` 指令定义了在缓存已被另一个请求锁定时，请求应等待 `FastCGI` 缓存锁可用的最长秒数。当对同一资源发起多个请求，并且由于另一个请求正在处理相同内容导致缓存被锁定时，该指令可以防止请求无限期挂起。相反，指定的等待时长（由此指令设定）允许请求在一定时间后重试。这有助于优化用户的响应时间，并通过避免过度等待来提高整体服务器性能。 `fastcgi_cache_lock_age` 的参数以秒为单位，并接受整数值。例如，如果该指令设置为 10，任何遇到缓存锁的请求将在放弃获取锁并发起新的请求之前最多等待 10 秒。设置过高会导致响应延迟，而设置过低可能导致不必要的缓存未命中。管理员应根据应用的预期缓存访问模式和对终端用户可接受的延迟来平衡 `fastcgi_cache_lock_age` 参数。

配置示例

location /app {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_cache my_cache;
    fastcgi_cache_lock on;
    fastcgi_cache_lock_age 10;
}

说明

'fastcgi_cache_revalidate' 指令在 NGINX 中允许对来自 FastCGI 后端的缓存响应的重新验证进行更细粒度的控制。当该指令设置为 'on' 时，NGINX 将基于缓存内容使用 'If-Modified-Since' 或 'If-None-Match' 头发出有条件请求。这样可以确保当后端内容发生变化时，会相应地将更新后的响应返回给客户端。该行为有助于在减少不必要的后端请求的同时保持缓存内容的新鲜度，从而在动态内容不经常变化的环境中提升性能。 相比之下，当设置为 'off' 时，NGINX 将在不查询后端更新的情况下提供缓存响应，这可能导致在底层数据发生变化时提供过时的内容。该指令在处理更新频率不可预测的内容时特别有用，因为它在提供缓存内容与确保用户接收最新响应版本之间取得了平衡，同时不丧失缓存带来的效率优势。

配置示例

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi_tmp levels=1:2 keys_zone=my_cache:10m;

    server {
        location /fastcgi {
            include fastcgi_params;
            fastcgi_pass backend;
            fastcgi_cache my_cache;
            fastcgi_cache_revalidate on;
        }
    }
}

说明

指令 `fastcgi_cache_background_update` 是一个布尔标志，用于控制当访问的内容已过期时，NGINX 是否在后台更新缓存的 FastCGI 内容。当设置为 `on` 时，它允许在发起新请求以获取更新内容的同时并行提供现有的缓存响应，这在高流量情况下尤其有用，因为等待缓存刷新可能导致延迟和更长的加载时间。这意味着用户将继续接收缓存版本，而耗时的后端请求将在后台处理。 相反，如果该指令设置为 `off`（默认值），请求过期缓存响应的用户将不得不等待发起新的请求来获取更新版本，从而产生额外的延迟。这在用户体验和资源利用方面效率较低。该指令可以应用于 `http`、`server` 或 `location` 上下文，从而根据应用或特定路由的需求灵活控制缓存行为。 正确设置此指令可大幅提升严重依赖 FastCGI 缓存的 Web 应用的响应性和速度，因为它能最小化缓存内容更新时的负载和等待时间。然而，必须谨慎处理缓存失效，以防长时间提供过期内容，尤其是在数据频繁变化的动态应用中。

配置示例

location /api {
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_background_update on;
}

说明

`fastcgi_temp_path` 指令定义了 NGINX 在 FastCGI 处理过程中存放临时文件的路径。这对处理大响应或 FastCGI 输出被缓冲的情况尤其有用。指定的路径必须对 NGINX 工作进程可写。你可以指定最多四个用空白字符分隔的目录路径；NGINX 会使用第一个可用目录来存放临时文件，这样可以在需要时将负载分散到多块磁盘上。 当处理 FastCGI 请求且响应超过某些缓冲限制时，NGINX 会将数据写入指定的临时文件，直到整个响应处理完毕再发送给客户端。这样可以让 NGINX 有效管理内存使用，从而提高整体性能并避免因内存消耗过大而导致的失败。可能需要事先创建目录结构，并设置适当的权限以避免访问问题。

配置示例

fastcgi_temp_path /var/tmp/nginx/fastcgi_temp;

说明

指令 'fastcgi_max_temp_file_size' 指定由 NGINX 为缓冲 FastCGI 响应数据而创建的临时文件允许达到的最大尺寸。如果响应的大小超过此限制，NGINX 将返回 502 Bad Gateway 错误并拒绝该请求。此设置对于管理服务器资源尤其有用，可防止过大的 FastCGI 响应耗尽所有可用磁盘空间。 该指令可应用于多个上下文，包括 'http'、'server' 和 'location'，根据使用情况提供灵活的配置。其值以字节为单位定义，应根据预期的 FastCGI 响应量谨慎设置。过小的值可能导致错误率上升，而过大的值则可能在高负载时导致磁盘使用过多。 在应用此指令时，需要考虑应用的工作负载特性和可用磁盘空间。随着响应大小随时间或用户负载模式变化，可能需要监控并调整此配置，以确保应用在意外流量激增时仍能保持性能和弹性。

配置示例

location /cgi-bin {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_max_temp_file_size 16m;
}

说明

`fastcgi_temp_file_write_size` 指令在 NGINX 中用于定义 FastCGI 模块在处理请求时可以写入的临时文件的最大大小。该指令在处理大响应时尤其有用，因为它有助于有效地管理内存和磁盘使用，降低服务器过载的风险。通过设置此指令，管理员可以根据预期的 FastCGI 响应大小增大或减小允许的尺寸。 该指令接受单个参数，即一个大小值（字节）。如果响应的大小超过指定的限制，响应将被写入临时文件而不是直接写入内存。这样可缓解内存使用峰值，并在必要时通过利用磁盘空间让服务器更高效地处理更多请求。 该指令可以在任何上下文中设置：http, server, 或 location，使其在各种配置中都很灵活。然而，在配置此指令时必须考虑可用磁盘空间以及写入磁盘对性能的影响。应根据应用的正常负载和 FastCGI 响应的特性选择适当的值。

配置示例

http {
    fastcgi_temp_file_write_size 16k;
}

说明

'fastcgi_next_upstream' 指令允许你指定在何种条件下，对 FastCGI 服务器的请求应在配置的 upstream 组中重试到后续服务器。该指令可以接受一个或多个参数，这些参数对应特定情形，例如超时、非 2xx 响应和连接错误。启用此指令后，NGINX 可以通过尝试使用备用服务器处理请求来更优雅地处理潜在的服务器错误，从而提高 Web 应用的弹性和可靠性。 例如，典型的使用场景是部署多个用于 PHP 处理的 FastCGI 服务器。通过在配置中包含带有 'error' 和 'timeout' 等参数的 'fastcgi_next_upstream' 指令，如果原始服务器发生错误或在一定时间内未响应，NGINX 将尝试将失败的请求重发到另一个已配置的 FastCGI 服务器。在需要维持高可用性的重要的负载均衡环境中，此功能特别有用。 完整的参数集合包括诸如 'error'、'timeout'、'invalid_header'、'http_500' 等选项，允许对哪些错误条件应触发重试进行精细控制。基于错误的重试功能有助于缓解单个服务器故障相关的问题，保持无缝的用户体验并提供高可用性。然而，应谨慎配置此指令，以避免在错误情况下造成额外的开销。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_next_upstream error timeout invalid_header;
    include fastcgi_params;
}

说明

指令 `fastcgi_next_upstream_tries` 指定在 FastCGI 请求不成功时应尝试的上游服务器数量。通过设置此指令，NGINX 可以在后端 FastCGI 服务器之间实现负载均衡：如果初始服务器失败，则尝试在指定数量的其他服务器上重试请求。在对高可用性有严格要求的场景中，这尤其有用，可确保即使一个或多个上游服务器宕机，应用仍能继续运行。 在指定该指令的值时，可以在 http、server 或 location 上下文中定义，从而根据不同的应用需求进行细粒度调整。例如，可以在更容易发生失败的 location 中设置较高的值，而在更稳定的区域保持较低的值。所指定的值必须是正整数，如果设置为 0，则实际上禁用该功能，这意味着 NGINX 不会尝试在其他上游服务器上重试。 值得注意的是，该指令会与其他与 FastCGI 相关的指令交互，尤其是 `fastcgi_next_upstream`，后者决定何种情况下会发生重试。将两者结合使用可以全面控制 NGINX 如何处理后端故障和故障转移。

配置示例

location /api {
    fastcgi_pass backend;
    fastcgi_next_upstream_tries 3;
}

说明

`fastcgi_next_upstream_timeout` 指令定义了在初始请求失败时对后续 FastCGI 请求的超时时间。该指令允许精细控制在首次尝试失败后服务器在放弃 FastCGI 上游之前将等待多长时间。 在对响应时间要求严格、且服务器可能会将请求重试到不同后端以获取更快响应的应用场景中，指定该超时非常关键。该超时可以在不同上下文中设置，包括 http、server 和 location 块，从而根据配置需求提供灵活性。 该指令接受一个时间值作为参数，通常以秒为单位。如果在指定超时时间内未从上游 FastCGI 服务器收到响应，NGINX 将中止该请求并以相同方式处理下一个上游。这种行为保证服务器保持响应性并能够优雅地处理来自 FastCGI 应用的失败。开发者有时可能需要根据应用性能和必要的故障切换策略调整此超时，以确保更高的可用性和更低的请求延迟。

配置示例

location /api {
    fastcgi_pass backend;
    fastcgi_next_upstream_timeout 10s;
    include fastcgi_params;
}

说明

在 NGINX 配置中使用 `fastcgi_param` 指令来设置传递给 FastCGI 服务器的环境变量。默认情况下，它可在诸如 `http`、`server` 和 `location` 等上下文中使用，从而允许针对不同应用路由灵活配置 FastCGI 行为。该指令接受两个或三个参数：第一个参数为变量名，第二个为其值，可选的第三个参数用于指定该值是否应从请求头中获取。 当使用 `fastcgi_param` 指令时，它本质上是传达与 FastCGI 请求处理相关的信息。例如，可以设置像 `SCRIPT_FILENAME` 这样的参数，用于指示要在 FastCGI 服务器上执行的脚本。该指令可确保必要的变量可供 FastCGI 应用使用，以正确响应用户的请求。当需要明确指定某些变量应如何被 FastCGI 应用的逻辑处理时，它尤其有用。 值得注意的是，`fastcgi_param` 会覆盖配置中已设置的同名参数，这使得可以对传递给 FastCGI 处理器的环境进行精细控制，从而避免变量值冲突或产生意外行为。

配置示例

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

说明

'fastcgi_pass_header' 指令允许您定义应包含在发送给客户端的响应中的、从 FastCGI 服务器接收到的哪些 HTTP 头部。该指令可以在同一上下文中多次指定，从而允许传递多个头部。当处理请求且 FastCGI 服务器返回头部时，NGINX 会根据 'fastcgi_pass_header' 提供的配置筛选这些头部。只有与该指令中指定的头部匹配的头部会被包含在最终发回客户端的输出中，所有其他头部将被忽略。这对于控制哪些元数据或指令被传回客户端特别有用，可以提高安全性或仅关注相关数据。 'fastcgi_pass_header' 指令可以在 'http'、'server' 和 'location' 上下文中定义，使其在各种配置中具有灵活性。通过使用此指令，管理员可以确保敏感头部不会被暴露，或防止无关头部使响应杂乱。需要注意的是，该指令与 FastCGI 配置配合使用，并且需要 'fastcgi_pass' 指令将流量定向到 FastCGI 服务器。 配置的一个重要方面是要理解头部名称不区分大小写，但其值是否区分大小写可能取决于应用程序。因此，在定义要传递的头部时，应确保值的拼写和大小写保持一致，以确保正确的运行完整性。

配置示例

location /some_location {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_pass_header X-My-Custom-Header;
}

说明

'fastcgi_hide_header' 指令在 NGINX 配置中用于指定哪些来自 FastCGI 服务器响应的头不应发送给客户端。该指令可以因为安全或运行方面的原因阻止特定头被暴露，从而通过对客户端隐藏不必要或敏感的信息来帮助保持清晰的接口。它接受一个参数，即你希望隐藏的 HTTP 头的名称。例如，指定 'fastcgi_hide_header X-Powered-By;' 会阻止 'X-Powered-By' 头返回给客户端，即使 FastCGI 应用在其响应中包含该头。 该指令可以放在包括 'http'、'server' 和 'location' 在内的多个上下文中，使其在配置上具有灵活性，取决于你想在哪里应用头抑制。当在 FastCGI 响应中出现指定的头时，NGINX 将在最终发送给客户端的 HTTP 响应中不包含该头，从而避免暴露可能敏感的信息。当处理会泄露可用于指纹识别攻击的信息的应用程序，或在考虑特定安全需求的配置时，此功能尤其有用。

配置示例

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_hide_header X-Powered-By;
}

说明

`fastcgi_ignore_headers` 指令用于指定在 NGINX 处理响应时应忽略哪些来自 FastCGI 响应的头。默认情况下，NGINX 会将所有 FastCGI 响应头传回给客户端。但在某些情况下，您可能希望抑制某些头，以防止它们被发送到客户端，例如某些与安全相关的头或修改缓存行为的头。 该指令接受一个或多个头名称作为参数。当 FastCGI 响应中存在在此指令中指定的头时，NGINX 将完全忽略该头并不转发给客户端。这在保护应用程序安全以及在不修改上游应用行为的情况下管理某些响应的处理方式时特别有用。例如，忽略 `X-Powered-By` 可以帮助避免暴露正在使用的服务器技术。 `fastcgi_ignore_headers` 指令可以在 `http`、`server` 和 `location` 上下文中使用，允许在不同配置中灵活应用。您可以指定任意组合的要忽略的头，从而对向客户端暴露的信息进行细粒度控制。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_ignore_headers X-Powered-By;
    include fastcgi_params;
}

说明

'fastcgi_catch_stderr' 指令在 'http'、'server' 和 'location' 等上下文中使用，用于管理由 FastCGI 应用程序产生的错误消息的处理。启用时，任何由 FastCGI 应用程序发送到标准错误的消息都会被 NGINX 捕获并记录，从而便于调试，并通过 NGINX 错误日志直接查看应用问题的情况。默认情况下，该指令设置为 off，这意味着除非显式开启，否则 NGINX 只捕获标准输出。 该指令接受一个参数：'on' 或 'off'。将其设置为 'on' 后，开发者可以获得有价值的错误信息，这些信息对于诊断 FastCGI 应用程序的问题（尤其是在生产环境中）可能至关重要，因为查看这些日志可预先指出代码执行中的潜在错误。需要注意的是，如果应用产生大量错误输出，过多的日志记录可能会导致性能下降，因此建议谨慎管理日志级别。 正确使用 'fastcgi_catch_stderr' 可以通过 NGINX 将错误日志集中化，从而提高 FastCGI 应用的可维护性，并为开发者提供对可能在其他地方看不到的运行时错误的清晰洞察。然而，在使用此指令时，应权衡在高流量条件下提高日志详细程度对性能的影响。

配置示例

location /api {
    fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_index index.php;
    fastcgi_catch_stderr on;
}

说明

NGINX 中的 `fastcgi_keep_conn` 指令，可在 http、server 和 location 上下文中使用，是一个标志，用于决定在请求完成后是否在 NGINX 与 FastCGI 服务器之间维持持久连接。默认情况下，请求处理完毕后与 FastCGI 服务器的连接会被关闭。但是，将该指令设置为 'on' 会在后续请求中保持连接打开，从而降低后续请求的延迟，并可能在多个请求发送到同一 FastCGI 服务器的高流量环境中提高性能。 启用 `fastcgi_keep_conn` 后，连接会被重用，而不是不断地打开和关闭，这可以节约资源并提升吞吐量。它对在连续多个请求很常见的托管场景（如 PHP 或类似技术的动态内容生成）特别有用。然而，保持连接打开会占用服务器资源，因此应根据应用的行为和服务器的整体负载能力谨慎使用。

配置示例

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_keep_conn on;
}

说明

`flv` 指令在 NGINX 配置的 location block 中使用，用于指定在提供内容时是否处理 FLV (Flash Video) 文件。启用后，NGINX 会配置自身以正确处理对 FLV 文件的请求，使视频能够以 FLV 播放器期望的正确头部和行为进行流式传输。该指令不接受任何参数；只需包含它即可在该上下文中启用 FLV 处理功能。NGINX 源代码中的实现确保对 FLV 文件应用特定的响应头和缓冲规则，以便提供流畅的流式传输体验。 该指令可以放在希望提供 FLV 内容的 location block 中。如果在没有具体 location 的 server block 中使用该指令，则会被忽略，除非已明确定义了用于 FLV 文件的 location。在以正确的 MIME type 提供文件时，使用 `flv` 指令可确保 NGINX 适当地处理请求并优化以获得更好的流式传输性能。需要注意的是，该指令在很大程度上已被弃用，因为 Flash 的使用量已显著减少，现代替代方案更适合用于视频流式传输。

配置示例

location /videos {
    flv;
    root /var/www/videos;
}

说明

`geo` 指令用于创建将客户端 IP 地址映射到变量的映射表，这些变量可在各种 NGINX 配置中使用。它在根据地理位置配置访问控制和管理请求路由时尤其有用。该指令可以定义 IPv4 和 IPv6 地址，并且可以嵌套在 `http` 上下文中。每条映射规则由一个地址（或地址范围）和一个可选变量组成，该变量可以包含一个值（例如用于允许或拒绝访问的 '1' 或 '0'），或者对于不匹配的地址设置为 'default'。 在 `geo` 块内，您可以指定单个 IP 地址、CIDR 表示法或地理范围。NGINX 将按照规则定义的顺序将客户端的 IP 地址与这些规则进行匹配。如果找到匹配项，NGINX 将相应地设置指定的变量。如果没有任何规则匹配某个地址，则会应用 `default` 指令设置的值。这使得 `geo` 成为创建基于不同客户端 IP 响应的动态配置（无论是用于负载均衡、访问控制还是应用配置）的强大工具。 需要注意的是，`geo` 指令必须在 `http` 块中定义，并且它不会在自身内部直接接受其他相关指令，这在复杂的 NGINX 配置中可能导致混淆。此外，该指令在 HTTP 层运行，并在根本上依赖于传入请求的网络细节，因此需要根据客户端请求的预期特征正确使用。

配置示例

geo $remote_addr {
    default 0;
    192.168.1.0/24 1;
    10.0.0.0/8 2;
}

说明

`geoip_country` 指令允许您将 NGINX 指向用于基于客户端 IP 地址执行地理定位的 GeoIP 数据库。配置后，NGINX 可以为请求分配地理信息，例如来源国家/地区。此信息随后可用于访问控制或内容定制，确保服务器能够根据用户的地理位置调整其响应。 该指令接受一个或两个参数：GeoIP 数据库文件的路径和可选的 'country' 选项。如果提供，则可启用或禁用特定的国家查找功能，或更改有关数据库使用的行为。当组织需要执行基于区域的策略、投放定向广告或提供本地化内容时，此功能至关重要，因为它有助于准确识别传入请求的来源位置。 通过与 GeoIP 模块集成，它使服务器能够动态识别用户的国家/地区，从而允许将规则绑定到特定的地理位置。注意：这需要一个外部数据库，必须定期更新以保持地理定位映射的准确性。

配置示例

geoip_country /path/to/geoip.dat;

说明

`geoip_org` 指令是 NGINX HTTP Core 模块的一部分，通过使用 GeoIP 数据来确定与给定 IP 地址关联的组织，从而便于实现访问控制。通过利用 GeoIP 数据库，NGINX 可以根据发出请求的客户端的组织身份动态允许或限制访问。该指令使服务器能够根据 GeoIP 派生的组织信息采取相应措施，允许管理员基于发出请求的实体实施自定义路由、日志记录或访问策略。 该指令可以接受一个到两个参数：要么是表示 GeoIP 数据库名称的单个字符串，要么是用于与传入请求匹配的特定组织名称。这些参数的存在允许灵活配置，管理员可以根据 IP 地址所暗示的组织条件自定义流量处理方式。如果仅提供组织名称，NGINX 将在其内部 Lookup 中使用该名称来识别连接；而可选的 DB 路径参数则便于关联自定义或第三方 GeoIP 数据库。 总体而言，`geoip_org` 通过利用 GeoIP 技术将请求与组织数据关联，在增强 NGINX 的访问控制能力方面发挥关键作用，使流量管理决策更加有依据。

配置示例

geoip_org /path/to/geoip/db GeoIP Org Name;

说明

`geoip_city` 指令旨在通过访问 GeoIP 数据库来增强 NGINX HTTP 服务器基于客户端 IP 地址作出地理判断的能力。通过指定 GeoIP 城市数据库的路径，该指令使 NGINX 能够根据传入请求的地理位置确定并设置变量。 当在 `http` 上下文中使用 `geoip_city` 指令时，它接受一个或两个参数：GeoIP 城市数据库文件的路径，以及可选的第二个参数，用于指定处理格式错误 IP 地址的标志。该指令处理传入请求，将客户端的 IP 与指定 GeoIP 数据库中的条目匹配，并使城市级别的地理数据（如城市名、区域和国家）可在配置中使用。然后，这些地理信息可以用于访问控制规则、日志文件格式化，甚至用于内容个性化。 此指令通常对需要基于用户地理位置进行定向内容投放的应用有益，例如本地化广告或遵守当地法规。重要的是确保 GeoIP 数据库文件保持更新，因为 IP 与位置的映射可能经常变化。错误或过时的数据可能因地理定位粒度不准确而导致糟糕的用户体验。

配置示例

http {
    geoip_city /usr/share/GeoIP/GeoIPCity.dat;
    server {
        location / {
            if ($geoip_city) {
                add_header X-City $geoip_city;
            }
        }
    }
}

说明

`geoip_proxy` 指令为 NGINX 提供了一种利用 proxy protocol 获取客户端原始 IP 地址的方法，从而通过 GeoIP 数据库提高地理定位的准确性。尤其在请求从一个代理服务器转发到另一个代理服务器的环境中非常有用，因为请求中的地址可能无法准确反映客户端的实际地理位置。配置后，NGINX 会从指定的头部读取客户端的原始 IP 地址，而不是直接从客户端连接中读取。 该指令接受一个参数，指定要查找的头部名称，通常包含客户端的原始地址（例如 `X-Real-IP`）。在使用此指令时，必须确保上游代理正确填充该头部并提供有效的 IP，以便进行准确的 GeoIP 查询。配置不当可能导致在日志记录或访问控制时记录不正确的地理数据。 此指令在 HTTP 上下文中生效，允许它在 server 块之间全局适用或在特定 location 块中使用。对头部的正确评估在收到请求时执行，因此在部署中需要在任何中间代理之间保持一致的配置。

配置示例

http {
    geoip_proxy X-Forwarded-For;
}

说明

在 NGINX 的 `http` 上下文中使用 `geoip_proxy_recursive` 指令来控制启用 GeoIP 的代理请求的行为。当设置为 'on' 时，该指令允许模块对客户端的地理信息执行递归查找。这在客户端通过多个代理连接的场景中特别有用，可在确定地理位置时保留原始客户端的 IP 地址。该指令确保 GeoIP 模块从客户端的真实 IP（而不是最后一个代理的 IP）获取数据。 当启用该指令时，NGINX 会检查诸如 `X-Forwarded-For` 或 `X-Real-IP` 之类的头以检索真实的客户端 IP 地址。如果这些头包含多个地址，NGINX 会遍历它们以查找始发 IP 地址，从而为 GeoIP 查找提供准确的位置数据。该功能对需要基于地理位置提供目标内容或实施基于地理位置的安全措施的应用至关重要。 该指令被解释为一个标志，意味着它具有二元状态。要么激活（设置为 'on'），要么不激活（设置为 'off'）。其行为与 NGINX 在开启或禁用指令之间切换的整体设计一致，根据环境配置的具体需求提供灵活性。

配置示例

http {
    geoip_proxy_recursive on;
    geoip_country /path/to/GeoIP.dat;
}

说明

`grpc_pass` 指令专门用于在 NGINX 内路由 gRPC 请求。它定义了一个后端服务器，gRPC 请求会被转发到该服务器。该指令以 URL 作为参数，该 URL 可以指定由 `upstream` 指令定义的上游服务器组或直接的服务器地址。当 NGINX 收到 gRPC 请求时，它会将该请求转换为适当的格式并转发到指定的后端，同时处理 gRPC 通信所需的二进制协议。 在 NGINX 配置的上下文中，`grpc_pass` 指令用于 `location` 块，使其在定义应映射到特定后端服务的 URI 区段时至关重要。响应头的正确处理、连接管理以及二进制的编码/解码机制由 NGINX 自动管理，开发者可以专注于应用逻辑而不是 gRPC 通信的细节。重要的是要确保上游服务器支持 gRPC 并已适当配置以处理从 NGINX 转发的请求。 因为 gRPC 使用 HTTP/2，`grpc_pass` 指令本质上要求 NGINX 的构建包含对 HTTP/2 的支持。这意味着服务器需要适当配置以监听 HTTP/2 连接，当与 `grpc_pass` 配合使用时，将能实现对 gRPC 流量的完整支持。

配置示例

location /gRPC {
    grpc_pass grpc://localhost:50051;
}

说明

`grpc_bind` 指令在 NGINX 中用于定义服务器将绑定以处理 gRPC 请求的本地地址和端口。该指令可以在 `http`、`server` 和 `location` 上下文中设置，允许根据流量路由需求进行灵活配置。它接受一个或两个参数；第一个参数是地址（IPv4 或 IPv6），第二个参数是可选的端口号。如果不指定端口，则默认使用 gRPC 的标准端口（通常为 50051）。 配置 `grpc_bind` 指令后，NGINX 会在指定的地址和端口上监听传入的 gRPC 请求，并将它们转发到配置中定义的上游 gRPC 服务器。这样，应用可以高效处理 gRPC 流量，利用 NGINX 作为反向代理来管理连接、负载均衡以及其他功能，例如限流或身份验证。应注意确保所指定的地址和端口未被占用，以避免绑定冲突，从而导致服务中断。

配置示例

grpc_bind 0.0.0.0 50051;

说明

`grpc_socket_keepalive` 指令用于启用或禁用 NGINX 处理的 gRPC 连接的 TCP keepalive 功能。当启用时，该指令通过定期发送 keepalive 探测包来确保空闲的 TCP 连接保持活跃。这对于维护长连接至关重要，gRPC 在服务间通信中通常使用长连接。默认情况下，许多操作系统可能未启用 TCP keepalive，这可能导致连接在长时间空闲后被关闭并中断通信。 该指令接受一个标志值，即可以设置为 'on'（启用）或 'off'（禁用）。当设置为 'on' 时，NGINX 会为套接字配置 keepalive 相关选项，使其根据系统中定义的设置（例如 `tcp_keepalive_time`、`tcp_keepalive_intvl` 和 `tcp_keepalive_probes` 选项）发送 keepalive 包。因此，亦需在系统级别调整这些参数以确保 keepalive 按预期工作。请注意，在没有适当服务器设置的情况下启用此功能可能会导致性能问题或不必要的网络流量，尤其是在高规模环境中。

配置示例

server {
    listen 80;
    grpc_socket_keepalive on;
    location /myservice {
        grpc_pass grpc://backend;
    }
}

说明

`grpc_connect_timeout` 指令指定用于与 gRPC 后端服务器建立连接的最大允许时间，单位为毫秒。此超时对于确保长时间或无响应的连接不会在很长时间内延迟客户端请求的处理非常重要。当在成功建立连接之前达到超时时间时，NGINX 将中止连接尝试并向客户端返回错误，从而使您的应用能够优雅地处理连接失败。 该指令可以放在 `http`、`server` 或 `location` 上下文中，允许管理员根据应用架构的具体要求定义连接超时。超时时间可以设置为任意正整数；如果设置为 0，则会完全禁用超时功能，但在对客户端响应性要求较高的生产环境中通常不推荐这样做。将 `grpc_connect_timeout` 最有效地用于在连接延迟与应用性能之间取得平衡，以便在后端服务无响应时快速重试或启用替代故障转移。

配置示例

http {
    server {
        location / {
            grpc_pass grpc://backend;
            grpc_connect_timeout 500ms;
        }
    }
}

说明

`grpc_send_timeout` 指令在 NGINX 中设置服务器在处理完请求后向客户端发送 gRPC 响应的最长时间限制。该指令对确保客户端应用不会无限等待响应非常重要，有助于管理资源并维护应用性能。该指令可在不同上下文中使用，例如 `http`、`server` 和 `location`，允许你根据应用的具体需求设置不同的超时值。 当定义的超时时间到期时，NGINX 会终止连接并生成表示超时错误的 gRPC 状态码。在微服务众多的环境中，这尤其有用，因为快速失败响应通常比对严重延迟的服务无限期等待更可取。所指定的超时仅用于服务器开始向客户端发送响应之后的发送过程，这意味着它不影响请求本身的处理时间，只影响发送最终响应数据包的时间间隔。 该指令的语法为 `grpc_send_timeout time;`，其中 `time` 可以用多种格式指定，例如 `30s`（三十秒）或 `1m`（一分钟）等。选择超时时间时需在给予响应足够时间和防止无响应服务阻碍整体功能之间取得平衡。

配置示例

location /api {
    grpc_pass grpc://backend_service;
    grpc_send_timeout 30s;
}

说明

NGINX 中的 `grpc_intercept_errors` 指令允许您管理 gRPC 服务如何处理错误。启用时，NGINX 会捕获 gRPC 的错误响应，并根据配置中定义的行为将其替换为自定义响应。这对于提供更友好的错误信息或统一发送给客户端的错误响应格式尤其有用。 该指令接受一个布尔参数，取值为 'on' 或 'off'。当设置为 'on' 时，NGINX 会拦截来自上游 gRPC 服务的错误，并允许进一步配置以定义如何在返回给客户端之前处理或转换这些错误。例如，您可以记录该错误或将某些错误代码映射为更具描述性的消息。如果设置为 'off'，NGINX 将直接传递后端 gRPC 服务的错误代码和消息，不进行任何拦截或修改。 该指令可用于多种上下文，包括 `http`、`server` 和 `location`，这允许针对每个位置或每个服务器进行细粒度控制，从而在应用的不同部分根据需要采用不同的错误处理策略。

配置示例

http {
    server {
        location /some-grpc-service {
            grpc_pass grpc://backend_service;
            grpc_intercept_errors on;
        }
    }
}

说明

grpc_buffer_size 指令对于优化通过 NGINX 提供的 gRPC 应用的性能至关重要。当 NGINX 作为 gRPC 的反向代理时，它需要高效地从上游服务器读取响应。该指令决定用于读取这些响应的缓冲区大小，从而可以控制内存使用和吞吐量。较大的缓冲区可以容纳更大的响应但可能占用更多内存，而较小的缓冲区可能会加快内存分配速度，但如果响应超过缓冲区大小，可能导致需要更多的读取操作。 该指令可在 http、server 或 location 上下文中配置，提供了应用上的灵活性。管理员可以根据其 gRPC 服务的具体需求调整缓冲区大小。例如，如果你的 gRPC 响应通常较大，增大缓冲区大小可以减少 NGINX 向上游服务器请求数据的次数，从而改善整体延迟和 gRPC 服务的性能。 该指令的参数包括一个表示缓冲区大小的单一值（以字节为单位），或者也可以使用诸如 `k`、`m` 之类的大小后缀来指定千字节或兆字节。建议根据上游 gRPC 服务的预期响应大小谨慎调整。

配置示例

http {
    grpc_buffer_size 64k;
    server {
        location /grpc {
            grpc_pass backend;
        }
    }
}

说明

`grpc_read_timeout` 指令定义了在建立连接后 NGINX 等待来自 gRPC 后端服务器响应的最大时间间隔。此超时对于控制服务器在放弃并关闭连接之前应等待回复的时长至关重要。它允许管理员通过避免请求无限挂起的长时间停滞来微调服务器的响应性和资源管理。 此指令可在三种上下文中指定：`http`、`server` 和 `location`。其值以时间格式指定（例如 '30s' 表示 30 秒）。指令的值必须是有效的时间跨度，可以以秒、分钟或小时为单位指定。如果在指定的超时时间内未收到响应，NGINX 将向客户端返回错误，从而在可能出现延迟的服务中提供更好的容错能力。 在生产环境中为 `grpc_read_timeout` 设置合适的值至关重要，尤其是当 gRPC 服务的响应时间可能随负载而变化时。超时时间过短可能导致不必要的重试或失败，而超时时间过长则可能降低应用的响应性，因为请求可能会不必要地长时间挂起。

配置示例

location /example {
    grpc_pass grpc://backend;
    grpc_read_timeout 30s;
}

说明

在 HTTP、server 或 location 块的上下文中使用 `grpc_next_upstream` 指令，用于定义在何种条件下 NGINX 会尝试将请求发送到为 gRPC 协议处理配置的下一个 upstream 服务器。该指令接受一个或多个参数，用于指定各种失败条件，例如超时、连接失败或其他错误。当发生定义的失败时，NGINX 会自动在 upstream 块中对下一个服务器重试该请求，从而通过允许对暂时性问题的自动恢复来提高 gRPC 服务的可靠性和可用性。 `grpc_next_upstream` 指令的行为既提供了细粒度的控制，又具有较强的灵活性。例如，如果请求超时或后端服务器不可达，该指令使 NGINX 能够无缝地尝试其他服务器。可以根据应用的要求设置该指令的参数，允许服务器管理员微调故障处理策略。这在分布式系统中特别有用，因为每个服务组件的可用性特性可能不同。 该指令与 NGINX 的整体负载均衡策略密切相关，可用于实现复杂的模式，例如主动健康检查和服务不可用时的处理。重要的是将此指令与 upstream 块设置一并配置，以确保对客户端和后端服务器情形做出一致的响应，最终改善使用 gRPC 进行实时通信的应用的用户体验。

配置示例

upstream grpc_backend {
    server backend1.example.com:50051;
    server backend2.example.com:50051;
}

location / {
    grpc_pass grpc://grpc_backend;
    grpc_next_upstream error timeout;  # Retry on error or timeout
}

说明

`grpc_next_upstream_tries` 指令指定在上一个服务器未能响应的情况下 NGINX 应尝试联系多少个上游服务器。在处理 gRPC 请求时，如果第一个上游服务器返回错误，NGINX 可以根据该指令的值将请求重试到后续服务器。该指令在负载均衡环境中很有用，通过在遇到问题时回退到备用服务器来确保客户端与服务器通信的可靠性。重试机制对短暂性故障有益，但应权衡可能导致的客户端响应时间增加。 该指令在 `http`、`server` 和 `location` 上下文中生效。`grpc_next_upstream_tries` 的值必须为正整数，表示在上游请求失败时允许的重试次数。如果将该指令设置为 0，则完全禁用重试，第一次联系上游服务器后即失败。默认行为由服务器管理员的配置决定，可根据应用需求在性能和可靠性之间进行权衡和调整。

配置示例

grpc_next_upstream_tries 3;

说明

`grpc_next_upstream_timeout` 指令指定在 gRPC 请求期间，当前一个上游服务器失败时，等待连接到下一个上游服务器的最长时间。该超时在多个上游服务器可能参与处理客户端请求的场景中至关重要。如果初始上游服务器发生错误，所配置的超时时间决定了 NGINX 在操作超时之前，会尝试连接栈中下一个可用上游服务器的时长。 `grpc_next_upstream_timeout` 的参数以毫秒为单位定义，这允许在主要服务器无响应或响应缓慢等不利情况下对响应生成速度进行细粒度控制。它直接影响服务的效率和响应性，尤其是在上游服务器故障率或延迟较高的情况下。通过配置此指令，管理员可以在等待服务器响应与故障切换到替代服务器之间取得平衡，从而优化用户体验和资源使用。 此指令可以在 `http`, `server` 和 `location` 等多种上下文中设置，使其在不同级别的配置中都具有通用性。将其与 `grpc_pass` 或 `proxy_next_upstream` 等相关指令结合使用，能够进一步增强服务器的功能和可靠性。

配置示例

location /api {
    grpc_pass grpc://my_upstream;
    grpc_next_upstream_timeout 500ms;
}

说明

`grpc_set_header` 指令允许您为传递到后端服务器的 gRPC 请求添加或修改 HTTP/2 头。这在微服务架构中尤其有用，当需要随请求发送特定元数据时。该指令接受两个参数：第一个是要设置的头名称，第二个是要赋给该头的值。这允许根据请求的上下文或预定义变量动态生成头的值。 当在特定上下文 (http, server, or location) 中使用 `grpc_set_header` 指令时，它会在该配置级别应用这些头。例如，如果在 server block 中声明，则由该 server 处理的所有 gRPC 请求都会携带指定的头。如果在 location block 内声明，则只有匹配该 location 的请求会被设置这些头。也可以在指令中使用变量来动态设置头值，从而提高将元数据传递给后端服务的灵活性。

配置示例

location /rpc {
    grpc_pass grpc://backend;
    grpc_set_header api-key $api_key;
    grpc_set_header user-id $http_user_id;
}

说明

`grpc_pass_header` 指令用于指定应从传入请求传递到上游 gRPC 服务器的哪些头。该指令在 gRPC 代理中起着关键作用，尤其在 gRPC 服务在运行时需要特定头时。当在适当的上下文 (http, server, location) 中设置时，它允许对头转发进行细粒度控制，使服务能够从客户端接收必要的元数据。 此指令的一个主要特点是它接受一个参数，该参数是要转发的 HTTP 头的名称。该参数不区分大小写，这意味着指定 `example-header` 或 `Example-Header` 将产生相同的结果。该指令可以重复使用以转发多个头，从而有助于在服务边界之间保持重要的元数据。 在需要保留并随 gRPC 调用一并传递身份验证令牌、跟踪 ID 或其他形式元数据的场景中，使用此指令尤其有用。它增强了依赖细微头信息进行操作的服务之间的互操作性，从而改善整体 API 功能。

配置示例

location /api {
    grpc_pass backend;
    grpc_pass_header Custom-Header;
}

说明

grpc_hide_header 指令用于控制 NGINX 提供的 gRPC 响应中应被省略的头部。该指令可以通过隐藏可能被暴露的头部来帮助管理敏感信息或控制客户端交互。它接受一个参数，用于指定要隐藏的头的名称。设置该指令后，任何来自 gRPC 服务器且包含指定头的响应都会在到达客户端之前被 NGINX 过滤掉。

配置示例

location /grpc {
    grpc_pass grpc://backend;
    grpc_hide_header X-My-Header;
}

说明

grpc_ignore_headers 指令允许用户指定一个在请求处理期间应被忽略的 gRPC 头列表。该指令接受一个或多个头名作为参数，任何与所列名称匹配的头都将被 NGINX 服务器排除在处理之外。这在某些场景下很有用，例如特定头可能会干扰应用逻辑，或安全策略要求从客户端请求中排除特定头。 该指令可用于 http、server 或 location 上下文，这意味着其作用可以限定为整个服务器、某个特定的虚拟主机，或甚至某个特定的 location 块。使用此指令的灵活性允许对 gRPC 流量管理进行细粒度控制。如果未指定任何头，则默认不忽略任何头，意味着默认情况下会处理所有头。 在使用此指令时，重要的是确保您选择忽略的头不会破坏 gRPC 应用程序的预期功能。忽略关键头可能导致应用出现意外行为，因为服务器可能无法接收处理请求所需的必要数据。

配置示例

location /grpc {
    grpc_pass grpc://backend;
    grpc_ignore_headers 
        x-grpc-status
        x-user-header;
}

说明

`grpc_ssl_session_reuse` 指令用于配置通过 NGINX 服务器建立的 gRPC 连接的 SSL 会话重用。它可以设置为一个标志值；启用时，gRPC 客户端可以重用现有的 SSL 会话来建立新连接，从而优化资源利用并提升性能。当该指令设置为 'on' 时，NGINX 在后续连接上可能减少 SSL 握手所需的时间，因为如果重用了现有会话则可以跳过握手。相反，将其设置为 'off' 会禁用此功能，这可能导致重复连接时延迟增加，因为每次都需要完整的 SSL 握手。 该指令可在多种上下文中使用，包括 `http`、`server` 和 `location`，根据需要重用会话的 gRPC 服务范围提供灵活性。请注意，虽然会话重用可以显著提高性能，但它要求服务器和客户端之间有适当的配置与兼容性才能正确工作。SSL 会话 ID 必须在服务器和客户端之间共享才可成功重用，这有时需要在多个服务器实例之间进行会话缓存的额外考虑。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_session_reuse on;
    ssl_certificate /path/to/cert;
    ssl_certificate_key /path/to/key;
    # other configurations...
}

说明

`grpc_ssl_protocols` 指令允许配置由 NGINX 处理的 gRPC 连接可用的 SSL 和 TLS 协议。用户可以指定服务器在安全通信中接受的协议列表，通过排除过时和易受攻击的协议版本来提高安全性。该指令可以在诸如 `http`、`server` 或 `location` 等不同上下文中定义，根据应用需求提供配置灵活性。 该指令的有效参数通常包括常见的 SSL/TLS 版本，例如 `TLSv1`、`TLSv1.1`、`TLSv1.2` 和 `TLSv1.3`，允许管理员对应用使用的安全标准进行精细控制。此外，在 `http` 上下文中定义此指令将使设置在整个服务器范围内生效，而在 `server` 或 `location` 上下文中定义则可实现更细粒度的控制，可能为不同的 gRPC 服务启用不同的协议设置。关键在于以满足安全要求和客户端兼容性考虑的方式排列所指定的协议。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_protocols  TLSv1.2 TLSv1.3;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
}

说明

`grpc_ssl_ciphers` 指令在 NGINX 中配置可用于 gRPC 应用的安全连接的密码套件。当 gRPC 服务配置为使用 SSL/TLS 时，需要在客户端和服务器之间建立安全的通信通道。`grpc_ssl_ciphers` 指令允许您显式指定服务器在协商 SSL/TLS 连接时应接受哪些密码，从而根据应用的需求确保兼容性和安全性。该指令适用于 `http`、`server` 和 `location` 上下文，因此在为全局或特定用例定义密码套件时提供了灵活性。 该指令接受一个参数，该参数是以冒号分隔的密码列表。列表中的每个密码必须符合 NGINX 所使用的 SSL/TLS 库（通常为 OpenSSL）的有效性要求。当指定多个密码时，建立安全连接时将按列出的顺序进行评估，从而允许优先选择密码。在配置密码套件时务必考虑应用的安全性，因为使用弱或已弃用的密码可能会使系统暴露于漏洞之中。此外，该指令与其他与 SSL 相关的指令协同工作，以为 gRPC 通信建立一个安全的环境。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_ciphers 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256';
}

说明

grpc_ssl_name 指令在 NGINX 配置中用于设置在 gRPC 连接的 SSL 握手期间将在 Server Name Indication (SNI) 扩展中发送的主机名。当 NGINX 作为多个 gRPC 服务的反向代理，而这些服务托管在同一个 IP 地址上但基于客户端请求的主机名需要不同的 SSL 证书时，这一点尤为重要。 当设置该指令时，NGINX 在处理 gRPC 请求时会用指定的值替换 SSL 上下文中的主机名。通过确保针对每个特定的 gRPC 服务请求呈现正确的证书，它提高了 SSL 连接的安全性和可靠性。该指令可用于 http、server 和 location 上下文，根据服务结构允许灵活配置。 该指令的参数必须是一个单独的字符串，用于定义 SSL 主机名。如果省略该指令，NGINX 默认使用客户端请求的原始主机。对于涉及虚拟主机或处理多个 gRPC 后端的部署，正确配置 grpc_ssl_name 至关重要。

配置示例

server {
    listen 443 ssl;
    server_name grpc.example.com;

    grpc_ssl_name backend.grpc.example.com;

    location / {
        grpc_pass grpc://backend;
    }
}

说明

在 NGINX 配置中，`grpc_ssl_server_name` 指令用于在 gRPC 连接的 SSL 握手中包含服务器名称。这使 NGINX 能够满足客户端的 Server Name Indication (SNI) 要求，帮助根据指定的主机名将连接正确路由到相应的后端服务器。启用此指令后，服务器可以在相同的 IP 地址上托管多个 SSL 站点，并通过各自的域名进行区分。 该指令可以在多种上下文中指定，包括 `http`、`server` 和 `location`，在整个配置文件中提供灵活的应用方式。将此指令设置为 'on' 后，NGINX 服务器会使用 gRPC 请求中包含的服务器名称用于其 SSL 配置，从而能够正确选择与域名匹配的 SSL 证书集合。在多个 gRPC 服务托管于同一服务器的环境中，这一点尤其有用。 需要注意的是，启用 `grpc_ssl_server_name` 可能需要对 SSL 证书进行仔细管理，以确保它们为 SNI 正确配置。如果使用多个域，请确保它们使用有效的 SSL 证书妥善保护，以实现可靠的通信。该功能强调了与期望 SNI 支持以正常工作的 gRPC 客户端的互操作性。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_server_name on;
    ssl_certificate /path/to/certificate.pem;
    ssl_certificate_key /path/to/key.pem;
}

说明

`grpc_ssl_verify` 指令在 NGINX 服务器配置中使用，用于控制对 gRPC 后端服务器的 SSL 证书验证过程。该指令接受一个标志参数，用以指定在 gRPC 请求期间是否执行 SSL 证书验证。 当设置为 'on' 时，NGINX 会将上游 gRPC 服务器提供的 SSL 证书与系统中配置的 CA 证书进行验证，确保证书有效，从而保证连接安全并验证服务器身份。 该指令可以放在 `http`、`server` 或 `location` 上下文中，根据请求层级实现灵活配置。如果启用验证且服务器证书无效或无法验证，NGINX 将拒绝建立连接。相反，将该指令设为 'off' 会禁用验证过程，这在测试时可能有用，但在存在中间人攻击风险的生产环境中会带来安全隐患。 请注意，当启用 `grpc_ssl_verify` 时，它依赖于 NGINX 构建中可用的 CA 证书，这些证书可以通过指定 `ssl_trusted_certificate` 指令来定制。因此，正确配置受信任证书对于该指令的正常运行以及与 gRPC 服务的安全通信至关重要。

配置示例

location /api {
    grpc_pass grpc://backend-grpc;
    grpc_ssl_verify on;
}

说明

在 NGINX 配置中，`grpc_ssl_verify_depth` 指令用于指定在处理 gRPC 请求时 SSL 验证链中允许出现的中间证书的最大数量。该指令在处理基于 SSL 的 gRPC 时尤为重要，因为它有助于控制证书验证过程，防止验证过程中出现循环或过深的证书链。通过设置此指令，管理员可以在保证安全性的同时兼顾运行性能，确保客户端连接到预期的服务器。 该指令采用一个整数值，定义 SSL 证书验证允许的最大深度。例如，如果设置为 '3'，则在到达信任锚点之前，证书链最多可以包含三个中间证书。在颁发多个证书且需要管理证书链深度以防超出既定要求的配置中，这一点很有用。此外，如果验证深度超过此限制，NGINX 将终止连接，从而在不对验证过程造成过大负担的情况下加强安全策略的执行。 此指令可以在多个上下文中指定，包括 `http`、`server` 和 `location`，根据配置的作用域实现细粒度控制。应根据服务器端和客户端已知的证书结构调整该值。

配置示例

http {
    server {
        location / {
            grpc_pass grpc://backend;
            grpc_ssl_verify on;
            grpc_ssl_verify_depth 3;
        }
    }
}

说明

`grpc_ssl_trusted_certificate` 指令在 NGINX 中用于指定包含受信任根证书的文件，以便在建立安全的 gRPC 连接时使用。这在 gRPC 服务通过 TLS 运行时尤为重要，因为它确保客户端能够验证服务器的 SSL 证书的真实性。所指定的证书文件通常包含被信任用于签署服务器证书的证书颁发机构 (CAs) 的公钥证书，从而使 NGINX 在建立安全连接时能够检查信任链。 在配置此指令时，应以其参数形式提供证书文件的路径。该文件应为 PEM 格式，并包含用于验证所需的完整证书链。还应确保该文件的权限允许 NGINX 读取。如果在 server 或 location 上下文中定义了这些指令，它们将应用于这些块处理的所有 gRPC 连接，从而确保所有通过这些块的 gRPC 流量进行一致的 SSL/TLS 验证。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_trusted_certificate /etc/nginx/certs/ca.crt;
    # Additional configuration...
}

说明

`grpc_ssl_crl` 指令用于 NGINX 配置中以指定 Certificate Revocation List (CRL) 文件，服务器在 gRPC 连接期间使用该文件来验证客户端 SSL 证书的有效性。这在确保通信通道安全方面尤为重要，因为它使服务器能够拒绝在到期日前已被吊销的证书。该指令可在 `http`、`server` 和 `location` 上下文中使用，便于在配置的不同部分范围内灵活设置。 当客户端尝试连接到服务器时，NGINX 将查阅指定的 CRL 文件，对客户端提供的证书进行检查。如果客户端的证书出现在 CRL 中，NGINX 将拒绝连接，从而通过确保被吊销的证书不能用于建立信任来增强安全性。必须保持 CRL 文件的更新以反映证书的当前状态，CRL 通常由管理签名和吊销的 Certificate Authority (CA) 提供。 该指令接受一个参数，指向 CRL 文件的路径，且必须与其他 SSL 指令（例如 `ssl_certificate` 和 `ssl_certificate_key`）配合使用，作为完整 gRPC SSL 配置的一部分。

配置示例

server {
    listen 443 ssl;
    ssl_certificate     /etc/ssl/certs/server.crt;
    ssl_certificate_key /etc/ssl/private/server.key;
    grpc_ssl_crl       /etc/ssl/crl/my_crl.pem;
}

说明

`grpc_ssl_certificate` 指令在 NGINX 中用于指定将在 HTTPS 上用于加密 gRPC 通信的 SSL 证书文件的路径。该指令对于确保通过 gRPC 连接传输的数据安全至关重要，为在网络上传输的敏感数据提供加密。当设置此指令时，NGINX 在处理传入的 gRPC 请求时会使用指定的 SSL 证书。 该指令可以放在 `http`、`server` 或 `location` 上下文中，允许在服务器架构的不同粒度级别上灵活配置 SSL。该配置期望一个参数，该参数应为指向 PEM 编码证书的有效文件路径。如果指定的文件无法读取或不是有效的证书，NGINX 将无法启动，从而强制执行严格措施以确保通信安全。此外，应与适当的 SSL 设置（例如 `grpc_ssl_certificate_key`）一起使用此指令，以在会话期间正确建立并保护 SSL 握手。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_certificate /etc/ssl/certs/my_cert.crt;
    grpc_ssl_certificate_key /etc/ssl/private/my_key.key;
    location /grpc {
        grpc_pass grpc://backend_service;
    }
}

说明

`grpc_ssl_certificate_key` 指令用于定义建立安全 gRPC 连接所需的私钥文件。该指令在服务器需要使用 SSL/TLS 向客户端进行身份验证时尤其关键。所提供的参数应为 PEM 编码文件的路径，该文件包含与 `grpc_ssl_certificate` 指令定义的 SSL 证书关联的私钥。当 gRPC 客户端尝试连接时，会使用 SSL 证书和私钥来建立安全连接，确保传输的数据被加密且安全。 该指令可在 `http`、`server` 或 `location` 级别使用。此灵活性允许根据 Web 服务器不同部分的需求对 SSL 配置进行细粒度控制。需要注意的是，如果未指定有效的证书及对应的私钥，客户端可能无法建立连接，导致通信失败。因此，对于通过 SSL/TLS 加密要求保密性和完整性的 gRPC 服务，正确设置该指令至关重要。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_certificate     /etc/ssl/certs/server.crt;
    grpc_ssl_certificate_key /etc/ssl/private/server.key;
}

说明

NGINX 中的 grpc_ssl_certificate_cache 指令旨在通过缓存 SSL 证书来提高 gRPC 通信的效率。它允许管理员指定一种缓存机制，用于存储在 gRPC 连接中经常使用的 SSL 证书，从而减少对这些证书的重复加载和解析的需求。通过缓存，这可以显著改善延迟和性能，因而将重复建立安全连接的开销降到最低。 该指令可以接受 1 到 3 个参数：缓存大小、用于缓存证书的 TTL (Time To Live) 和可选的最大尺寸。第一个参数设置缓存大小，通常以 bytes (e.g., 10m for 10 megabytes) 表示。TTL 决定证书在缓存中保持有效的时长，超过该时长后证书将被移除并重新加载。管理员可以根据其特定的服务器负载和性能要求调整这些参数。该指令的灵活性允许配置以适应各种 gRPC 应用的需求，确保安全且高效的服务交付。

配置示例

grpc_ssl_certificate_cache 10m 2m 1h;

说明

`grpc_ssl_password_file` 指令用于 NGINX 配置中，从指定文件读取密码。该密码在处理加密的 SSL 证书时非常重要，这类证书通常用于安全的 gRPC 连接。配置后，NGINX 会在 SSL 上下文初始化期间访问该密码，从而相应地解密 SSL 证书。密码文件的路径应作为该指令的参数提供。 就上下文而言，`grpc_ssl_password_file` 指令可以放置在 NGINX 配置文件的 `http`、`server` 或 `location` 块中。该指令的使用在依赖安全通道的 gRPC 应用中至关重要。如果指定的密码文件丢失或无法读取，NGINX 将无法启动，并会记录错误，指出 SSL 证书初始化的问题。 还必须确保证书密码文件具有适当的文件系统权限以避免未经授权的访问，因为它包含对安全 gRPC 通信运行至关重要的敏感信息。在生产环境中，管理此类文件的安全性对于维护 SSL 通信的完整性和机密性至关重要。

配置示例

server {
    listen 443 ssl;
    grpc_ssl_password_file /etc/ssl/private/grpc_password.txt;
    ssl_certificate /etc/ssl/certs/grpc_cert.pem;
    ssl_certificate_key /etc/ssl/private/grpc_key.pem;
}

说明

grpc_ssl_conf_command 指令用于在 NGINX 中为 gRPC 通信设置特定的 SSL 参数。该指令可以包含在 http、server 或 location 上下文中，便于灵活配置。它接受两个参数，分别表示要执行的命令及其对应的值。该指令的一个关键方面是它能够专门修改 gRPC 连接的 SSL 设置，独立于标准的 HTTP 配置，这对于在依赖 gRPC 的微服务架构中维护安全通信通道至关重要。 在使用 grpc_ssl_conf_command 时，你指定的每个命令都会影响传入 gRPC 请求的处理方式，并以感知上下文的方式生效。这意味着根据层级级别（http、server、location），这些命令的作用可以更细粒度或更全局，从而允许管理员根据 NGINX 不同部分的不同安全需求微调 SSL 操作。该指令对于默认 SSL 参数无法覆盖的自定义配置特别有用，因此对于希望增强其 gRPC 部署的用户来说非常重要。 需要注意的是，必须提供正确的值以确保最佳运行；错误的参数可能导致 SSL 配置不当，从而危及连接安全或导致服务故障。因此，在使用该指令时，建议仔细参考 NGINX 的 SSL 文档和 gRPC 的相关要求。

配置示例

grpc_ssl_conf_command valid_commands value;

说明

`gunzip` 指令在 NGINX 中用于控制服务器是否在将响应发送给客户端之前自动解压缩 gzip 压缩的 HTTP 响应主体。启用时，NGINX 会解压内容，使不支持 gzip 压缩的客户端能够正确解析响应，而无需在客户端进行额外处理。该指令对于确保与可能无法正确处理 gzip 编码的各种客户端的兼容性非常重要。 `gunzip` 指令以标志作为参数，`on` 启用解压缩，`off` 禁用。该指令可以在 `http`、`server` 和 `location` 上下文中使用，从而根据不同配置对何时解压响应进行精细控制。应谨慎使用此指令；例如，对某些可能被压缩的资源所在的 `location` 开启它可以减少带宽并提高加载速度，但对于非常小的文件可能会引入额外开销。 由于 NGINX 使用 `Content-Encoding` 头来判断响应是否被压缩，`gunzip` 指令与控制压缩过程的 gzip 相关指令配合工作。如果响应未被压缩（即未包含 `Content-Encoding: gzip` 头），`gunzip` 设置不会生效，这意味着无论该指令处于何种状态，原始内容都会按原样发送。启用 `gunzip` 时，用户必须确保上游服务器或应用程序正确设置了用于压缩的头部，以使其完全生效。

配置示例

server {
    listen       80;
    server_name  example.com;

    location / {
        gunzip on;
        proxy_pass http://backend;
    }
}

说明

`gunzip_buffers` 指令指定用于保存来自 HTTP 响应的解压数据的缓冲区数量和大小。该指令在处理发送给客户端的 Gzip 压缩内容时尤其有用，因为它允许 NGINX 高效地管理解压数据的内存分配。第一个参数定义缓冲区的数量，第二个参数指定每个缓冲区的大小（以字节为单位）。在处理 Gzip 压缩的响应时，NGINX 会使用这些缓冲区在将数据发送给客户端之前临时存储解压后的数据。 使用 `gunzip_buffers` 指令可以通过优化解压过程中的内存使用来提高性能。默认情况下，该指令可能未设置，这意味着 NGINX 将使用内置的缓冲区大小来处理解压数据。管理员可能希望根据应用的特性调整这些参数，尤其是在处理大文件或高流量时，合适的缓冲区大小可以防止性能瓶颈。总之，当涉及 Gzip 压缩内容时，该指令用途广泛，能够提高 NGINX 在响应处理上的效率。

配置示例

http {
    gunzip on;
    gunzip_buffers 8 16k;
}

说明

NGINX 的 HTTP Core 模块中的 'gzip' 指令用于控制发送给客户端的响应的 gzip 压缩。启用该指令后，NGINX 会使用 gzip 算法对响应进行压缩，这可以显著减小传输数据的大小并改善客户端的加载时间。服务器会检查允许的内容类型和客户端的能力（例如是否存在 'Accept-Encoding: gzip' 头）来决定是否以压缩数据响应。 该指令可取布尔值：设置为 'on' 时启用 gzip 压缩，设置为 'off' 时禁用。此外，NGINX 提供了若干配置参数以进一步细化 gzip 压缩的行为，例如 'gzip_types' 用于指定要压缩的 MIME 类型，'gzip_vary' 用于指示是否向响应添加 Vary 头以表明对不支持 gzip 的客户端存在不同版本。使用 gzip 有助于降低带宽成本并提升用户体验，尤其对 HTML、CSS 和 JavaScript 等基于文本的文件效果明显。 需要谨慎使用 gzip 压缩，因为并非所有内容类型都适合压缩，过度使用可能会在服务器端引入不必要的 CPU 开销。

配置示例

http {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

说明

gzip_buffers 指令指定在 NGINX 发送的响应上使用 gzip 压缩时，为存储压缩数据而分配的缓冲区的数量和大小。该指令接受两个参数：第一个指定缓冲区的数量，第二个指定每个缓冲区的大小。例如，配置 `gzip_buffers 16 8k;` 表示将分配 16 个每个 8 千字节的缓冲区。 这些缓冲区用于在将压缩输出发送到客户端之前保存数据，优化这些值会显著影响性能，尤其是在负载较高时。选择更大的缓冲区大小可以减少对输出的写入次数，从而在提高吞吐量的同时增加内存使用；相反，较小的缓冲区可能导致更频繁的写入但降低内存占用。 需要注意的是，缓冲区的总大小还取决于分配的总内存，这可能受到系统设置或应用程序内存占用的限制。错误配置这些值可能导致内存使用效率低下或性能瓶颈，尤其是在处理大响应或高流量时。

配置示例

gzip on;
gzip_buffers 16 8k;

说明

NGINX 中的 `gzip_types` 指令用于定义一个 MIME 类型列表，当启用 `gzip` 模块时这些类型应被压缩。该指令可以更精细地控制哪些文件类型会被压缩，从而优化特定内容类型的传输，同时可能排除那些压缩后不会显著减小体积的类型。该指令接受一个或多个 MIME 类型作为参数。通过指定这些类型，可以确保只有预期的内容类型（例如文本文件）会被压缩，从而提升加载速度并节省带宽，同时避免对非相关文件类型进行不必要的处理。 当启用 gzip 模块时，它会将响应的 `Content-Type` 头与 `gzip_types` 中指定的 MIME 类型进行检查。如果匹配，则在发送到客户端之前对响应进行压缩。这一功能对基于文本的内容（例如 HTML、CSS、JavaScript 和 XML）尤其重要，可大幅减小大小，从而加快页面加载。然而，为了实现最佳效率，关键是列出所有希望压缩的相关 MIME 类型。此外，应注意理解特定文件格式的行为；例如，某些二进制格式可能已经被压缩，额外的 gzip 压缩可能效果不佳甚至适得其反。

配置示例

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml;

说明

NGINX HTTP Core 模块中的 `gzip_comp_level` 指令允许管理员指定在提供 gzip 编码内容时应用的压缩级别。有效值范围为 1 到 9，其中 1 表示最小的压缩量（处理速度最快），9 表示最高的压缩级别（CPU 负载更高）。 默认情况下，`gzip_comp_level` 设置为 1，这意味着内容将被轻度压缩。提高此值可以改善压缩比，从而节省更多带宽；但同时也会在压缩过程中增加 CPU 使用率。在权衡时需要谨慎考虑，尤其是对于高流量站点，过高的 CPU 负载可能会影响性能。另外，压缩级别仅适用于符合 gzip 压缩条件的数据，例如 HTML、CSS 和 JavaScript 文件，具体由其他 `gzip` 指令指定。 该指令具有上下文相关性，可以在 `http`、`server` 或 `location` 上下文中定义，便于根据具体需求进行灵活配置。在 `http` 上下文中设置将把指定的压缩级别应用于全局，而在 `server` 或 `location` 上下文中的设置可以覆盖全局设置以实现更细粒度的控制。

配置示例

http {
    gzip on;
    gzip_comp_level 5;
}

说明

gzip_window 指令在启用 NGINX 的 Gzip 压缩时，配置 zlib 压缩算法所使用的滑动窗口的最大大小。它指定在压缩响应时可以保留在内存中的输入数据量。较大的窗口大小可以通过在处理输出的每个字节时引用更多数据来提高压缩效率，从而获得更好的压缩比。然而，这也会增加 NGINX 工作进程的内存使用，在内存受限的环境中可能是不利的。 该指令接受单个参数，应以字节为单位指定，这意味着您可能需要提供不带任何后缀的数字值。设置此参数后，指令会启用指定的窗口大小用于 Gzip 压缩，从而提升通过 HTTP 传输内容的整体性能和效率。如果未配置，则会应用默认设置，根据被压缩内容的类型和大小，默认值可能无法充分发挥 Gzip 算法的潜力。 在实际操作中，用户在增大此值之前应仔细考虑服务器的内存能力，尤其是在高负载场景或处理大型响应时，因为过度分配可能导致内存耗尽和性能下降。

配置示例

gzip on;
 gzip_window 32k;  
 location / {
     gzip_types text/plain text/css application/json; 
     # any other configurations 
 }

说明

指令 `gzip_hash` 属于 NGINX 的 HTTP Core module，控制 NGINX 如何处理 HTTP 响应的 gzip 压缩。通过定义哈希方法，它可以优化已缓存内容的 gzip 参数的存储和检索，从而在高负载下提供更好的性能。 该指令可以配置为多种哈希算法，例如 `md5`、`sha1` 或 `crc32`，允许用户根据服务器的能力和预期内容类型调整 gzip 压缩的响应性与资源使用。哈希方法的选择可能影响存储的 gzip 标志的性能和大小，从而影响整体内存占用。NGINX 会检查压缩上下文，并根据配置的参数生成哈希值，以确保基于所选哈希函数为压缩内容生成唯一标识符。 指令 `gzip_hash` 可放置在 `http`、`server` 或 `location` 上下文中，提供配置上的灵活性。需要注意的是，选择更复杂的哈希函数可以提高条目的唯一性，但可能会消耗额外的 CPU 周期，因此在配置时应根据应用的具体需求及预期负载进行权衡。

配置示例

http {
    gzip on;
    gzip_hash sha1;
}

说明

'postpone_gzipping' 指令在 NGINX 中指定是否应延迟对响应主体的 gzip 压缩，直到响应头被发送。默认情况下，响应数据序列化为 gzip 格式会立即执行。然而，当设置为 'on' 时，NGINX 会将压缩推迟到 HTTP 头发送之后，这在服务器需要优先快速向客户端发送头部而不是承担压缩开销时可能有利。此设置可以优化资源使用并改善感知延迟，尤其是对大体积响应。\n\n该指令可在多种上下文中使用，包括 http、server 和 location 块。应用时，它可以接受单个参数 'on' 或 'off'。如果设置为 'on'，NGINX 将延迟 gzipping 过程，这允许在处理特定类型的响应或在请求处理的某些阶段时具有更大的灵活性。相反，将其设置为 'off' 或不指定该指令将导致 NGINX 立即执行 gzipping，在响应主体生成后立即应用任何已配置的压缩设置。

配置示例

http {
    gzip on;
    postpone_gzipping on;
}

说明

`gzip_no_buffer` 指令在 NGINX 中用于控制对进行 gzip 压缩的响应的输出缓冲。当设置为 'on' 时，该指令允许 NGINX 在不先将整个响应缓存在内存中的情况下，直接将压缩后的输出发送给客户端。对于较大的响应或需要实时流式传输数据的场景，这种行为尤其有用，因为它通过在生成数据时即发送给客户端来减少内存使用并可能提高吞吐量。相反，将此指令设置为 'off'（默认值）会启用缓冲，使整个响应在压缩并发送之前保存在内存中，这在优化响应传递方式时可能有利，尤其是当服务器可以从数据去重和压缩效率中受益时。 该指令接受一个标志参数：'on' 或 'off'。启用时，响应会直接发送而不进行缓冲；保持关闭则采用标准的缓冲行为。需要注意的是，在特定场景下关闭缓冲可能会影响性能，尤其是在处理大量并发请求或大型响应时，因为动态压缩数据的开销可能会增加运行负载。

配置示例

http {
    gzip on;
    gzip_no_buffer on;
}

说明

`gzip_min_length` 指令控制在 NGINX 中响应主体达到多大尺寸才可进行 Gzip 压缩。当生成响应时，如果主体大小小于指定长度，则不会进行压缩。此项设置有助于优化性能，因为压缩较小的响应可能比直接发送未压缩的内容更耗费 CPU。 该指令接受一个以字节为单位定义最小长度的参数，并且可以在 `http`、`server` 或 `location` 上下文中设置。这允许在服务器层级的不同级别使用不同的配置。通过调整该值，管理员可以在压缩开销与网络带宽节省之间找到平衡。对于响应包含小型资源（例如图像或脚本）的场景尤其重要，因为这些资源可能不会从 Gzip 压缩中获得显著收益。 要设置此指令，只需提供一个表示阈值的数字（字节）。例如，设置 `gzip_min_length 1000;` 意味着任何小于 1000 字节的响应主体将以未压缩形式发送，而较大的主体将被压缩。该行为有助于减轻因处理大量小型压缩文件而导致的性能延迟。

配置示例

http {
    gzip on;
    gzip_min_length 1000;
}

说明

`gzip_static` 指令允许 NGINX 提供带有 `.gz` 扩展名的预先压缩文件，而不是在运行时即时压缩文件。启用后，当对压缩资源发出请求时，NGINX 会首先在指定位置检查对应的 `.gz` 文件是否存在。如果找到，则直接提供该文件，绕过 gzip 模块的运行时压缩。这些预先压缩的文件有助于提高性能，尤其是在高峰流量期间，因为它们减少了与动态 gzip 压缩相关的 CPU 开销。 `gzip_static` 指令接受一个参数，可为 `on` 或 `off`，用于指示启用或禁用该功能。设置为 `on` 时，NGINX 在处理请求时会检查文件的 gzip 压缩版本（通常以 `.gz` 为后缀）是否存在。如果没有找到此类文件，NGINX 会回退为提供常规文件（如果存在），如果两者都不存在则返回错误。此行为提高了资源传输的效率，尤其适用于 HTML、CSS 或 JavaScript 等文本类内容，因为 gzip 压缩通常能显著减小体积。 需要注意的是，为了使 `gzip_static` 有效运行，通常会将其与 `gzip` 指令配合使用，以确保在构建或部署阶段对必要的文件应用压缩。此外，还需要正确管理缓存头，以防在静态文件更新时提供过期的数据。

配置示例

http {
    gzip_static on;

    server {
        location / {
            root /var/www/html;
        }
    }
}

说明

'expires' 指令用于为 NGINX 提供的静态资源设置过期时间。通过定义资源被视为有效的时长，它有助于浏览器缓存并通过减少发送到服务器的请求数量来优化加载时间。该指令接受一个时间值作为参数，可以用秒（例如 '30s'）、分钟（例如 '5m'）、小时（例如 '12h'）或天（例如 '1d'）来指定。还有额外选项，可指定 'max' 表示无限期过期，或 'epoch' 将其设置为过去的时间。 设置后，'expires' 指令会为客户端请求自动生成相应的响应头。它可以在多个上下文中配置，包括 'http'、'server' 和 'location'。值得注意的是，它也可以在 location 块内的 'if' 语句中使用以获得更细粒度的控制。通过在不同上下文中使用多个 'expires' 指令，可以针对不同类型的资源定制缓存策略，从而确保静态文件得到高效提供。

配置示例

location /images {
    expires 30d;
}

说明

`add_header` 指令允许在 NGINX 发送的响应中包含特定的 HTTP 头。对于配置参数（如安全策略 (`Strict-Transport-Security`, `Content-Security-Policy`)）或管理缓存行为（`Cache-Control`, `Expires`）特别有用。指定时，它会为定义的上下文 (http, server, or location) 设置这些头。\n\n可以使用多个 `add_header` 指令定义多个头，如果该头已存在，使用此指令可以修改其值。一个需要注意的关键行为是，`add_header` 不会覆盖已存在的头，除非使用 `always` 参数；使用 `always` 可以确保在响应代码指示错误（例如 4xx 或 5xx 响应）时也包含所添加的头。这允许在不受底层应用逻辑响应影响的情况下管理头的可见性。

配置示例

server {
    listen 80;
    server_name example.com;
    add_header X-Frame-Options "DENY";
    location / {
        add_header Content-Security-Policy "default-src 'self'";
    }
}

说明

`add_trailer` 指令用于指定包含在 HTTP/2 和 HTTP/3 响应的 response trailer 部分的自定义 header 字段。Trailers 是在消息体之后发送的额外 HTTP 头。这对于在主负载发送完成后才能确定的元数据或状态信息很有用。 该指令接受 2 到 3 个参数：第一个参数是要添加的 header 的名称，后续参数是与该 header 关联的 values。values 可以包含 variables，使该指令在处理动态 header 内容时更灵活。如果指定了多个 values，它们将用逗号连接。 需要注意，并非所有 clients 都能良好处理 trailers，因此开发者应确保其 applications 能正确处理包含 trailer 信息的响应。此外，使用该指令时应谨慎，因为它可能会根据添加的 headers 影响 caching 和 client 行为。

配置示例

server {
    location /example {
        add_trailer X-Custom-Trailer "Trailer Value";
    }
}

说明

`add_header_inherit` 指令控制使用 `add_header` 设置的头部指令的继承。当指定此指令时，它允许在父上下文（例如 http 或 server）中定义的任何 `add_header` 指令被子上下文（如 location）继承。这对于确保在不同配置级别中的头部一致性特别有用，无需在每个上下文中重新定义头部，从而简化配置管理。该指令接受一个参数，用于指定是否启用此继承，其中 `on` 允许继承，`off` 禁止继承。 默认情况下，继承是禁用的，除非显式启用。当启用继承时，父上下文中添加的任何头部将自动包含在子上下文的响应中，从而允许服务器在配置的特定块中全局应用并保持一致的头部，例如安全头、缓存策略或自定义头。通过减少在多个上下文块或 location 中重复定义头部，这可以提高安全性和性能。

配置示例

http {
    add_header X-Frame-Options "DENY";
    server {
        add_header_inherit on;
        location /api {
            # /api will inherit the X-Frame-Options header
        }
    }
}

说明

`add_trailer_inherit` 指令提供了一种机制，用于配置在代理服务器上下文中如何处理 trailer headers（即在主响应体之后发送的头）。设置后，它允许将这些 trailer headers 从被代理的 upstream 服务器响应继承到发送给客户端的响应中。当处理诸如 chunked 之类的传输编码时，这一点尤其有用，因为在响应结尾需要发送额外的头以向客户端提供必要的元数据。 该指令接受一个参数，值为布尔型：'on' 或 'off'。若设置为 'on'，NGINX 将在发送给客户端的响应中包含从 upstream 服务器收到的任何 trailer headers。若设置为 'off'，则不会包含这些头。必须认识到，继承 trailer headers 可能会影响客户端的行为，特别是在涉及 HTTP/1.1 chunked 传输的场景中。因此，在使用此指令时应仔细考虑 upstream 服务器的配置和客户端的期望。

配置示例

http {
    server {
        location /example {
            proxy_pass http://upstream_server;
            add_trailer_inherit on;
        }
    }
}

说明

`image_filter` 指令是 NGINX 图像过滤模块的一部分，该模块通过定义的过滤器提供处理图像文件的功能。您可以在 `location` 块中使用此指令，以启用例如调整大小、裁剪和更改由 Web 服务器提供的图像格式等操作。 该指令接受一到三个参数：过滤器类型、其参数和可选的配置标志。过滤器可以包括例如将图像调整为特定尺寸或修改格式以优化加载时间并减少资源使用的选项。根据指定的过滤器及其配置，NGINX 在图像被请求时动态处理图像文件，而不是提供静态副本，这可以显著提升性能和灵活性。 该指令通过允许实时图像处理而无需外部处理工具，从而提升整体用户体验。这可以减少服务器负载并提高响应速度，尤其适用于需要为不同设备类型提供各种图像尺寸或格式的应用。

配置示例

location /images {
    image_filter resize 800 600;
    image_filter_jpeg_quality 85;
    image_filter_cache on;
}

说明

`image_filter_jpeg_quality` 指令允许你在通过 NGINX 的图像过滤模块处理时指定 JPEG 图像的质量。它接受单个参数，表示所需的质量级别，范围从 1 到 100。较小的数值会导致更高的压缩率和更低的图像质量，而较大的数值则会产生更好的图像质量但文件体积更大。 当你在 `http`、`server` 或 `location` 上下文中设置该指令时，NGINX 会将指定的质量设置应用到所有由图像过滤模块处理的 JPEG 图像。这对于通过在文件大小和视觉保真度之间取得平衡来优化图像传输特别有用，这可以改善加载时间并为 Web 应用节省带宽。需要注意的是，只有在你的 NGINX 配置中包含并启用了图像过滤模块时，该指令才会生效。 该指令的一个特殊注意点是，如果你在一个需要快速加载时间的网站上提供图像，可能需要试验该质量设置以找到既满足性能又满足外观要求的最佳平衡。此外，对该指令的修改需要重新加载 NGINX 配置才能生效。

配置示例

http {
    location /images {
        image_filter jpeg;
        image_filter_jpeg_quality 85;
    }
}

说明

`image_filter_webp_quality` 指令用于定义在 NGINX 中使用 image_filter 模块时生成的 WebP 图像的质量级别。该指令接受一个参数，该参数为整数，用来指定输出 WebP 图像的质量（0 到 100），其中 100 表示最高质量和最低压缩，0 则表示最低质量和最大压缩。该指令必须在配置文件的 `http`、`server` 或 `location` 上下文中包含，因为它用于控制图像的处理和提供方式。 配置后，`image_filter_webp_quality` 通过将传入图像转换为 WebP 格式来增强 NGINX 的图像提供能力，WebP 通常相比 JPEG 或 PNG 等其他格式体积更小，而不会显著降低视觉质量。如果客户端支持 WebP（通过检查 HTTP 请求中的 `Accept` 头确定），此转换会在运行时进行。适当设置质量参数可让开发者根据应用的具体需求在图像清晰度和文件大小之间进行权衡，从而改善以图像为主的网页的加载时间和性能。

配置示例

location /images {
    image_filter png;
    image_filter_webp on;
    image_filter_webp_quality 85;
}

说明

'image_filter_sharpen' 指令用于在 NGINX HTTP 服务器中，对由图像过滤模块处理的图像应用锐化效果。该指令可以通过增强边缘和细节处的对比度来改善图像的外观。它接受一个参数，用于指定锐化强度，控制滤镜增强图像清晰度的程度。数值越高，图像越锐利，但过度锐化可能会产生伪影。 正确配置时，'image_filter_sharpen' 指令可放在不同的上下文中，例如 http、server 和 location 块。该指令应与处理 NGINX 所提供图像文件的图像过滤模块配合使用。如果图像未被处理或滤镜模块未启用，则该指令不会生效。锐化效果的显著程度也会根据原始图像质量而有所不同。 用户应提供数值（通常范围为 0 到 100）来微调应用于图像的锐化量。根据视觉输出的需求适当设置该值，可以在保持自然外观、避免过度锐化的同时显著提高图像清晰度。

配置示例

location /images {
    image_filter brighten 0.1;
    image_filter_sharpen 10;
}

说明

'image_filter_transparency' 指令允许用户指定由 NGINX 图像过滤模块处理的图像的透明设置。该指令接受一个布尔标志，当启用时，会指示 NGINX 在渲染图像时应用透明设置。对于需要保持透明背景（例如标志或图标等网站资源）的图像，这一功能特别有用，可确保图像文件中设定的任何透明度在传输过程中被保留。 当该指令设置为 'on' 时，图像过滤器会根据图像文件的 alpha 通道处理图像，以保留或应用透明区域。该设置有助于网页开发者在不同浏览器和平台上优化图像显示效果。它作为一个简明的开关，改变图像数据的存储和传输方式，而无需在客户端进行额外的处理或操作。该指令影响图像的渲染方式，但不允许在启用与禁用之外对透明度级别进行更细粒度的配置。 在上下文中，该指令可以在 http、server 或 location 块中指定，从而允许在不同配置作用域中灵活应用。将此指令与图像过滤模块中的其他指令正确搭配使用，可以显著影响 NGINX 实例所提供图像的视觉质量，从而提升 Web 应用的整体用户体验。

配置示例

location /images/ {
    image_filter on;
    image_filter_transparency on;
    try_files $uri =404;
}

说明

image_filter_interlace 指令用于控制如何将图像提供给客户端，尤其是与渐进渲染相关的情况。启用交错时，图像以允许它们逐步加载和显示的方式发送到浏览器，从而在较慢的连接上提升大图像的用户体验。该指令接受一个布尔标志：'on' 启用交错，'off' 禁用交错。这意味着开发者可以根据具体用例和性能考虑选择是否以支持渐进显示的格式提供图像。 该指令可在 http、server 或 location 上下文中配置，从而可以全局应用或更精确地针对特定位置应用。例如，在网站提供画廊图片时启用此指令特别有益，因为它允许用户在图像加载时先看到低分辨率版本，而无需长时间等待高分辨率图像完全渲染。需要注意的是，交错通常仅被某些图像格式（例如 PNG 和 JPEG）支持，并且并非对所有图像类型或场景都有益。在图像加载性能是关注点的环境中，可能需要测试两种场景以确定哪种提供最佳的用户体验。

配置示例

location /images/ {
    image_filter on;
    image_filter_interlace on;
}

说明

`image_filter_buffer` 指令配置在使用 NGINX 图像过滤模块处理图像时分配的内存量。该指令在处理大图像时至关重要，因为它能够实现高效的处理并避免可能导致性能下降的过度内存分配。缓冲区大小允许 NGINX Web 服务器在发送给客户端之前将图像数据临时保存在内存中，以便执行诸如缩放、裁剪或修改图像的操作。 此指令可以在 `http`、`server` 或 `location` 上下文中设置。指定时，它接受一个单一参数，表示缓冲区的大小（以字节为单位）。如果指定的大小不足以处理某个图像，NGINX 可能会返回错误或无法按预期处理图像。因此，必须根据所提供或处理图像的大小和类型适当设置缓冲区。 在实践中，该指令有助于在确保图像操作能够无缝执行的同时保持服务器资源的高效利用。在设置此值时，应考虑服务器的可用内存和预期流量，以在性能和内存使用之间取得平衡。

配置示例

location /images/ {
    image_filter buffer 16k;
    image_filter resize 200x200;
}

说明

'index' 指令在 NGINX 中指定当用户请求目录时应返回的默认文件。该指令在以下情况下特别有用：当目录中不包含用户指定的 index 文件，或用户直接请求目录路径时。服务器会按列出的顺序查找指定的 index 文件，直到找到其中一个，或所有选项都被耗尽。这允许根据应用需求自定义默认行为。\n\n可以通过空格分隔来指定多个 index 文件，NGINX 会按给定顺序检查每个文件是否存在。如果没有找到任何指定的文件，NGINX 将根据配置设置返回 403 Forbidden 或 404 Not Found 错误。这种灵活性使得 'index' 指令成为 NGINX 无缝提供动态 Web 应用程序和静态内容能力的关键部分。

配置示例

location / {
    index index.php index.html index.htm;
}

说明

'limit_conn_zone' 指令用于 HTTP 上下文中，定义一个内存区域，用于跟踪指定键（例如远程地址）的连接数量。它允许您为单个 IP 地址或任何其他参数设置并发连接数限制，帮助缓解因过多连接导致的滥用或资源耗尽。 该指令接受两个参数：第一个是键，通常使用诸如 '$binary_remote_addr'（引用客户端的远程地址）或 '$servername'（基于服务器名的限制）之类的变量。第二个参数定义共享内存区域的大小（例如 '10m' 表示 10 兆字节）。该内存区域用于存储指定客户端的连接计数，允许基于实时连接进行高效跟踪和限制。 与 'limit_conn' 指令结合使用时，管理员可以指定每个键允许的并发连接数，从而增强安全性和性能。所设置的内存限制确保此跟踪在不消耗过多资源的情况下有效。

配置示例

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    server {
        location / {
            limit_conn addr 10;
        }
    }
}

说明

NGINX 中的 `limit_conn` 指令用于限制单个 IP 地址对特定 server 或 location 块发起的并发连接数。 这对于防止由于连接过多而导致的滥用或过载至关重要，这类情况会降低服务器性能。该指令接受两个参数：区域名称和每个 IP 地址允许的最大连接数。该指令与 `limit_conn_zone` 配合使用，后者定义用于跟踪来自 IP 地址的连接计数的共享内存区域。 当收到请求时，NGINX 会在定义的区域中将源 IP 的连接计数递增。如果连接计数超过指定限制，客户端将收到 503 服务不可用 错误。连接计数按 IP 地址管理，通常记录在内存中，从而可以高速检查连接限制，无需持久化存储。这有助于管理拥塞并确保服务器资源在用户之间公平分配。 要实现该指令，管理员必须在适当的上下文（http、server 或 location）中定义限制，并确保配置了相应的 `limit_conn_zone` 指令。根据预期流量在定义区域和设置限制之间取得平衡，是有效实施此指令的关键。

配置示例

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    server {
        location / {
            limit_conn addr 1;
        }
    }
}

说明

`limit_conn_log_level` 指令用于定义当连接数超出由 `limit_conn` 指令指定的允许限制时的日志记录级别。这有助于调试和监控，因为管理员可以通过调整日志的详细程度来判断情况的严重性。 该指令接受一个表示日志级别的单一参数，该级别可以是预定义的 NGINX 日志级别之一，例如 `error`、`warn`、`info`、`notice` 等。根据所选级别，关于连接限制违规的记录信息量会有所不同，这对运营洞察和诊断很有帮助。 通过在不同上下文（例如 HTTP、server 或 location 块）中设置此指令，您可以对应用各个部分的连接限制问题的日志记录进行精细控制。这种有针对性的日志记录有助于在 Web 服务器架构的不同层面识别具体问题。

配置示例

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    limit_conn addr 10;
    limit_conn_log_level warn;
    # Other settings...
}

说明

NGINX 中的 `limit_conn_status` 指令指定当客户端请求超出在某一上下文 (http, server, or location) 配置的连接限制时返回给客户端的 HTTP 状态码。该指令允许管理员自定义响应行为，为可能不小心尝试建立超过 NGINX 配置允许的连接数的用户提供更有意义的提示。 当由 `limit_conn` 配置的限制被触发时，可以返回指定的状态码，而不是返回默认的 503 Service Unavailable 响应（该响应可能无法为用户提供有意义的反馈）。这可以更清晰地表明情况，帮助客户端应用处理错误。状态码必须是有效的 HTTP 码，通常应避免使用常见的成功或重定向状态码以免引起混淆。 要有效使用此指令，建议评估客户端应用在触发限制时的预期行为，因为除 503 之外的状态码可能改变客户端对容量问题的响应方式。例如，使用 429 Too Many Requests 状态可能更合适，表明用户因过度访问资源而被限速。该指令还可以与专门用于监控连接限制违规的日志结合使用。

配置示例

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    limit_conn addr 10;
    limit_conn_status 429;
}

说明

`limit_conn_dry_run` 指令是一个功能，允许管理员在不实际拒绝连接的情况下测试其连接限制配置。设置后，服务器不会阻止超过定义限制的连接，但会记录那些在日志中本应被强制限制的实例。这对于在不影响用户体验的情况下调整和验证配置特别有用，允许管理员在完全应用限制之前收集有关限制可能影响的数据。 该指令可在 `http`、`server` 或 `location` 上下文中设置，并接受一个标志作为参数 (on/off)。启用后（设置为 'on'），NGINX 将模拟限制而不阻止超出的连接。需要注意的是，在该指令处于活动状态时，没有实际的连接会被拒绝，这可以在不造成中断的情况下清楚地反映出相对于限制的使用情况。 然而，管理员在生产环境测试时应对该指令保持谨慎，因为服务器仍会在日志中记录那些超过限制的情况，如果将该指令与强制执行的限制混淆，可能会导致观察结果出现误导。理想情况下，应在配置评估期间临时使用该指令。

配置示例

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m; 
    server {
        limit_conn addr 10;
        limit_conn_dry_run on;
    }
}

说明

'limit_req_zone' 指令在 NGINX 配置的 http 上下文中使用，用于定义与请求速率限制机制关联的共享内存区。它接受三个参数：一个用于定义请求将被跟踪的上下文的 key（例如客户端 IP 地址或某个变量）、存放请求计数器的区域名以及该共享内存区的最大大小。\n\n正确配置后，NGINX 会基于所定义的 key 对进入的请求进行分组并随时间统计这些请求。例如，如果 key 是客户端的 IP 地址，NGINX 会跟踪每个 IP 发出的请求数量。这允许管理员防止滥用并限制对特定资源的过度使用。请求限制功能通过两个主要选项，burst 和 nodelay 来实现，可与 'limit_req' 指令一起指定以控制如何处理超额请求。\n\n所选参数必须反映部署需求，因为不同的应用可能需要更高或更低的速率限制，并可能受到用户同时请求突发的影响。因此，正确调整这些参数对于避免无意中限制合法用户同时有效缓解滥用至关重要。

配置示例

limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

说明

'limit_req' 指令用于在 NGINX 中限制客户端在指定时间内向服务器发起的请求数量。该指令属于 HTTP Core Module，可在多种上下文中使用，包括 http、server 和 location 块。此指令的主要目的是控制流量并防止客户端滥用（例如发送过多请求），以免影响服务器的性能和稳定性。 'limit_req' 指令接受一到三个参数： 1. **zone**（必需）：存储请求速率限制配置的共享内存区域。 2. **burst**（可选）：当短时超过限额时，允许处理一定数量的超额请求（无需延迟）。burst 值允许应对流量突增。 3. **nodelay**（可选）：如果指定，超额请求在不超过 burst 限制时将立即被处理；否则将根据速率限制被延迟。 在使用 'limit_req' 之前，用户需要使用 'limit_req_zone' 指令定义一个共享内存区域。速率限制基于这些区域中定义的参数，这些参数决定在指定时间内来自特定键（例如 IP 地址）的请求数量。

配置示例

limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s;
server {
    location /api {
        limit_req zone=mylimit burst=5 nodelay;
    }
}

说明

`limit_req_log_level` 指令允许管理员指定记录请求限额违规事件的日志严重性级别。该指令可以在 `http`、`server` 或 `location` 上下文中定义，接受一个表示日志级别的单个参数。可用级别包括 `error`、`warn`、`info`、`debug` 等。默认情况下，如果未配置，NGINX 在请求限制日志中使用日志级别 `error`。\n\n当使用 `limit_req_zone` 指令定义的请求限制被超过时，NGINX 会根据指定的日志级别记录这些事件。这对于监控非常重要，允许您根据运行需求调整日志详细程度，或排查与流量限速相关的问题。在高流量环境中尤其有用，因为过多的日志可能会掩盖关键信息。该日志机制与 NGINX 的错误日志功能集成，您可以审查这些日志以识别模式并采取适当措施以优化请求处理。

配置示例

http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
    limit_req_log_level warn;
}

说明

`limit_req_status` 指令属于 NGINX HTTP Core 模块，并与 `limit_req` 指令提供的速率限制功能配合使用。当客户端超过允许的请求速率时，针对被限流机制拒绝的请求会返回指定的 HTTP 状态码。这样可以使用自定义的信息，例如 503 Service Unavailable，来通知客户端请求被限速，而不仅仅是简单地未能处理其请求。 该指令接受单个参数：当请求超出限制时应在响应中发送的目标 HTTP 状态码。用户可以指定任何有效的 HTTP 状态码，以便根据其应用的需求灵活选择。常用的状态码包括 503（服务不可用）或 429（请求过多）。需要注意的是，该指令仅影响因限流而未被处理的请求，而不影响那些在限制范围内成功处理的请求。 作为配置指令，它可以在 `http`、`server` 或 `location` 上下文级别定义，从而可以根据应用的不同范围灵活地应用不同的状态码。开发人员应确保所指定的状态码在启用速率限制时与其应用的错误处理逻辑和用户期望相符。

配置示例

limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

server {
    location / {
        limit_req zone=one;
        limit_req_status 503;
    }
}

说明

limit_req_dry_run 指令专为便于在 NGINX 中开发和测试限流配置而设计。启用时，它通过处理请求但不实际强制任何限制来模拟限流效果。这在管理员想要监控在超过速率限制时本可能被处理或拒绝的请求数量而不影响实时流量的情况下特别有用。 该指令接受一个二元参数——on 或 off。设置为 on 时，NGINX 会按照其他指令（例如 limit_req_zone）定义的规则执行限流检查，但不会基于这些限制拒绝请求。相反，日志会标明请求是否超限。这允许在全面部署前对限流参数进行微调并确保一切按预期工作。该指令具有上下文敏感性，可以在 NGINX 配置的 http、server 或 location 块中进行配置。 通过使用 limit_req_dry_run，管理员可以收集有关请求行为和模式的数据，这有助于在指令关闭后有效确定应应用的合适速率限制。然而，必须记住，启用模拟运行时，实际的预期限流不会生效，如果在开始强制执行后将限制设置得过高，可能会导致未被监控的流量激增。

配置示例

http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

    server {
        location / {
            limit_req zone=one;
            limit_req_dry_run on;
        }
    }
}

说明

'log_format' 指令在 'http' 上下文中使用，用于指定日志条目的格式。每个日志条目可以包含表示不同请求和服务器参数的变量，例如客户端 IP 地址、请求方法、响应状态等。默认情况下，日志条目以简单格式生成，但使用 'log_format' 指令可以进行自定义，以满足特定的日志记录需求。 该指令至少需要两个参数，包括日志格式的名称和指定日志输出布局的实际格式字符串。格式字符串可以包含各种变量（例如 $remote_addr 表示客户端 IP，$request_time 表示请求耗时）和静态文本。参数还可以包含条件值和特殊格式选项，以增强日志的详细程度。 此外，一旦定义了日志格式，就可以在 'access_log' 指令中引用该格式，'access_log' 控制日志的写入位置。在单个 NGINX 配置中可以定义多个日志格式，从而为各种日志场景提供灵活性。

配置示例

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

access_log /var/log/nginx/access.log main;