ajp: 支持 AJP 协议代理与 NGINX
安装
您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：
- RedHat Enterprise Linux 7、8、9 和 10
- CentOS 7、8、9
- AlmaLinux 8、9
- Rocky Linux 8、9
- Amazon Linux 2 和 Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-ajp
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-ajp
通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用该模块：
load_module modules/ngx_http_ajp_module.so;
本文档描述了 nginx-module-ajp v0.3.6，于 2026 年 2 月 13 日发布。
http {
upstream tomcats {
server 127.0.0.1:8009;
keepalive 10;
}
server {
listen 80;
location / {
ajp_keep_conn on;
ajp_pass tomcats;
}
}
}
描述
使用此模块，Nginx 可以直接连接到 AJP 端口。编写这些模块的动机是 Nginx 的高性能和稳健性。
指令
ajp_buffers
语法： ajp_buffers the_number is_size;
默认值： ajp_buffers 8 4k/8k;
上下文： http, server, location
该指令指定了从 AJP 服务器获取的响应将被读取的缓冲区的数量和大小。默认情况下，一个缓冲区的大小等于页面的大小。根据平台，这个大小可能是 4K、8K 或 16K。
ajp_buffer_size
语法： ajp_buffer_size the_size;
默认值： ajp_buffer_size 4k/8k;
上下文： http, server, location
该指令设置了将读取的响应第一部分的缓冲区大小。
在响应的这一部分中，通常包含小的响应头。
默认情况下，缓冲区大小等于指令 ajp_buffers 中一个缓冲区的大小；但是，可以将其设置为更小的值。
ajp_cache
语法： ajp_cache zone;
默认值： off
上下文： http, server, location
该指令指定了实际用于缓存的共享内存的名称。可以在多个地方使用相同的区域。您必须首先设置 ajp_cache_path。
ajp_cache_key
语法： ajp_cache_key line;
默认值： none
上下文： http, server, location
该指令指定了缓存键中包含的信息，例如：
ajp_cache_key "$host$request_uri$cookie_user";
请注意，默认情况下，服务器的主机名不包含在缓存键中。如果您在网站的不同位置使用子域名，则需要将其包含在内，例如通过将缓存键更改为类似于：
ajp_cache_key "$scheme$host$request_uri";
ajp_cache_methods
语法： ajp_cache_methods [GET HEAD POST];
默认值： ajp_cache_methods GET HEAD;
上下文： main,http,location
GET/HEAD 是语法糖，即使您只设置：
ajp_cache_methods POST;
也无法禁用 GET/HEAD。
ajp_cache_min_uses
语法： ajp_cache_min_uses n;
默认值： ajp_cache_min_uses 1;
上下文： http, server, location
设置在响应被缓存之前的请求数量。
ajp_cache_path
语法： ajp_cache_path /path/to/cache [levels=m:n keys_zone=name:time inactive=time clean_time=time];
默认值： none
上下文： http, server, location
该指令设置缓存路径和其他缓存参数。缓存的数据存储在文件中。缓存中的键和文件名是代理 URL 的 md5。Levels 参数设置缓存中的子目录数量，例如：
ajp_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
文件名将类似于：
/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c
ajp_cache_use_stale
语法： ajp_cache_use_stale [updating|error|timeout|invalid_header|http_500];
默认值： ajp_cache_use_stale off;
上下文： http, server, location
如果在与 AJP 服务器交互时发生错误，可以使用过期的缓存响应。该指令确定在何种情况下允许这样做。指令的参数与 ajp_next_upstream 指令的参数匹配。
此外，更新参数允许在当前正在更新时使用过期的缓存响应。这可以在更新缓存数据时最小化对 AJP 服务器的访问次数。
ajp_cache_valid
语法： ajp_cache_valid [http_error_code|time];
默认值： none
上下文： http, server, location
为不同的响应代码设置缓存时间。例如，以下指令：
ajp_cache_valid 200 302 10m;
ajp_cache_valid 404 1m;
为响应代码 200 和 302 设置 10 分钟的缓存，为响应代码 404 设置 1 分钟的缓存。
如果只指定缓存时间：
ajp_cache_valid 5m;
那么只缓存 200、301 和 302 响应。
此外，可以使用 any 参数指定缓存任何响应：
ajp_cache_valid 200 302 10m;
ajp_cache_valid 301 1h;
ajp_cache_valid any 1m;
缓存的参数也可以直接在响应头中设置。这比使用指令设置的缓存时间具有更高的优先级。“X-Accel-Expires”头字段设置响应的缓存时间（以秒为单位）。值 0 禁用缓存响应。如果值以 @ 前缀开头，则设置为自 Epoch 起的绝对时间（以秒为单位），在此之前响应可以被缓存。如果头中不包含 “X-Accel-Expires” 字段，则可以在 “Expires” 或 “Cache-Control” 头字段中设置缓存参数。如果头中包含 “Set-Cookie” 字段，则该响应将不会被缓存。可以使用 ajp_ignore_headers 指令禁用对一个或多个这些响应头字段的处理。
ajp_connect_timeout
语法： ajp_connect_timeout time;
默认值： ajp_connect_timeout 60s;
上下文： http, server, location
该指令为与上游服务器的连接分配超时时间。需要注意的是，此超时时间不能超过 75 秒。
这不是服务器返回页面的时间，这是 ajp_read_timeout 语句。如果您的上游服务器正常，但挂起（例如，它没有足够的线程来处理您的请求，因此将您放入连接池中以稍后处理），那么此语句将无效，因为与服务器的连接已经建立。
ajp_header_packet_buffer_size
语法： ajp_header packet_buffer_size;
默认值： ajp_header_packet_buffer_size 8k;
上下文： http, server, location
设置转发请求数据包的缓冲区大小。范围为 (0, 2^16)。
ajp_headers_hash_bucket_size
语法： ajp_headers_hash_bucket_size size;
默认值： ajp_headers_hash_bucket_size 64;
上下文： http, server, location
设置 ajp_hide_header 和 ajp_set_header 指令使用的哈希表的桶大小。
ajp_headers_hash_max_size
语法： ajp_headers_hash_max_size size;
默认值： ajp_headers_hash_max_size 512;
上下文： http, server, location
设置 ajp_hide_header 和 ajp_set_header 指令使用的哈希表的最大大小。
ajp_hide_header
语法： ajp_hide_header name;
上下文： http, server, location
默认情况下，Nginx 不会将 AJP 过程中的“Status”和“X-Accel-...”头返回给客户端。可以使用此指令隐藏其他头。
如果必须提供“Status”和“X-Accel-...”头，则需要使用指令 ajp_pass_header 强制将它们返回给客户端。
ajp_ignore_headers
语法： ajp_ignore_headers name [name ...];
默认值： none
上下文： http, server, location
该指令（0.7.54+）禁止处理代理服务器响应中的头行。
可以指定字符串，例如 "X-Accel-Redirect"、"X-Accel-Expires"、"Expires" 或 "Cache-Control"。
ajp_ignore_client_abort
语法： ajp_ignore_client_abort on|off;
默认值： ajp_ignore_client_abort off;
上下文： http, server, location
该指令确定在客户端中止请求时，当前对 AJP 服务器的请求是否必须被中止。
ajp_intercept_errors
语法： ajp_intercept_errors on|off;
默认值： ajp_intercept_errors off;
上下文： http, server, location
该指令确定是否将 4xx 和 5xx 错误转发回客户端，或允许 Nginx 使用指令 error_page 进行响应。
注意：您需要明确为此定义 error_page 处理程序，以使其有效。正如 Igor 所说，“如果没有自定义处理程序，nginx 不会拦截错误，它不会显示其默认页面。这允许拦截某些错误，同时将其他错误原样传递。”
ajp_keep_conn
语法： ajp_keep_conn on|off;
默认值： ajp_keep_conn off;
上下文： http, server, location
该指令确定是否与后端服务器保持连接。
ajp_next_upstream
语法： ajp_next_upstream [error|timeout|invalid_header|http_500|http_502|http_503|http_504|http_404|off];
默认值： ajp_next_upstream error timeout;
上下文： http, server, location
该指令确定请求在何种情况下将被传递到下一个服务器：
- error — 在连接到服务器、向其发送请求或读取其响应时发生错误；
- timeout — 在与服务器连接、传输请求或读取响应时发生超时；
- invalid_header — 服务器返回了空或不正确的答案；
- http_500 — 服务器返回代码为 500 的答案；
- http_502 — 服务器返回代码为 502 的答案；
- http_503 — 服务器返回代码为 503 的答案；
- http_504 — 服务器返回代码为 504 的答案；
- http_404 — 服务器返回代码为 404 的答案；
- off — 禁止请求传递到下一个服务器。仅在没有任何内容传递给客户端的情况下才能将请求传递到下一个服务器——也就是说，如果在请求传输的过程中发生错误或超时，则无法在不同的服务器上重试当前请求。
ajp_max_data_packet_size
语法： ajp_max_data_packet_size size;
默认值： ajp_max_data_packet_size 8k;
上下文： http, server, location
设置 AJP 数据包的最大大小。范围为 [8k, 2^16]；
ajp_max_temp_file_size
语法： ajp_max_temp_file_size size;
默认值： ajp_max_temp_file_size 1G;
上下文： http, server, location, if
当内容大于代理缓冲区时，临时文件的最大大小。如果文件大于此大小，它将从上游服务器同步提供，而不是缓冲到磁盘。
如果 ajp_max_temp_file_size 等于零，则将禁用临时文件的使用。
ajp_pass
语法： ajp_pass ajp-server
默认值： none
上下文： location, if in location
该指令分配 AJP 服务器正在监听的端口或套接字。端口可以单独指示，也可以作为地址和端口，例如：
ajp_pass localhost:9000;
使用 Unix 域套接字：
ajp_pass unix:/tmp/ajp.socket;
您还可以使用上游块。
upstream backend {
server localhost:1234;
}
ajp_pass backend;
ajp_secret
语法： ajp_secret ajpsecret
默认值： none
该指令分配 AJP 服务器的密钥。
ajp_pass_header
语法： ajp_pass_header name;
上下文： http, server, location
允许将特定的头字段从 AJP 服务器传递给客户端。
ajp_pass_request_headers
语法： ajp_pass_request_headers [ on | off ];
默认值： ajp_pass_request_headers on;
上下文： http, server, location
允许将请求头字段从客户端传递到服务器。
ajp_pass_request_body
语法： ajp_pass_request_body [ on | off ] ;
默认值： ajp_pass_request_body on;
上下文： http, server, location
允许将请求体从客户端传递到服务器。
ajp_read_timeout
语法： ajp_read_timeout time;
默认值： ajp_read_timeout_time 60
上下文： http, server, location
该指令设置上游等待 AJP 进程发送数据的时间。如果您有长时间运行的 AJP 进程，在完成处理之前不会产生输出，请更改此指令。如果您在错误日志中看到上游超时错误，请将此参数增加到更合适的值。
ajp_send_lowat
语法： ajp_send_lowat [ on | off ];
默认值： ajp_send_lowat off;
上下文： http, server, location, if
该指令设置 SO_SNDLOWAT。此指令仅在 FreeBSD 上可用。
ajp_send_timeout
语法： ajp_send_timeout time;
默认值： ajp_send_timeout 60;
上下文： http, server, location
该指令为向上游服务器传输请求分配超时时间。超时不是针对整个请求传输，而仅在两个写操作之间。如果在此时间后，上游服务器未接收新数据，则 nginx 将关闭连接。
ajp_set_header
语法： ajp_set_header name value;
上下文： http, server, location
允许重新定义或附加传递给 AJP 服务器的请求头字段。值可以包含文本、变量及其组合。
这些指令在当前级别上仅在没有定义 ajp_set_header 指令的情况下从上一个配置级别继承。
ajp_store
语法： ajp_store [on | off | path] ;
默认值： ajp_store off;
上下文： http, server, location
该指令设置上游文件存储的路径。参数“on”根据指令 alias 或 root 中指定的路径保留文件。参数“off”禁止存储。此外，可以通过包含变量的行明确指定路径名称：
ajp_store /data/www$original_uri;
文件的修改时间将设置为响应中“Last-Modified”头的日期。为了能够在此目录中保存文件，路径必须位于由指令 ajp_temp_path 指定的临时文件目录下。
该指令可用于为动态输出的后端创建本地副本，这些输出不经常更改，例如：
location /images/ {
root /data/www;
error_page 404 = @fetch;
}
location @fetch {
internal;
ajp_pass backend;
ajp_store on;
ajp_store_access user:rw group:rw all:r;
ajp_temp_path /data/temp;
root /data/www;
}
需要明确的是，ajp_store 不是缓存，而是按需镜像。
ajp_store_access
语法： ajp_store_access users:permissions [users:permission ...];
默认值： ajp_store_access user:rw;
上下文： http, server, location
该指令分配创建的文件和目录的权限，例如：
ajp_store_access user:rw group:rw all:r;
如果为组或所有人分配了任何权限，则不需要为用户分配权限：
ajp_store_access group:rw all:r;
ajp_temp_path
语法： ajp_temp_path dir-path [ level1 [ level2 [ level3 ] ] ] ;
默认值： $NGX_PREFIX/ajp_temp
上下文： http, server, location
该指令的作用类似于 client_body_temp_path，用于指定将大型代理请求缓冲到文件系统的位置。
ajp_temp_file_write_size
语法： ajp_temp_file_write_size size;
默认值： ajp_temp_file_write_size ["#ajp buffer size"] * 2;
上下文： http, server, location, if
设置在写入时将刷新到 ajp_temp_path 的数据量。可以用于防止工作进程在排队数据时阻塞太长时间。
已知问题
*
GitHub
您可以在 nginx-module-ajp 的 GitHub 仓库 中找到此模块的其他配置提示和文档。