Виправлення помилок 502 Bad Gateway у Docker Compose під час завантаження великих файлів у FastAPI

Усунення помилок Docker 502 під час завантаження файлу

Під час роботи з FastAPI, Docker Compose та завантаженням файлів іноді можуть виникати помилки, особливо під час завантаження великих файлів. Поширеною проблемою, про яку повідомляють розробники, є a 502 Поганий шлюз помилка, особливо під час спроби завантажити більші файли, наприклад архів .7z розміром 120 МБ.

Цей тип помилки може бути наслідком багатьох причин, зокрема тайм-аутів сервера, обмежень конфігурації в Docker або навіть проблем зі зворотним проксі-сервером, подібних до тих, що виникають у Nginx. Розуміння першопричини є ключовим для вирішення цих постійних проблем із завантаженням.

Якщо ви використовуєте інтерфейс Swagger від FastAPI для завантажень, ви можете помітити, що програма намагається оновити або аварійно завершувати роботу під час процесу, особливо при завантаженні менших файлів. Ці симптоми можуть призвести до непослідовної поведінки та вимагати подальшого налагодження.

У цьому посібнику ми розглянемо, що може спричиняти ці помилки, зокрема обмеження розміру файлу, неправильні конфігурації зворотного проксі-сервера або інші проблеми серверної частини вашого Docker Compose середовище. Ми також розглянемо можливі рішення для запобігання повторюваним помилкам під час завантаження файлів у програмах FastAPI.

Розуміння рішення для помилки 502 у FastAPI з Docker Compose

Надані раніше сценарії спрямовані на вирішення проблеми завантаження великих файлів, зокрема архіву .7z розміром 120 МБ, через FastAPI та Docker Compose. Одним із основних елементів є використання фонові завдання у FastAPI. Використовуючи background_tasks.add_task() процес вилучення файлу виконується асинхронно, тобто не блокується основний цикл запиту. Це важливо для запобігання помилкам тайм-ауту під час обробки великих файлів. Без цієї функції FastAPI намагався б обробити все в основному потоці, імовірно, спричиняючи помилку 502 Bad Gateway, якщо сервер надто довго відповідає.

Іншою ключовою особливістю є використання shutil.copyfileobj() метод, який ефективно записує завантажений файл на диск. Ця функція розроблена для великих файлів, оскільки вона зчитує з файлового потоку частинами, запобігаючи перевантаженню пам’яті. Функція UUID у Python гарантує, що кожен файл отримує унікальне ім’я для запобігання перезапису, що важливо в середовищах, де кілька користувачів можуть завантажувати файли одночасно. Якщо ім’я файлу не є унікальним, у вас можуть виникнути проблеми з пошкодженням файлу або конфліктами під час процесу завантаження.

Файл Docker Compose налаштовано на подовження часу очікування для сервера FastAPI за допомогою uvicorn --timeout-keep-alive варіант. Ця команда гарантує, що сервер може підтримувати з’єднання з клієнтом довше, навіть якщо завантаження великих файлів займає значний час. Встановивши значення 300 секунд (або 5 хвилин), це запобігає передчасному розриву з’єднання Docker, що часто призводить до помилки 502. Це також допомагає підтримувати стабільність під час тривалих процесів.

Нарешті, конфігурація Nginx відіграє вирішальну роль у дозволі завантаження більших файлів шляхом налаштування client_max_body_size директива до 200 Мб. Ця зміна гарантує, що Nginx може приймати файли, розмір яких перевищує стандартний ліміт у 1 Мб. У поєднанні з proxy_read_timeout Директива, яка дозволяє серверу довше чекати відповіді серверного сервера, ці параметри допомагають уникнути помилок, які виникають через повільну або велику передачу файлів. Разом ці оптимізації гарантують, що ваша програма FastAPI зможе обробляти завантаження великих файлів без збоїв або спричинення помилок 502 у середовищах 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

Подолання проблем із розміром файлу у FastAPI за допомогою Docker Compose

Один важливий аспект, який може вплинути на завантаження файлів у Docker Compose середовищ — це обробка обмежень сервера для пам’яті та тайм-аутів. Окрім коригування часу очікування сервера та конфігурації зворотного проксі-сервера, на завантаження файлів також можуть впливати обмеження системного рівня, наприклад доступна пам’ять і ресурси ЦП. Під час завантаження великого файлу, як-от архіву .7z розміром 120 МБ, сервер може зіткнутися з недостатньою пам’яттю або високим завантаженням ЦП, що призведе до збою або оновлення в середині процесу. Ситуація може ще більше посилюватися, коли кілька користувачів завантажують файли одночасно.

Іншим важливим моментом є те, що продуктивність завантаження файлів може погіршитися через саму контейнеризацію. Докер ізолює ресурси для кожного контейнера, тобто якщо контейнер не налаштований належним чином, він може не мати достатньо ресурсів для ефективної обробки великих файлів. Це може призвести до оновлення або збою сервера під час обробки навіть менших файлів, таких як діапазон 16-17 МБ, який ви мали. Важливо переконатися, що ваші контейнери Docker мають необхідні ресурси ЦП і пам’яті, а обмеження слід перевіряти в реальних сценаріях.

Нарешті, обробку запитів FastAPI можна оптимізувати за допомогою методів потокової передачі, які дозволяють завантажувати файли з фрагментами. Це допоможе обробляти великі файли, не перевантажуючи пам’ять сервера. У поєднанні з належною конфігурацією розподілу ресурсів Nginx, Uvicorn і Docker потокова передача може зробити ваш API більш надійним. Включення цих додаткових оптимізацій забезпечує кращу стабільність під час роботи з великими або одночасними завантаженнями файлів у робочих середовищах.