blog

Nginx proksisi yordamida xato sahifalarini birlashtirish

NEXTREE.

• 6 min read
Nginx proksisi yordamida xato sahifalarini birlashtirish

1. Muammo ta’rifi: Izchil bo‘lmagan xato ekranlari va xavfsizlik xatarlari

Korporativ va mikroxizmatli veb-arxitekturalarda xatolik yuz berganda, xato kelib chiqqan qatlamga qarab turli ekranlar ko‘rsatiladi. Old qismda Nginx reverse proxy, uning ortida esa Tomcat ichiga o‘rnatilgan Spring Boot ilovasi ishlaydigan muhitda quyidagi parchalangan ekranlar paydo bo‘lishi mumkin.

  • Spring Boot Whitelabel xato sahifasi: HTTP holat kodi, vaqt tamg‘asi va xato xabari brauzerda xom ko‘rinishda ko‘rsatiladi.

  • Apache Tomcat standart xato sahifasi: Servlet konteyneri darajasida 404/500 xatosi yuz berganda, Tomcat’ga xos kulrang ekran paydo bo‘ladi.

  • Nginx standart xato sahifasi: Backend ilovasi ishlamay qolganda yoki vaqt tugaganda, qo‘pol 502 Bad Gateway / 504 Gateway Time-out matnli ekrani ko‘rsatiladi.

Bu parchalanish nafaqat foydalanuvchi tajribasiga (UX) zarar yetkazadi, balki xavfsizlik zaifliklarini (CWE-209: Information Exposure) ham keltirib chiqaradi. Tomcat versiyasi haqidagi ma’lumotlar yoki framework stack trace’lari oshkor bo‘ladigan Server Fingerprinting hujumchilarga tizim zaifliklarini tahlil qilish uchun ko‘rsatmalar beradi.

image1.pngimage2.png

Spring Boot xato sahifasi

image3.png

Apache Tomcat xato sahifasi

image4.png

Nginx xato sahifasi

2. Texnik cheklovlar: Spring Boot ichki qayta ishlashining cheklovlari

Spring Boot’ning @ExceptionHandler yoki ErrorController komponenti faqat ilova (JVM/Tomcat) jarayoni normal ishlayotgan va javob yaratishga qodir bo‘lganida ishlaydi.

Haqiqiy ishlab chiqarish muhitlarida ilova kodini hatto bajarib bo‘lmaydigan holatlarda jiddiy nosozliklar yuz beradi.

  • JVM OOM (Out of Memory) ishdan chiqishi: Heap xotirasi tugagani sababli jarayon majburan to‘xtatilganda (502 Bad Gateway)

  • Tomcat oqimlar havzasi / DB ulanishlar havzasining tugashi: Tomcat katta hajmdagi trafik sababli yangi ulanishlarni o‘rnata olmaganda (504 Gateway Time-out)

  • Nol to‘xtashli joylashtirish paytida rolling update uzilishi: Yangi konteyner ishga tushishidan oldingi qisqa vaqt oralig‘ida kelib tushadigan so‘rovlar

Ushbu infratuzilma darajasidagi nosozlik holatlarida Spring Boot kodi bajarila olmagani sababli Nginx’ning xom xato ekrani ko‘rsatiladi. Haqiqiy yuqori mavjudlikka ega xatolarni boshqarishga erishish uchun xatolarni boshqarish markazlashtirilishi kerak trafik uchun birinchi shlyuz bo‘lgan Nginx qatlamida.

3. Yechim dizayni: Nginx proxy_intercept_errors asosida markazlashtirilgan boshqaruv

Nginx’ni birinchi chiziqdagi xato boshqaruvchisiga aylantirishning asosiy mexanizmi proxy_intercept_errors direktivasidir. Ushbu direktiva yoqilganda, Upstream (Tomcat/Spring Boot) qaytargan HTTP javob kodi 300 yoki undan yuqori bo‘lsa, Nginx javob tanasini ushlab qoladi va uni ichki ravishda oldindan belgilangan error_page yo‘liga yo‘naltiradi.

  • Xavfsizlik izolyatsiyasi: Backendda qaysi istisno yuz berishidan qat’i nazar, javob tanasi bekor qilinadi va faqat Nginx’ning tozalangan statik fayli taqdim etiladi. Shu tariqa ichki ma’lumotlarning oshkor bo‘lishi oldi olinadi.

  • Infratuzilma darajasidagi zaxira mexanizmi: Spring Boot ishlayotgan yoki ishlamayotganidan qat’i nazar, izchil xizmat ma’lumotlari ekranini taqdim etadi.

  • To‘g‘ridan-to‘g‘ri kirishni bloklash: Ichki direktiva foydalanuvchilarning brauzer manzil satriga /error/500.html manzilini kiritib, unga bevosita kirishining oldini oladi.

4. Amaliy ishlab chiqarish nginx.conf konfiguratsiyasi misoli

Bu Tomcat va Spring Boot xatolarini ushlab qolib, ularni maxsus xato ekranlariga yo‘naltiradigan asosiy nginx.conf konfiguratsiyasi misolidir.

# 1. [Content Negotiation] 요청 헤더(Accept) 기반 응답 포맷 판별
#   React 비동기 API 요청(JSON)과 일반 웹 브라우징(HTML)을 구분합니다.
map $http_accept $error_response_type {
  default "html";
  ~*application/json "json";
  ~*text/json "json";
}

server {
    listen 80;
    server_name service.example.com;

    # 2. [핵심] 뒷단 WAS(Tomcat/Spring Boot)의 3xx/4xx/5xx 에러를 가로챕니다.
    proxy_intercept_errors on;

    # 3. HTTP 상태 코드별 내부 에러 디스패처로 라우팅
    error_page 404 = /handle_error_404;
    error_page 500 = /handle_error_500;
    error_page 502 = /handle_error_502;
    error_page 504 = /handle_error_504;

    # 기본 비즈니스 프록시 패스
    location / {
        proxy_pass http://backend_app;
        # WAS 장애 시 빠른 Nginx 에러 핸들러 전환을 위한 타임아웃
        proxy_connect_timeout 3s;
        proxy_read_timeout 10s;
    }

    # 4. [내부 디스패처] 헤더에 따라 JSON vs HTML 분기 반환
    #   internal 지시어로 외부 사용자의 직접 URL 호출을 차단합니다.
    location = /handle_error_500 {
        internal;
        if ($error_response_type = "json") {
            default_type application/json;
            return 500 '{"status": 500, "code": "INTERNAL_SERVER_ERROR", "message": "서버 오류가 발생했습니다."}';
        }
        rewrite ^ /error/500.html break;
    }

    # 5. [WAS 다운 대응] Spring Boot 프로세스 다운(OOM 등) 시 502 처리
    location = /handle_error_502 {
        internal;
        if ($error_response_type = "json") {
            default_type application/json;
            return 502 '{"status": 502, "code": "SERVICE_UNAVAILABLE", "message": "현재 서비스 점검 중입니다."}';
        }
        rewrite ^ /error/502.html break;
    }

    # 6. [정적 파일 격리] 커스텀 HTML 에러 페이지 서빙 (직접 접근 불가)
    location /error/ {
        internal;
        alias /usr/share/nginx/html/error/;
        add_header Cache-Control "no-store, no-cache, must-revalidate";
    }
}

Nginx.conf kodi misoli

5. Kengaytirilgan dizayn: React integratsiyasidagi oq ekran muammosi va uning yechimi

proxy_intercept_errors on; parametrini oddiy veb-sahifalar uchun shunchaki qo‘llash odatda normal ishlaydi, biroq React SPA muhitida jiddiy ish vaqti xatosiga olib keladi.

  • Muammo (SyntaxError va oq ekran):
    Backend 500 xatosini qaytarganda yoki React axios/fetch orqali API’ni chaqirayotgan paytda Tomcat ishlamay qolganda (502), Nginx error_page’da ko‘rsatilgan HTML hujjatni qaytaradi. Frontend uni JSON sifatida tahlil qilishga urinadi, natijada SyntaxError: Unexpected token '<' yuzaga keladi va butun ekran oq ekranda to‘xtab qoladi.

  • Yechim (Nginx kontentni kelishish mexanizmi):
    So‘rov sarlavhasidagi Accept qiymatini aniqlash uchun Nginx’ning map modulidan foydalaning: oddiy ko‘rish so‘rovlarini (text/html) HTML ekraniga yo‘naltiring, React’ning asinxron API so‘rovlari (application/json) uchun esa darhol standartlashtirilgan JSON xato sxemasini qaytaring.

  • Yaxshilangan natijalar:
    Spring Boot butunlay ishlamay qolganida ham React’ning global Axios interceptori standartlashtirilgan JSON javobini qabul qilishi va "Server texnik xizmat ko‘rsatish rejimida" modal oynasi yoki toast bildirishnomasini xavfsiz tarzda ko‘rsatishi mumkin. Shu tariqa infratuzilma darajasidagi to‘liq Fallback’ga erishiladi.

6. Xulosa: Qatlamlarni ajratish orqali yaratilgan infratuzilma ishonchliligi

Nginx yordamida proksi qatlamidagi xatolarni boshqarish oddiy dizaynni moslashtirishdan ko‘ra ko‘proq narsani anglatadi; bu infratuzilma (Nginx) va ilova (Tomcat/Spring Boot) mas’uliyatlarini ajratadigan asosiy arxitekturadir (Separation of Concerns).

Ilovaga sof biznes mantiqi va domen istisnolariga e’tibor qaratish, birinchi chiziqdagi proksiga esa infratuzilma nosozliklari va ishlamay qolish holatlarini ushlab, standartlashtirilgan formatda javob berish vazifasini yuklash orqali xizmat barqarorligi va xavfsizligini bir vaqtning o‘zida ta’minlash mumkin.

TK

Site footer