Gestionarea Timeout-urilor în Reverse Proxy: proxy_connect_timeout, proxy_read_timeout și proxy_send_timeout în Nginx

În arhitecturile moderne în care Nginx acționează ca Reverse Proxy în fața unor aplicații backend (Node.js, Python FastAPI, PHP-FPM, microservicii AI), una dintre cele mai frecvente erori întâlnite este 504 Gateway Timeout. Aceasta apare atunci când serverul upstream nu răspunde în intervalul maxim configurat implicit în Nginx (60 de secunde).

Pentru a gestiona corect cererile de lungă durată (generare de rapoarte PDF, interogări LLM cu streaming sau conexiuni WebSockets), Nginx oferă trei directive esențiale de timeout:

• proxy_connect_timeout: Timpul maxim alocat pentru stabilirea conexiunii TCP cu serverul upstream (implicit 60s).
• proxy_send_timeout: Intervalul maxim admis între două operații succesive de scriere a cererii către serverul upstream.
• proxy_read_timeout: Timpul maxim pe care Nginx îl așteaptă între două operații succesive de citire a răspunsului de la backend.

location /api/ai/stream {
    proxy_pass http://ai_backend_cluster;
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # Extinderea timeout-urilor pentru streaming de răspunsuri mari
    proxy_connect_timeout 30s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    # Dezactivarea buffering-ului pentru afișarea instantanee a tokenilor (SSE)
    proxy_buffering off;
    proxy_cache off;
}

Setarea proxy_buffering off este obligatorie în aplicațiile de tip Server-Sent Events (SSE) pentru a preveni reținerea fragmentelor în bufferul Nginx.