Nginx bị lỗi 504 Gateway Timeout khi xử lý file upload lớn: Nguyên nhân và cách khắc phục

Bối cảnh sự cố 504 Gateway Timeout#

Khách hàng của bạn phản ánh: "Khi upload file tài liệu hoặc video dung lượng khoảng 150MB lên hệ thống, sau khi chờ khoảng 1 phút thì màn hình báo lỗi 504 Gateway Timeout của Nginx".

Lỗi 504 Gateway Timeout xảy ra khi Nginx (đóng vai trò là Reverse Proxy) chờ phản hồi từ upstream backend server (Node.js, Go, PHP-FPM...) nhưng quá thời gian giới hạn (timeout) mà backend vẫn chưa xử lý xong.

4 thông số Nginx bắt buộc phải cấu hình lại#

Mặc định, các thông số timeout của Nginx thường được đặt ở mức 60 giây và kích thước body bị giới hạn ở 1MB (client_max_body_size 1M).

Dưới đây là cấu hình hoàn chỉnh trong khối server hoặc location:

server {
    listen 80;
    server_name api.topdev.com.vn;

    # 1. Cho phép upload file lên tới 200MB
    client_max_body_size 200M;

    location /api/v1/upload {
        proxy_pass http://backend_upstream;
        proxy_http_version 1.1;

        # 2. Tăng thời gian chờ đọc và gửi dữ liệu tới upstream
        proxy_connect_timeout 300s;
        proxy_send_timeout    300s;
        proxy_read_timeout    300s;
        send_timeout          300s;

        # 3. Tránh việc Nginx ghi tạm file vào đĩa gây chậm
        proxy_request_buffering off;
        
        # 4. Giữ nguyên thông tin IP thực của client
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Đừng quên cấu hình timeout ở phía Backend!#

Nhiều dev chỉ sửa Nginx mà quên mất backend cũng có timeout riêng:

• Node.js (Express/Fastify): Mặc định server.timeout hoặc keepAliveTimeout.
• Go http.Server: Cần kiểm tra ReadTimeout và WriteTimeout.

// Tăng timeout cho Node.js server
const server = app.listen(3000);
server.setTimeout(300000); // 300 giây

Giải pháp kiến trúc lâu dài: Presigned URL#

Với các file lớn (>50MB), giải pháp tối ưu nhất là không bao giờ đẩy luồng dữ liệu file đi qua Nginx và Backend server. Hãy cho frontend xin Presigned URL của S3 / Cloudflare R2 và upload trực tiếp từ trình duyệt lên Storage!

Góc thảo luận#

Anh em đang cho upload file trực tiếp qua backend hay dùng Presigned URL của Cloud Storage?

Xem thêm nội dung liên quan:

• Học kiến trúc hệ thống và Cloud
• Review công cụ quản trị server