SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor

Konfigurasi Reverse Proxy nginx, Dijelaskan

Pelajari konfigurasi reverse proxy nginx di Ubuntu 24.04, termasuk proxy_pass, empat header penting, WebSocket, garis miring penutup, dan unggahan file.

Fungsi konfigurasi reverse proxy nginx

Reverse proxy nginx menerima permintaan yang masuk melalui port 80 dan port 443, lalu meneruskan setiap permintaan ke aplikasi yang sudah listening pada port lokal. Setelah itu, nginx mengembalikan respons aplikasi tersebut ke browser. Konfigurasinya berupa satu blok server, dan blok ini singkat. Hampir seluruh bagian yang sulit terdapat pada lima atau enam baris yang memberi tahu aplikasi siapa klien sebenarnya dan protokol apa yang digunakan klien tersebut.

Semua konfigurasi berikut dibuat dari awal pada Ubuntu 24.04 menggunakan paket nginx dari distribusi. Kondisi awalnya adalah aplikasi yang sudah memberikan respons pada 127.0.0.1:3000. Jika Anda belum menentukan proxy yang akan digunakan, baca terlebih dahulu perbandingan nginx dengan Caddy dan Traefik. Bagian berikut menjelaskan bentuk konfigurasi nginx, baris demi baris.

Jalankan konfigurasi ini di server Anda sendiri. Uji setiap perubahan dengan sudo nginx -t sebelum melakukan reload, lalu baca output yang ditampilkannya.

Lokasi nginx menyimpan konfigurasinya di Ubuntu

sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/

File utamanya adalah /etc/nginx/nginx.conf. File ini menetapkan opsi global di dalam blok http { }, lalu memuat dua direktori: /etc/nginx/conf.d/*.conf dan /etc/nginx/sites-enabled/*. Di Ubuntu dan Debian, buat satu file untuk setiap situs di /etc/nginx/sites-available/, lalu aktifkan situs tersebut dengan symlink ke /etc/nginx/sites-enabled/. Menghapus symlink akan menonaktifkan situs tanpa menghapus filenya.

Dua direktif yang digunakan nanti hanya berfungsi dalam konteks http, bukan di dalam blok server: map dan upstream. Letakkan direktif tersebut dalam file tersendiri di bawah /etc/nginx/conf.d/, karena direktori itu dimuat pada tingkat http.

Paket ini menyediakan situs yang sudah diaktifkan dengan nama default. Situs tersebut ditandai sebagai default_server. Artinya, situs ini akan menjawab setiap permintaan yang nilai header Host-nya tidak cocok dengan server_name mana pun dalam konfigurasi Anda. Selama situs ini tetap aktif, permintaan yang tidak cocok dengan nama situs Anda akan diarahkan ke situs tersebut, bukan ke aplikasi Anda. Hapus symlink setelah situs Anda sendiri berfungsi.

sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Blok server minimal yang meneruskan satu aplikasi

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

Simpan sebagai /etc/nginx/sites-available/app.example.com, lalu aktifkan dan muat konfigurasinya.

sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/

listen 80; mengikat IPv4, sedangkan listen [::]:80; mengikat IPv6. Jika baris kedua dihilangkan, semua koneksi IPv6 ke server akan ditolak. Browser dual-stack yang hasil pencarian DNS (domain name system) miliknya mengembalikan rekaman AAAA biasanya beralih ke IPv4 sehingga masalah ini tidak terlihat. Namun, pengunjung yang hanya menggunakan IPv6, atau klien yang hanya mencoba alamat pertama yang diterimanya, akan melihat koneksi ditolak, sementara semua pengguna IPv4 melihat situs yang berfungsi. Laporan bug yang Anda terima berbunyi, "di sisi saya berfungsi".

server_name dicocokkan dengan header Host yang dikirim browser. Beberapa nama dapat dicantumkan dan dipisahkan dengan spasi. Jika tidak ada blok yang cocok, nginx menggunakan blok yang merupakan default_server, sehingga situs bawaan harus dihapus.

location / adalah pencocokan prefix pada path permintaan, sedangkan / cocok dengan semua path. proxy_pass adalah alamat yang digunakan nginx untuk membuka koneksi. Biarkan aplikasi terikat ke 127.0.0.1 agar satu-satunya jalur masuk adalah melalui nginx. Jika aplikasi berjalan dalam container, publikasikan sebagai 127.0.0.1:3000:3000, bukan 3000:3000, karena Docker menulis aturannya sendiri dan memublikasikan port langsung melewati ufw, sehingga port yang dipublikasikan tanpa pembatasan dapat diakses dari Internet terlepas dari konfigurasi ufw. Docker mendokumentasikan chain DOCKER-USER sebagai tempat untuk memfilter trafik tersebut, tetapi mengikat aplikasi ke 127.0.0.1 merupakan perbaikan yang lebih sederhana.

Baris curl mengirimkan header Host yang benar dari server itu sendiri, sehingga Anda dapat menguji blok tersebut sebelum DNS diarahkan ke mana pun.

Apa yang dikirim nginx ke upstream jika tidak ada konfigurasi tambahan

proxy_pass secara mandiri menyembunyikan empat hal dari aplikasi Anda.

Paket nginx 1.24.0 yang dirilis bersama Ubuntu 24.04 menggunakan HTTP/1.0 ke backend secara default dan mengirim Connection: close. Akibatnya, setiap permintaan membuka koneksi upstream baru dan tidak ada peningkatan protokol yang dapat dilakukan. nginx 1.29.7, yang dirilis pada Maret 2026, mengubah default tersebut: sejak versi itu, nginx menggunakan HTTP/1.1 ke upstream, tidak mengirim header Connection, dan menggunakan kembali koneksi dalam pool, bukan membuka koneksi baru untuk setiap permintaan. Namun, peningkatan WebSocket tetap memerlukan header yang ditunjukkan di bagian berikutnya.

Header Host ditulis ulang menjadi nilai dalam proxy_pass, yaitu 127.0.0.1:3000. Aplikasi yang membuat tautan absolut berdasarkan Host kini menghasilkan tautan yang tidak dapat dibuka oleh siapa pun dari luar server.

Koneksi yang mencapai aplikasi berasal dari nginx, sehingga aplikasi melihat alamat klien sebagai 127.0.0.1. Setiap baris log dan setiap pembatasan laju di dalam aplikasi kemudian mencatat proxy, bukan pengunjung.

Aplikasi tidak dapat mengetahui bahwa browser menggunakan HTTPS karena koneksi yang diterimanya adalah HTTP biasa pada alamat loopback.

Empat baris memperbaiki semua masalah tersebut.

Empat header yang harus ditetapkan dan informasi yang dapat dilihat backend dari masing-masing header

location / {
    proxy_pass http://127.0.0.1:3000;

    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;
}

Host membawa nama yang diketik pengunjung. $host adalah nama dari request, tanpa port dan dengan huruf kecil. Tetapkan header ini agar aplikasi membentuk URL absolut yang benar, misalnya redirect setelah login atau tautan dalam email pengaturan ulang kata sandi. Jika tidak ditetapkan, aplikasi menganggap 127.0.0.1:3000 sebagai namanya sendiri. Nilai default proxy_redirect dari nginx menulis ulang header Location atau Refresh yang mengarah ke alamat proxy_pass. Karena itu, redirect biasa setelah login biasanya tetap mengarah ke tempat yang benar. Namun, URL absolut yang ditulis aplikasi ke halaman dan emailnya, seperti tautan pengaturan ulang kata sandi, akan mengarah ke 127.0.0.1:3000, yaitu alamat yang tidak dapat dibuka oleh browser pengunjung. Jika aplikasi juga memerlukan port, misalnya karena layanan dijalankan pada 8080, gunakan $http_host. Header ini berisi nilai persis seperti yang dikirim client.

X-Real-IP membawa satu nilai: $remote_addr, yaitu alamat tempat nginx menerima koneksi. Aplikasi membacanya untuk access log dan rate limiting miliknya sendiri.

X-Forwarded-For membawa sebuah daftar. $proxy_add_x_forwarded_for menambahkan $remote_addr ke nilai yang sudah ditempatkan client dalam header tersebut. Karena itu, nilainya dipisahkan dengan koma dan entri yang ditambahkan nginx berada di urutan terakhir. Detail ini menentukan apakah header tersebut dapat dipercaya. Client dapat mengirim X-Forwarded-For apa pun, sehingga aplikasi yang membaca entri pertama dapat menerima alamat apa pun. Jika nginx adalah edge server, tulis $remote_addr sebagai gantinya dan buang nilai dari client. Jika terdapat CDN atau proxy lain di depan nginx, gunakan set_real_ip_from dan real_ip_header dari modul realip agar $remote_addr sendiri menjadi alamat client yang sebenarnya.

X-Forwarded-Proto membawa http atau https. Framework membacanya untuk menentukan apakah cookie harus ditandai Secure dan apakah redirect ke HTTPS harus dipaksakan. Jika header ini tidak ditetapkan pada situs TLS, aplikasi yang dikonfigurasi untuk memaksa HTTPS melihat http, merespons dengan redirect ke alamat HTTPS, menerima request berikutnya melalui nginx, tetap melihat http, lalu melakukan redirect lagi. Browser akhirnya berhenti dan menampilkan ERR_TOO_MANY_REDIRECTS.

Mengulang keempat baris tersebut di setiap location dapat menyebabkan konfigurasinya berbeda. Simpan semuanya dalam satu file, lalu include file tersebut.

# /etc/nginx/snippets/proxy-headers.conf
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;
location / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;
}

Inheritance di sini memiliki jebakan. Sebuah location hanya mewarisi directive proxy_set_header dari server block jika location tersebut tidak mendefinisikan directive sendiri. Jika Anda menambahkan satu proxy_set_header di dalam location, semua header yang didefinisikan pada tingkat server akan dihapus untuk location tersebut. Karena itu, pertahankan semuanya pada satu tingkat atau include snippet tersebut di setiap location yang melakukan proxy.

Mengapa aplikasi WebSocket saya terhubung lalu terputus?

Karena konfigurasi default melarang upgrade, dan read timeout default menutup tunnel yang tidak aktif setelah 60 detik. WebSocket dimulai sebagai permintaan HTTP yang membawa Upgrade: websocket dan Connection: Upgrade. Keduanya adalah header hop-by-hop. Artinya, proxy seharusnya menggunakan header tersebut dan tidak meneruskannya. Selain itu, pada nginx 1.24.0 di Ubuntu 24.04, protokol upstream secara default menggunakan HTTP/1.0, yang sama sekali tidak memiliki mekanisme upgrade. Keduanya harus ditambahkan kembali secara manual.

Map ditempatkan dalam konteks http, di file tersendiri.

# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Berikutnya, tambahkan location.

location / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;

    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

Map digunakan agar satu location dapat melayani kedua jenis trafik. Pada permintaan biasa, $http_upgrade kosong, sehingga $connection_upgrade menjadi close. Pada permintaan upgrade, nilainya adalah websocket, sehingga header yang dikirim ke upstream adalah Connection: upgrade. Menetapkan proxy_set_header Connection "upgrade"; secara langsung akan mengirim header tersebut pada setiap permintaan halaman biasa. Beberapa backend akan menjawab permintaan seperti itu dengan status 400.

proxy_http_version 1.1; menjadi default mulai nginx 1.29.7. Pada versi tersebut, baris ini tidak mengubah apa pun dan tidak menimbulkan masalah. Pada paket 1.24.0, baris ini wajib ada. Baris Upgrade dan Connection wajib ada pada semua versi karena nginx tidak pernah meneruskan kedua header tersebut secara otomatis.

proxy_read_timeout menyebabkan munculnya laporan “aplikasi memuat data, lalu berhenti memperbarui”. Nilai defaultnya adalah 60 detik. Timeout ini mengukur jeda antara dua pembacaan dari backend, bukan durasi koneksi. Jika WebSocket tidak mengirim data selama 60 detik, nginx menutupnya, dan konsol browser menampilkan bahwa socket ditutup dengan kode 1006. Aplikasi yang mengirim heartbeat sendiri lebih sering daripada sekali per menit tidak akan mengalami masalah ini. Aplikasi yang tidak mengirim heartbeat akan terputus tepat setelah satu menit. Editor live dan dashboard biasanya menunjukkan masalah ini lebih dahulu, instance n8n yang di-host sendiri di balik HTTPS menjadi contoh yang umum.

Mengapa garis miring di akhir proxy_pass mengubah URL?

Aturannya sederhana. Jika proxy_pass diakhiri URI (uniform resource identifier), bahkan hanya /, nginx menghapus bagian path permintaan yang cocok dengan prefix location, lalu menggantinya dengan URI tersebut. Jika proxy_pass berhenti pada host dan port, path permintaan diteruskan tanpa perubahan.

location /app/ {
    proxy_pass http://127.0.0.1:3000/;
}

Permintaan ke /app/status diteruskan ke backend sebagai /status.

location /app/ {
    proxy_pass http://127.0.0.1:3000;
}

Permintaan ke /app/status diteruskan ke backend sebagai /app/status.

Bentuk yang digunakan bergantung pada aplikasi. Aplikasi dengan pengaturan base-path atau sub-folder memerlukan bentuk kedua, dengan pengaturan tersebut diarahkan ke /app. Aplikasi yang tidak mengenal prefix memerlukan bentuk pertama. Bentuk pertama memiliki dampak yang langsung terlihat: HTML yang dikembalikan aplikasi tetap berisi path absolut seperti /static/main.css, browser meminta path tersebut dari root situs, tidak ada location yang cocok, dan halaman ditampilkan tanpa styling. Tab network pada browser menunjukkan bahwa permintaan aset tersebut menghasilkan 404. Solusinya adalah pengaturan base-path milik aplikasi, atau location /static/ kedua yang mengarah ke backend yang sama.

Location regex tidak boleh memuat URI dalam proxy_pass. sudo nginx -t menolak konfigurasi tersebut dan menyebutkan alasannya: "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block.

Seluruh masalah ini hilang jika setiap aplikasi memiliki nama sendiri, app.example.com, dan diproxy dari location /. Sub-path hanya layak digunakan jika Anda tidak dapat menambahkan record DNS.

Bagaimana cara menempatkan lebih dari satu backend di balik satu nama?

Gunakan blok upstream. Blok ini berada dalam konteks http. Tulis blok tersebut di atas blok server dalam file yang sama, atau di /etc/nginx/conf.d/.

upstream app_backend {
    least_conn;
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

Kemudian, referensikan blok tersebut dalam location: proxy_pass http://app_backend;.

Metode default adalah round robin. least_conn mengirim setiap request ke backend dengan jumlah koneksi aktif paling sedikit. Metode ini sesuai untuk request dengan durasi yang tidak seragam. ip_hash mengikat satu alamat client ke satu backend. Anda memerlukan ip_hash ketika aplikasi menyimpan session di memorinya sendiri. Round robin pada dua backend semacam itu dapat membuat pengguna logout secara acak ketika request mereka masuk ke instance yang belum pernah menerima request tersebut. Memindahkan session ke shared storage merupakan solusi yang lebih baik.

max_fails=3 fail_timeout=30s berarti tiga upaya yang gagal dalam 30 detik akan mengeluarkan server tersebut dari pool selama 30 detik. Ketika semua server dalam blok berada dalam kondisi tersebut, client menerima 502 dan error log berisi no live upstreams while connecting to upstream.

keepalive 32 mempertahankan hingga 32 koneksi idle ke backend tetap terbuka untuk setiap proses worker. Ini menghilangkan proses TCP handshake dari sebagian besar request. Pada Ubuntu 24.04 dengan versi 1.24.0, baris tersebut mengaktifkan cache. Sejak nginx 1.29.7, cache aktif secara default. Namun, default yang didokumentasikan adalah keepalive 32 local;, dan parameter local mencegah koneksi yang di-cache digunakan bersama oleh location yang berbeda. Jadi, pada versi 1.29.7 dan yang lebih baru, keepalive 32; tanpa parameter tidak sekadar menyatakan ulang default. Dengan tidak mencantumkan local, konfigurasi tersebut memungkinkan location mana pun yang melakukan proxy ke upstream server yang sama untuk menggunakan kembali koneksi dalam pool. Ini berbeda dari perilaku default. Pada versi tersebut, hilangkan baris itu atau tulis keepalive 32 local; untuk mempertahankan default. Tulis tanpa parameter hanya jika Anda ingin mengaktifkan penggunaan bersama tersebut. Parameter local baru tersedia pada 1.29.7, sehingga package 1.24.0 tidak menerimanya. Untuk backend HTTP, konfigurasi yang direkomendasikan nginx untuk pool adalah proxy_http_version yang diatur ke 1.1 (atau 2 pada nginx 1.29.4 dan yang lebih baru), dengan header Connection yang dikirim ke upstream dihapus. nginx juga mendokumentasikan persistent connection HTTP/1.0, yang dibuat dengan mengirim Connection: Keep-Alive ke backend yang mendukungnya, tetapi metode tersebut tidak direkomendasikan. Sejak 1.29.7, kedua bagian konfigurasi yang direkomendasikan tersebut menjadi default. Pada 1.24.0, tambahkan proxy_http_version 1.1; dan proxy_set_header Connection ""; sendiri ke location. Jika tidak, nginx akan terus mengirim HTTP/1.0 dengan Connection: close dan pool tidak pernah digunakan kembali. Jika location yang sama juga menggunakan WebSocket map, ubah nilai kosong dari close menjadi string kosong agar request biasa tidak membawa header Connection dan koneksi dalam pool dapat digunakan kembali.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      '';
}

Nama di dalam blok upstream di-resolve saat nginx start. Jika backend Anda berupa container yang menerima alamat baru ketika restart, nginx akan terus menggunakan alamat lama sampai Anda me-reload-nya. nginx 1.27.3 dan yang lebih baru dapat mengikuti perubahan tersebut tanpa reload melalui resolver, zone di dalam blok upstream, dan parameter resolve pada setiap baris server. Namun, package 1.24.0 dirilis sebelum fitur tersebut tersedia. Di dalam jaringan Docker, Anda dapat memindahkan proses lookup ke waktu request menggunakan embedded resolver.

resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;

Jika container cukup sering dibuat dan dihapus hingga Anda harus terus mengedit nginx untuk menyesuaikan konfigurasi, proxy yang membaca label container merupakan pilihan yang lebih baik. Traefik di depan beberapa aplikasi Docker Compose membuat route dari container itu sendiri.

Mengapa unggahan gagal dengan 413 Request Entity Too Large?

client_max_body_size secara default bernilai 1 megabyte. nginx menolak body permintaan yang lebih besar dengan kode 413, dan log error mencatat client intended to send too large body. Tingkatkan nilainya di blok server atau di location tempat unggahan berlangsung.

client_max_body_size 512m;

Nilai 0 menonaktifkan pemeriksaan sepenuhnya. Dengan 512m, nginx tetap menolak body permintaan yang melebihi batas tersebut. Jadi, error 413 yang tetap muncul setelah perubahan ini tidak menunjukkan bahwa backend adalah sumbernya. Periksa client_max_body_size yang berlaku di location yang menangani unggahan dan error log nginx sebelum memeriksa batas unggahan aplikasi.

Secara default, nginx membaca seluruh body permintaan sebelum membuka koneksi upstream. Jika ukurannya besar, nginx terlebih dahulu menulisnya ke file sementara di disk. Cara ini melindungi aplikasi dari klien yang lambat karena backend menerima unggahan dengan kecepatan penuh jaringan lokal. Untuk unggahan yang sangat besar, Anda dapat menggunakan streaming.

proxy_request_buffering off;

Untuk unggahan chunked HTTP/1.1 pada paket 1.24.0, tetapkan juga proxy_http_version 1.1; di location tersebut. Jika tidak, nginx tetap melakukan buffering terhadap body. Backend kemudian menerima body saat data tiba dan harus mampu menanganinya. Setelah nginx mulai mengirim body ke upstream, nginx tidak dapat mencoba ulang permintaan tersebut ke upstream lain.

client_body_timeout, yang secara default bernilai 60 seconds, berlaku di antara dua pembacaan body yang berurutan, bukan untuk keseluruhan proses unggah. Unggahan yang lambat tetapi stabil akan tetap berjalan. Unggahan yang terhenti akan dihentikan.

Buffer respons dan pengaturan yang mengganggu output langsung

proxy_buffering aktif secara default dan biasanya itulah yang Anda perlukan. nginx membaca respons dari aplikasi secepat aplikasi dapat menulisnya, menahannya, lalu mengirimkannya kepada klien lambat sesuai kecepatan klien tersebut. Worker aplikasi selesai lebih awal dan tidak terus sibuk selama proses pengunduhan yang lambat.

Pengaturan ini mengganggu respons streaming. Server-sent events dan output log langsung tidak menampilkan apa pun kepada pembaca hingga buffer terisi. Nonaktifkan buffering hanya pada lokasi tersebut.

proxy_buffering off;

Jika Anda mengendalikan aplikasinya, langkah yang lebih baik adalah mengirim header X-Accel-Buffering: no hanya pada respons streaming. nginx membaca header tersebut untuk setiap respons dan menonaktifkan buffering hanya untuk respons itu, sehingga halaman biasa tetap memperoleh manfaatnya.

Jika error log menampilkan upstream sent too big header while reading response header from upstream, header respons tidak muat dalam satu buffer. proxy_buffer_size secara default berukuran satu halaman memori, yaitu 4 atau 8 kilobyte, bergantung pada platform. Cookie yang panjang atau header autentikasi yang besar dapat melampaui ukuran tersebut. Tingkatkan kedua nilainya.

proxy_buffer_size 16k;
proxy_buffers 8 16k;

TLS berada di bagian mana dalam konfigurasi ini?

Pada nginx, di depan semua komponen di atas. TLS (transport layer security) berakhir di proxy, sedangkan koneksi dari nginx ke aplikasi tetap menggunakan HTTP biasa melalui alamat loopback. Tidak ada perangkat lain di jaringan yang dapat membacanya. Aplikasi mengetahui bahwa pengunjung menggunakan HTTPS dari X-Forwarded-Proto, yaitu header keempat dari empat header.

Jangan menulis path sertifikat secara manual. Arahkan record DNS ke server, buka firewall, lalu biarkan Certbot mengedit server block yang sama. Certbot menambahkan baris listen 443 ssl dengan path ssl_certificate, serta pengalihan dari port 80. Menerbitkan sertifikat Let's Encrypt untuk nginx dengan Certbot menjelaskan proses penerbitan dan timer pembaruan.

sudo ufw allow 'Nginx Full'
sudo ufw status

Nginx Full adalah profil aplikasi yang dipasang oleh paket nginx. Profil ini membuka port 80 dan port 443 secara bersamaan. Port 80 harus tetap terbuka untuk tantangan pembaruan HTTP-01, meskipun semua pengunjung sudah dialihkan ke HTTPS.

Uji konfigurasi, lalu lakukan reload

sudo nginx -t
sudo systemctl reload nginx

nginx -t mem-parsing setiap file yang disertakan, lalu melaporkan bahwa pengujian berhasil atau menampilkan file dan baris tempat proses berhenti. Baca output tersebut sebelum melakukan reload. Reload dengan konfigurasi yang rusak tidak diterapkan: nginx tetap melayani menggunakan konfigurasi sebelumnya, sehingga situs tetap aktif sementara perubahan Anda tidak melakukan apa pun tanpa pesan. systemctl restart berperilaku berbeda dan lebih buruk, karena restart terlebih dahulu menghentikan server yang sedang berjalan. Akibatnya, kesalahan konfigurasi membuat nginx tidak berjalan sama sekali. Secara default, gunakan reload, dan gunakan restart hanya untuk perubahan yang memang memerlukannya.

sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'

Baris ss menampilkan proses yang menggunakan setiap port, sehingga Anda dapat memastikan aplikasi benar-benar listening pada alamat yang ditunjuk proxy_pass.

Kegagalan yang benar-benar akan Anda temui

502 Bad Gateway, dengan connect() failed (111: Connection refused) while connecting to upstream di log error. Tidak ada proses yang listening pada alamat di proxy_pass. Aplikasi berhenti, terikat ke port lain, atau terikat ke alamat internal container yang tidak dapat dijangkau oleh host.

502 dengan no live upstreams while connecting to upstream. Semua server dalam blok upstream saat ini ditandai gagal oleh max_fails. Perbaiki backend tersebut. nginx akan mencoba ulang setelah fail_timeout berakhir.

504 Gateway Time-out, dengan upstream timed out (110: Connection timed out) while reading response header from upstream. Backend menerima koneksi, lalu tidak mengirim apa pun selama proxy_read_timeout detik. Menaikkan timeout tepat untuk laporan yang memang lambat, tetapi tidak tepat untuk aplikasi yang macet.

Setiap path mengembalikan 404 dari aplikasi. Aturan trailing slash menulis ulang path tersebut. Bandingkan path yang dicatat dalam log aplikasi dengan path yang Anda minta.

Situs yang berbeda merespons. server_name tidak cocok dengan header Host, sehingga permintaan masuk ke blok default_server.

Halaman dimuat, lalu antarmuka berhenti merespons setelah sekitar satu menit. Ini adalah kasus WebSocket: konfigurasi Upgrade belum ada, atau proxy_read_timeout masih bernilai 60 detik.

FAQ

Mengapa nginx mengembalikan 502 Bad Gateway setelah saya menambahkan proxy_pass?

nginx tidak dapat membuka koneksi ke alamat pada proxy_pass. Log error di /var/log/nginx/error.log menjelaskan penyebabnya: connect() failed (111: Connection refused) while connecting to upstream berarti tidak ada proses yang sedang mendengarkan di sana, sedangkan no live upstreams berarti setiap server dalam blok upstream telah ditandai gagal. Jalankan sudo ss -lntp | grep 3000 untuk melihat proses yang menggunakan port tersebut dan alamat tempat proses itu terikat. Aplikasi yang terikat pada alamat internal container, atau pada port yang berbeda dari port yang Anda tulis, selalu menghasilkan error ini.

Mengapa aplikasi saya terputus setelah sekitar satu menit di belakang nginx?

Koneksi tersebut adalah WebSocket, dan proxy_read_timeout masih menggunakan nilai default 60 detik. Nilai ini mengukur jeda antara dua pembacaan dari backend. Socket yang tidak aktif akan ditutup oleh nginx, lalu konsol browser melaporkan kode penutupan 1006. Atur proxy_http_version 1.1 (nilai default sejak nginx 1.29.7, tetapi tidak tersedia dalam paket 1.24.0 yang disediakan Ubuntu 24.04), teruskan Upgrade dan Connection melalui map pada $http_upgrade, lalu naikkan proxy_read_timeout menjadi sekitar 3600s. Tanpa header Upgrade, proses upgrade sama sekali tidak berlangsung, sehingga aplikasi beralih ke polling atau tidak menampilkan pembaruan langsung.

Apakah garis miring di akhir proxy_pass berpengaruh?

Ya, dan garis miring tersebut mengubah path yang diterima backend. Dengan location /app/ dan proxy_pass http://127.0.0.1:3000/, permintaan untuk /app/status tiba di backend sebagai /status, karena URI apa pun setelah host dan port menggantikan awalan location yang cocok. Hapus garis miring terakhir tersebut, dan permintaan yang sama tiba sebagai /app/status. Penghapusan awalan sering merusak tautan aset milik aplikasi, yang tetap bersifat absolut lalu menghasilkan 404 di root situs. Karena itu, untuk aplikasi yang memiliki pengaturan base-path, gunakan bentuk yang meneruskan path tersebut.

Mengapa log aplikasi saya mencatat 127.0.0.1 sebagai alamat IP setiap pengunjung?

Karena koneksi yang diterima aplikasi memang berasal dari nginx melalui alamat loopback. Alamat pengunjung hanya diteruskan ke aplikasi melalui header yang Anda tetapkan: proxy_set_header X-Real-IP $remote_addr; untuk satu nilai, dan proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; untuk rantai yang ditambahkan. Aplikasi juga harus dikonfigurasi agar mempercayai header tersebut. Ingat bahwa client dapat mengirim X-Forwarded-For miliknya sendiri. Karena itu, saat nginx menjadi edge server, timpa nilainya dengan $remote_addr, bukan menambahkannya.

Apakah saya memerlukan TLS pada koneksi antara nginx dan aplikasi?

Tidak, jika aplikasi berjalan pada server yang sama dan terikat ke 127.0.0.1, karena trafik tersebut tidak pernah meninggalkan mesin. Hentikan TLS di nginx, gunakan proxy_pass melalui HTTP biasa pada loopback, lalu kirim X-Forwarded-Proto $scheme agar aplikasi mengetahui bahwa pengunjung menggunakan HTTPS. Jika backend berada pada host yang berbeda melalui jaringan yang tidak Anda kendalikan, hop tersebut memerlukan perlindungan sendiri, baik berupa HTTPS ke backend maupun tunnel privat antara kedua mesin.

Apakah artikel ini bermanfaat?