Opened 3 weeks ago

Last modified 2 weeks ago

#2438 accepted task

Improve fastcgi_cache_key documentation

Reported by: Denis Owned by:
Priority: minor Milestone:
Component: documentation Version:
Keywords: fastcgi_cache_key Cc:
uname -a: Linux ХХХ 5.4.0-137-generic #154-Ubuntu SMP Thu Jan 5 17:03:22 UTC 2023 x86_64 x86_64 x86_64 GNU/Linux
nginx -V: nginx version: nginx/1.18.0 (Ubuntu)
built with OpenSSL 1.1.1f 31 Mar 2020 (running with OpenSSL 1.1.1k 25 Mar 2021)
TLS SNI support enabled
configure arguments: --with-cc-opt='-g -O2 -fdebug-prefix-map=/build/nginx-lUTckl/nginx-1.18.0=. -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -fPIC' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=/var/log/nginx/error.log --lock-path=/var/lock/nginx.lock --pid-path=/run/nginx.pid --modules-path=/usr/lib/nginx/modules --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-debug --with-compat --with-pcre-jit --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_v2_module --with-http_dav_module --with-http_slice_module --with-threads --with-http_addition_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_image_filter_module=dynamic --with-http_sub_module --with-http_xslt_module=dynamic --with-stream=dynamic --with-stream_ssl_module --with-mail=dynamic --with-mail_ssl_module

Description

Сразу извиняюсь что не на английском, быстрее зарепорчу на родном языке.

В документации к директивам fastcgi_cache_key и proxy_cache_key не указана одна особенность: для ключа лучше использовать, в том числе и переменную $request_method, т.к. по дефолту:

fastcgi_cache_methods GET HEAD;

proxy_cache_methods GET HEAD;

означает что, в случае использования чего-то вроде (скопировал из доки):

fastcgi_cache_key localhost:9000$request_uri;

proxy_cache_key $scheme$proxy_host$uri$is_args$args;

и запросе HEAD-методом будет закеширован пустой ответ (без контента), который будет отдаваться nginx'ом и в GET-запросе. (Конечно, если бэкенд далее поддерживает HEAD запросы и обрабатывает их правильным образом)

Я столкнулся с этой неочевидной штукой на своих серверах, раскопал даже чью-то заметку на этот счет: https://www.claudiokuenzler.com/blog/705/empty-blank-page-nginx-fastcgi-cache-head-get

Думаю, стоит указать эту особенность в документации к директивам fastcgi_cache_key/proxy_cache_key.

PS: могу ли я прислать merge request для документации? Смущает что нужно прислать в merge request перевод сразу на нескольких языках.

Change History (2)

comment:1 by Denis, 2 weeks ago

Любопытно, что для proxy_cache существует директива proxy_cache_convert_head (https://nginx.org/ru/docs/http/ngx_http_proxy_module.html#proxy_cache_convert_head), а для fastcgi_cache такого нет.

comment:2 by Maxim Dounin, 2 weeks ago

Keywords: fastcgi_cache_key added; cache proxy_cache fastcgi_cache removed
Status: newaccepted
Summary: При использовании fastcgi_cache/proxy_cache и запросе HEAD кешируется пустой ответImprove fastcgi_cache_key documentation
Version: 1.18.x

При проксировании с кэшированием nginx автоматически меняет метод запроса к бэкенду с HEAD на GET (если это не запрещено явно с помощью директивы proxy_cache_convert_head), и соответственно использовать $request_method в ключе кэширования не нужно. В частности, в proxy_cache_key по умолчанию метод запроса не указывается, и к каким-либо негативным последствиям это приводить не может.

В случае FastCGI (и других CGI-like протоколов, scgi и uwsgi) поведение отличается, так как в общем случае приложения игнорируют метод запроса и всегда возвращают полный ответ. Кроме того, передаваемое на бэкенд значение REQUEST_METHOD не контролируется nginx'ом явно, а задаётся с помощью директив fastcgi_param в конфигурации (как, впрочем, и остальные передаваемые на бэкенд значения). Соответственно, nginx не пытается предлагать каких-либо значений для fastcgi_cache_key по умолчанию, а вместо этого ожидает, что в конфигурации будет указан ключ кэширования, подходящий для конкретной конфигурации и учитывающий поведение конкретных бэкендов.

Документация fastcgi_cache_key (а равно scgi_cache_key, uwsgi_cache_key) сейчас не пытается описывать, как правильно составить ключ кэширования, а лишь приводит пример использования директивы. Возможно, добавить в описания упомянутых директив какие-то рекомендации по правильному выбору ключа кэширования и/или более полные примеры, в том числе с $request_method, имеет смысл, это должно снять некоторое количество вопросов.

Что до патчей на документацию, то их, как и патчи на код, можно присылать в список nginx-devel@, общие рекомендации тут.

Note: See TracTickets for help on using tickets.