Memperbaiki 502 Kesalahan Gateway Buruk di Docker Compose Saat Mengunggah File Besar ke FastAPI

Memecahkan Masalah Kesalahan Docker 502 selama Pengunggahan File

Saat bekerja dengan FastAPI, Docker Compose, dan pengunggahan file, terkadang Anda mungkin mengalami kesalahan, terutama saat mengunggah file berukuran besar. Masalah umum yang dilaporkan oleh pengembang adalah a 502 Gerbang Buruk kesalahan, terutama saat mencoba mengunggah file yang lebih besar, seperti arsip .7z berukuran 120 MB.

Jenis kesalahan ini dapat disebabkan oleh berbagai penyebab, termasuk waktu tunggu server habis, batasan konfigurasi di Docker, atau bahkan masalah reverse proxy seperti yang terjadi pada Nginx. Memahami akar permasalahan adalah kunci untuk menyelesaikan masalah pengunggahan yang terus-menerus ini.

Jika Anda menggunakan UI Swagger FastAPI untuk unggahan, Anda mungkin memperhatikan aplikasi mencoba menyegarkan atau mogok selama proses, terutama dengan unggahan file yang lebih kecil. Gejala ini dapat menyebabkan perilaku tidak konsisten dan memerlukan proses debug lebih lanjut.

Dalam panduan ini, kami akan mendalami penyebab kesalahan ini, termasuk batas ukuran file, kesalahan konfigurasi proxy terbalik, atau masalah backend lainnya di perangkat Anda. Penulisan Docker lingkungan. Kami juga akan mengeksplorasi solusi potensial untuk mencegah kesalahan berulang saat menangani pengunggahan file di aplikasi FastAPI.

Memahami Solusi Error 502 di FastAPI dengan Docker Compose

Skrip yang disediakan sebelumnya bertujuan untuk mengatasi masalah pengunggahan file besar, khususnya arsip .7z 120MB, melalui FastAPI dan Docker Compose. Salah satu elemen intinya adalah penggunaan tugas latar belakang di FastAPI. Dengan memanfaatkan latar belakang_tugas.tambahkan_tugas() perintah, proses ekstraksi file ditangani secara asinkron, artinya tidak memblokir siklus permintaan utama. Ini penting untuk mencegah kesalahan batas waktu saat memproses file besar. Tanpa fitur ini, FastAPI akan mencoba menangani semua yang ada di thread utama, kemungkinan besar menyebabkan kesalahan 502 Bad Gateway jika server membutuhkan waktu terlalu lama untuk merespons.

Fitur utama lainnya adalah penggunaan shutil.copyfileobj() metode, yang secara efisien menulis file yang diunggah ke disk. Fungsi ini dirancang untuk file besar karena membaca dari aliran file dalam beberapa bagian, mencegah kelebihan memori. Fungsi UUID di Python memastikan bahwa setiap file mendapatkan nama unik untuk mencegah penimpaan, yang penting dalam lingkungan di mana banyak pengguna dapat mengunggah file secara bersamaan. Jika nama file tidak unik, Anda mungkin menghadapi masalah kerusakan file atau konflik selama proses pengunggahan.

File Docker Compose dikonfigurasi untuk memperpanjang waktu tunggu server FastAPI menggunakan uvicorn --timeout-tetap-hidup pilihan. Perintah ini memastikan bahwa server dapat mempertahankan koneksi dengan klien lebih lama, bahkan ketika file besar memerlukan waktu yang lama untuk diunggah. Dengan menyetelnya ke 300 detik (atau 5 menit), hal ini mencegah Docker menutup koneksi sebelum waktunya, yang sering kali mengakibatkan kesalahan 502. Ini juga membantu menjaga stabilitas selama proses yang berjalan lama.

Terakhir, konfigurasi Nginx memainkan peran penting dalam memungkinkan pengunggahan file yang lebih besar dengan mengatur klien_max_body_size arahan ke 200MB. Perubahan ini memastikan Nginx dapat menerima file yang lebih besar dari batas default 1 MB. Ditambah dengan proxy_read_timeout arahan, yang memungkinkan server menunggu lebih lama untuk respons server backend, pengaturan ini membantu menghindari kesalahan yang berasal dari transfer file yang lambat atau besar. Bersama-sama, pengoptimalan ini memastikan bahwa aplikasi FastAPI Anda dapat menangani unggahan file besar tanpa error atau menyebabkan kesalahan 502 di lingkungan Docker Compose.

# This FastAPI function handles large file uploads using background tasks.
from fastapi import FastAPI, UploadFile, File, BackgroundTasks, HTTPException, status
import os, shutil, uuid
from fastapi.responses import JSONResponse
app = FastAPI()
UPLOAD_DIR = "/app/uploads"
@app.post("/7zip/")
async def upload_7zip(background_tasks: BackgroundTasks, archive_file: UploadFile = File(...)):
    # Check if the uploaded file is a valid .7z file
    if not archive_file.filename.endswith(".7z"):
        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Please upload a valid 7z file.")
    # Generate a unique filename to prevent overwrites
    archive_filename = f"{uuid.uuid4()}_{archive_file.filename}"
    archive_path = os.path.join(UPLOAD_DIR, archive_filename)
    try:
        # Save the uploaded file to the server
        with open(archive_path, "wb") as buffer:
            shutil.copyfileobj(archive_file.file, buffer)
        # Add file extraction to background tasks to avoid timeouts
        background_tasks.add_task(extract_file, archive_path)
        return JSONResponse({"message": "File uploaded successfully, extraction is in progress."})
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"An error occurred while processing the 7z file: {str(e)}")
# Background task to extract files
def extract_file(archive_path: str):
    # Placeholder function for extracting 7z files
    pass

# Adjusting Nginx configuration to allow larger file uploads
server {
    listen 80;
    server_name example.com;
    location / {
        proxy_pass http://app:8000;
        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;
    }
    # Set the maximum allowed upload size to 200MB
    client_max_body_size 200M;
    proxy_read_timeout 300;
}

# Docker Compose file with increased timeout to avoid 502 errors
version: '3'
services:
  app:
    container_name: fastapi_app
    build: .
    command: bash -c "uvicorn main:app --host 0.0.0.0 --port 8000 --timeout-keep-alive=300"
    ports:
      - "8000:8000"
    volumes:
      - ./uploads:/app/uploads
    depends_on:
      - db
    restart: always
    environment:
      - FASTAPI_ENV=production
  db:
    image: postgres
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass

Mengatasi Masalah Ukuran File di FastAPI dengan Docker Compose

Salah satu aspek penting yang dapat mempengaruhi upload file di Penulisan Docker lingkungan adalah penanganan batas server untuk memori dan batas waktu. Selain penyesuaian waktu tunggu server dan konfigurasi proksi terbalik, pengunggahan file juga dapat dipengaruhi oleh batasan tingkat sistem, seperti memori yang tersedia dan sumber daya CPU. Saat mengunggah file besar, seperti arsip .7z 120MB, server mungkin mengalami kehabisan memori atau penggunaan CPU yang tinggi, sehingga menyebabkan crash atau penyegaran di tengah proses. Hal ini dapat diperburuk ketika beberapa pengguna mengunggah file secara bersamaan.

Hal penting lainnya adalah kinerja unggahan file dapat menurun karena containerisasi itu sendiri. Buruh pelabuhan mengisolasi sumber daya per kontainer, artinya kecuali dikonfigurasi dengan benar, sebuah kontainer mungkin tidak memiliki sumber daya yang cukup untuk menangani file besar secara efisien. Hal ini dapat menyebabkan server melakukan penyegaran atau crash saat menangani file yang lebih kecil lagi, seperti rentang 16-17 MB yang Anda alami. Penting untuk memastikan bahwa container Docker Anda memiliki alokasi sumber daya CPU dan memori yang diperlukan, dan batasannya harus diuji dalam skenario dunia nyata.

Terakhir, penanganan permintaan FastAPI dapat dioptimalkan menggunakan teknik streaming, yang memungkinkan pengunggahan file dalam potongan. Ini akan membantu menangani file yang lebih besar tanpa membebani memori server. Dikombinasikan dengan konfigurasi alokasi sumber daya Nginx, Uvicorn, dan Docker yang tepat, streaming dapat membuat API Anda lebih tangguh. Menggabungkan pengoptimalan tambahan ini memastikan stabilitas yang lebih baik ketika menangani unggahan file besar atau bersamaan di lingkungan produksi.