Linux : Nginx Reverse Proxy, TLS, dan Diagnosa 502
Reverse proxy bukan fitur tambahan nginx. Ia keputusan tentang siapa yang memegang nama domain dan sertifikat TLS, dan siapa yang memegang aplikasinya.
Kalau kamu melewatkan bagian ini, siswa akan mengakhiri pelajaran dengan kemampuan mengetik alamat beserta :3000 di belakangnya β dan itu bukan cara situs dipakai orang.
π― Tujuan
Setelah menyelesaikan praktikum ini, kamu bisa:
- Meneruskan permintaan dari nginx ke aplikasi yang berjalan di port lain.
- Menjelaskan arti garis miring terakhir pada
proxy_passtanpa menebak. - Meneruskan empat header yang membuat aplikasi tahu siapa pengunjungnya.
- Meneruskan koneksi WebSocket dengan pola
mapyang benar. - Mengakhiri TLS di nginx sementara aplikasi di belakang tetap bicara HTTP biasa.
- Mendiagnosa 502 dan 504 dari pesan
error.log, bukan dari tebakan.
π Konteks nyata
Sebuah sekolah membuat aplikasi daftar nilai. Aplikasinya berjalan di port 3000 pada satu server. Untuk membukanya, siswa harus mengetik:
Guru dan wali murid tidak akan pernah mengingat alamat seperti itu. Lebih buruk lagi: aplikasinya sendiri tidak menangani HTTPS, sehingga kata sandi dikirim tanpa enkripsi di jaringan sekolah.
π₯ Kasus nyata: Solusi yang dipilih bukan menulis ulang aplikasi. Yang dilakukan: nginx dipasang di mesin yang sama, lalu:
nilai.sekolah.iddiarahkan ke mesin itu,- nginx memegang sertifikat TLS,
- setiap permintaan diteruskan ke
127.0.0.1:3000.
Aplikasinya tidak diubah satu baris pun. Yang berubah: alamat yang diketik wali murid, dan fakta bahwa kata sandi tidak lagi melintas terbuka.
Tapi muncul masalah kedua yang khas: di log aplikasi, semua pengunjung tercatat sebagai 127.0.0.1. Penyebabnya bukan bug aplikasi β nginx meneruskan permintaan tanpa memberi tahu alamat asal. Itu sebabnya bagian header di artikel ini bukan formalitas.
π§ Konsep singkat
πΉ Tiga tugas reverse proxy
| Tugas | Yang terjadi | Tanpa ini |
|---|---|---|
| Memberi nama | nilai.sekolah.id menunjuk satu pintu
|
Pengguna mengetik IP dan port |
| Mengakhiri TLS | Sertifikat dipegang nginx | Aplikasi harus mengurus sendiri, atau data terbuka |
| Menjadi satu pintu | Banyak aplikasi di belakang satu domain | Tiap aplikasi butuh port publik sendiri |
πΉ proxy_pass dan arti garis miring terakhir
Ini bagian yang paling sering salah dan paling sulit didiagnosa, karena hasilnya bukan error β hasilnya halaman yang salah.
| Konfigurasi | Permintaan /app/halo diteruskan sebagai
|
|---|---|
location /app/ { proxy_pass http://127.0.0.1:9001/; }
|
/halo β prefiks /app/ diganti
|
location /app/ { proxy_pass http://127.0.0.1:9001; }
|
/app/halo β diteruskan utuh
|
Aturan praktisnya: ada garis miring di akhir proxy_pass β prefiks dibuang. Kalau aplikasi di belakang mengharapkan path yang sama, jangan pakai garis miring.
πΉ Empat header yang wajib diteruskan
| Header | Isi | Gunanya |
|---|---|---|
Host
|
Nama domain yang diminta | Aplikasi membangun URL dan redirect dengan benar |
X-Real-IP
|
Alamat asli pengunjung | Log dan pembatasan per pengguna |
X-Forwarded-For
|
Rantai alamat asal | Audit lintas beberapa proxy |
X-Forwarded-Proto
|
https atau http
|
Aplikasi tidak salah membuat tautan |
Tanpa empat header ini, aplikasi tetap jalan β tapi datanya salah. Log penuh 127.0.0.1, redirect mengarah ke http:// padahal pengunjung memakai HTTPS, dan pembatasan percobaan login per IP menjadi tidak berguna.
πΉ WebSocket: pakai map, jangan tulis "upgrade" mati
Banyak tutorial menulis begini:
proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
Ini berfungsi untuk WebSocket, tapi merusak permintaan biasa. Di lab kami, permintaan GET / biasa keluar dengan Connection: upgrade ke aplikasi β padahal itu bukan WebSocket. Efeknya: koneksi ke upstream tidak bisa dipakai ulang (keep-alive mati), dan aplikasi menerima header yang tidak masuk akal.
Pola yang benar memakai map di konteks http:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Lalu di location:
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade;
Hasilnya: WebSocket mendapat upgrade, permintaan biasa mendapat close β dan keep-alive tetap sehat.
πΉ TLS berhenti di nginx, aplikasi bicara HTTP
Pola paling umum: nginx memegang sertifikat, aplikasi di belakang tetap HTTP biasa di 127.0.0.1.
Keuntungannya: satu tempat untuk memperbarui sertifikat, dan aplikasi tidak perlu tahu soal TLS. Konsekuensinya: aplikasi harus diberi tahu bahwa permintaan aslinya HTTPS β itulah tugas X-Forwarded-Proto. Tanpa header itu, aplikasi akan membuat tautan http:// dan browser modern akan memblokirnya sebagai konten campuran.
πΉ 502 dan 504 bukan kesalahan yang sama
| Kode | Arti | Penyebab khas |
|---|---|---|
| 502 Bad Gateway | nginx tidak bisa menghubungi upstream | Aplikasi mati, port salah, atau socket menolak |
| 504 Gateway Timeout | Upstream dihubungi tapi tidak menjawab tepat waktu | Aplikasi lambat, query menggantung, proxy_read_timeout terlalu pendek
|
Membedakan keduanya menghemat waktu: 502 berarti "tidak ada yang menerima", 504 berarti "ada yang menerima tapi diam".
π§© Istilah penting
- Upstream β aplikasi/server di belakang nginx.
proxy_passβ directive yang menentukan ke mana permintaan diteruskan.mapβ penentu nilai variabel berdasarkan variabel lain; harus di kontekshttp.- WebSocket β koneksi dua arah yang dimulai sebagai HTTP lalu "naik kelas".
- TLS termination β proses mengakhiri enkripsi di satu titik.
- Keep-alive β koneksi dipakai ulang untuk beberapa permintaan.
- X-Forwarded-For β daftar alamat asal yang ditambahkan tiap proxy yang dilewati.
- Buffering β nginx menampung respons upstream dulu sebelum dikirim ke klien.
proxy_read_timeoutβ batas waktu menunggu jawaban upstream.- Konten campuran β halaman HTTPS yang memuat sumber
http://.
π§ Praktik: dari aplikasi di port 9001 ke HTTPS
Lab ini dijalankan di VM dengan nginx terpasang. Semua di bawah /tmp dengan port tinggi, jadi tidak menyentuh konfigurasi produksi.
πΉ Langkah 1 β siapkan aplikasi tiruan
Kita tidak butuh aplikasi sungguhan. Yang dibutuhkan hanyalah sesuatu yang menjawab dengan header yang diterimanya β karena header itulah bukti yang akan kita periksa.
mkdir -p /tmp/lab-nginx/up
cat > /tmp/lab-nginx/up/echo.py <<'PY'
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
class H(BaseHTTPRequestHandler):
def do_GET(self):
body = json.dumps({"path": self.path, "headers": dict(self.headers)}).encode()
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def log_message(self, *a):
pass
HTTPServer(("127.0.0.1", 9001), H).serve_forever()
PY
python3 /tmp/lab-nginx/up/echo.py &
πΉ Langkah 2 β siapkan sertifikat uji
mkdir -p /tmp/lab-nginx/cert openssl req -x509 -newkey rsa:2048 -nodes \ -keyout /tmp/lab-nginx/cert/lab.key \ -out /tmp/lab-nginx/cert/lab.crt \ -days 2 -subj "/CN=lab.local"
Sertifikat ini untuk latihan. Untuk produksi, pakai sertifikat yang dipercaya publik.
πΉ Langkah 3 β tulis konfigurasi lab
mkdir -p /tmp/lab-nginx/logs /tmp/lab-nginx/temp/proxy
cat > /tmp/lab-nginx/conf/nginx.conf <<'CONF'
worker_processes 1;
error_log /tmp/lab-nginx/logs/error.log warn;
pid /tmp/lab-nginx/logs/nginx.pid;
events { worker_connections 128; }
http {
default_type text/plain;
access_log /tmp/lab-nginx/logs/access.log;
proxy_temp_path /tmp/lab-nginx/temp/proxy;
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 8082;
location / {
proxy_pass http://127.0.0.1:9001;
proxy_http_version 1.1;
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;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
server {
listen 8443 ssl;
ssl_certificate /tmp/lab-nginx/cert/lab.crt;
ssl_certificate_key /tmp/lab-nginx/cert/lab.key;
location / {
proxy_pass http://127.0.0.1:9001;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
}
CONF
πΉ Langkah 4 β uji konfigurasi sebelum dinyalakan
nginx -t -p /tmp/lab-nginx -c /tmp/lab-nginx/conf/nginx.conf
Kalau dijalankan tanpa sudo, akan muncul baris seperti ini:
nginx: [alert] could not open error log file: open() "/var/log/nginx/error.log" failed (13: Permission denied) nginx: the configuration file /tmp/lab-nginx/conf/nginx.conf syntax is ok nginx: configuration file /tmp/lab-nginx/conf/nginx.conf test is successful
Alert itu bukan kegagalan. Baris terakhirnya yang menentukan. Ajarkan ini ke siswa, supaya mereka tidak membongkar konfigurasi yang sebenarnya sudah benar.
πΉ Langkah 5 β nyalakan dan uji jalur proxy
nginx -p /tmp/lab-nginx -c /tmp/lab-nginx/conf/nginx.conf curl -s -H 'X-Dari-Siswa: uji' http://127.0.0.1:8082/ | python3 -m json.tool
Keluaran di lab kami:
{
"path": "/",
"headers": {
"Host": "127.0.0.1",
"X-Real-IP": "127.0.0.1",
"X-Forwarded-For": "127.0.0.1",
"X-Forwarded-Proto": "http",
"Connection": "close",
"X-Dari-Siswa": "uji"
}
}
Perhatikan: Connection: close β bukan upgrade. Itulah bukti bahwa map bekerja: permintaan biasa tidak lagi disamarkan sebagai WebSocket. Header buatan siswa (X-Dari-Siswa) juga ikut sampai, bukti bahwa nginx meneruskan, bukan menelan.
πΉ Langkah 6 β buktikan WebSocket tetap diteruskan
curl -s -H 'Upgrade: websocket' -H 'Connection: Upgrade' http://127.0.0.1:8082/ws \
| python3 -c "import json,sys;h=json.load(sys.stdin)['headers'];print({k:h.get(k) for k in ['Upgrade','Connection','Host','X-Forwarded-For']})"
Keluaran lab kami:
{'Upgrade': 'websocket', 'Connection': 'upgrade', 'Host': '127.0.0.1', 'X-Forwarded-For': '127.0.0.1'}
Dua uji ini (langkah 5 dan 6) yang membedakan konfigurasi benar dari yang "kebetulan jalan".
πΉ Langkah 7 β uji TLS dan header proto
curl -sk https://127.0.0.1:8443/ | python3 -c "import json,sys;h=json.load(sys.stdin)['headers'];print(h.get('X-Forwarded-Proto'))"
Harus keluar https. Kalau keluar http, aplikasi akan membuat tautan yang salah dan browser akan memblokirnya.
πΉ Langkah 8 β buat 502 dengan sengaja
pkill -f 'up/echo.py'; sleep 1
curl -s -o /dev/null -w 'status=%{http_code}\n' http://127.0.0.1:8082/
tail -2 /tmp/lab-nginx/logs/error.log
Keluaran lab kami:
status=502 2026/11/15 13:10:41 [error] 945#945: *7 connect() failed (111: Connection refused) while connecting to upstream, client: 127.0.0.1, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:9001/", host: "127.0.0.1:8082"
Inilah pola diagnosa yang harus dibiasakan siswa: 502 β buka error.log β baca baris connect() failed β lihat port upstream. Bukan menebak, bukan install ulang.
πΉ Langkah 9 β buat 504 dengan sengaja
Nyalakan kembali aplikasi, tapi kali ini buat ia lambat menjawab 5 detik, lalu setel proxy_read_timeout 2s; di location. Uji ulang: hasilnya 504, dan error.log menulis upstream timed out.
Perbedaan pesannya jelas: connect() failed = tidak ada yang menerima; upstream timed out = ada yang menerima tapi diam.
πΉ Langkah 10 β matikan lab dan pastikan bersih
nginx -p /tmp/lab-nginx -c /tmp/lab-nginx/conf/nginx.conf -s stop pkill -f 'up/echo.py' ss -tln | grep -E ':(8082|8443|9001) ' || echo "bersih" rm -rf /tmp/lab-nginx
Kebiasaan membersihkan ini yang membedakan lab dari tumpukan percobaan yang menumpuk.
π Dipakai di dunia kerja
- Sekolah dan lab β satu domain untuk banyak aplikasi (e-learning, CBT, daftar nilai) tanpa membuka port aplikasi ke pengguna.
- Kantor dan UMKM β aplikasi internal yang tidak punya fitur TLS dilindungi oleh nginx di depannya, tanpa menulis ulang aplikasi.
- Hosting dan VPS β pola yang sama dipakai untuk semua situs pelanggan; bedanya hanya otomatisasi sertifikat.
- ISP dan NOC β reverse proxy menjadi titik pencatatan akses dan pembatasan laju sebelum mencapai aplikasi.
- Klinik dan rumah sakit β data sensitif hanya melintas lewat satu pintu yang terenkripsi, sehingga jejak auditnya terkumpul.
- Industri dan OT β aplikasi lama yang tidak boleh diubah dilindungi dari luar tanpa menyentuh kode produksi.
β Verifikasi
| Titik | Bukti | Lolos kalau |
|---|---|---|
| Proxy jalan | curl ke port proxy
|
Isi berasal dari aplikasi, bukan halaman nginx |
| Header asli | keluaran JSON aplikasi | X-Forwarded-For terisi
|
| Protokol | X-Forwarded-Proto
|
https saat diakses lewat TLS
|
| WebSocket | header Upgrade
|
Diteruskan saat diminta |
| Perilaku normal | Connection
|
close, bukan upgrade
|
| TLS | curl -k https://β¦
|
Halaman aplikasi keluar |
| Diagnosa 502 | error.log
|
connect() failed
|
| Diagnosa 504 | error.log
|
upstream timed out
|
| Kebersihan lab | ss -tln
|
Port lab tidak lagi mendengarkan |
β οΈ Kesalahan umum & troubleshooting
| Gejala | Penyebab | Perbaikan |
|---|---|---|
| 502 Bad Gateway | Aplikasi mati / port salah | error.log β connect() failed
|
| 504 Gateway Timeout | Aplikasi lambat | Naikkan proxy_read_timeout setelah memastikan aplikasinya sehat
|
| Log aplikasi penuh 127.0.0.1 | Header asal tidak diteruskan | Tambahkan X-Real-IP dan X-Forwarded-For
|
| Halaman 404 padahal aplikasi punya path | Garis miring di akhir proxy_pass
|
Sesuaikan prefiks, uji ulang |
Redirect ke http:// di halaman HTTPS
|
X-Forwarded-Proto hilang
|
Teruskan header proto |
| WebSocket gagal naik kelas | Upgrade/Connection tidak diteruskan
|
Pakai pola map
|
| Keep-alive ke upstream tidak jalan | Connection "upgrade" ditulis mati
|
Ganti ke map
|
invalid parameter "root" saat nginx -t
|
Titik koma hilang di baris sebelumnya | Baca satu baris sebelum pesan error |
| Situs tidak berubah setelah edit | Reload tidak dijalankan / berkas tidak terbaca | nginx -T, lalu reload
|
π Catatan keamanan
- Aplikasi di belakang sebaiknya hanya mendengarkan di
127.0.0.1. Kalau port aplikasi terbuka ke jaringan, proxy-mu bisa dilewati. - Sertifikat dan kunci privat harus dibaca hanya oleh proses nginx. Jangan menaruhnya di folder web root.
- Jangan meneruskan header mentah dari klien tanpa daftar putih. Header seperti
X-Forwarded-Forbisa dipalsukan kalau nginx tidak menimpanya. - Batasi akses ke halaman admin di tingkat proxy, bukan hanya di aplikasi.
- Saat mengajar, gunakan aplikasi tiruan seperti di lab. Jangan menjalankan uji beban ke situs sekolah atau situs orang lain.
π Kesimpulan
Reverse proxy terlihat seperti satu directive. Kenyataannya ada tiga keputusan:
- Path β apakah prefiks dibuang atau diteruskan; ditentukan oleh satu garis miring.
- Identitas pengunjung β header yang membuat log dan pembatasan akses masuk akal.
- Batas tanggung jawab β nginx memegang TLS, aplikasi memegang data.
Kalau hanya punya dua puluh menit untuk mengajar: jalankan langkah 5, 6, dan 8. Tiga langkah itu memperlihatkan bukti header, bukti WebSocket, dan bukti kegagalan berikut cara membacanya β dan itu jauh lebih berharga daripada sepuluh menit menjelaskan diagram.
π Materi terkait
- Linux : Instalasi dan Setup Nginx Produksi β prasyarat: memasang nginx dan mencabut situs default.
- Linux : Nginx Dasar dan Virtual Host β cara nginx memilih server block dan location.
- Linux : Praktikum Virtual Host Nginx dan Diagnosa Situs yang Salah Tampil β lima lapis bukti saat halaman salah tampil.
- Cyber Security : Audit Port Terbuka dan Layanan Berjalan β memastikan hanya pintu yang disengaja yang terbuka.
- Linux : Log dan journalctl untuk Troubleshooting β membaca log secara umum sebelum menyalahkan nginx.
π Referensi
- Dokumentasi
ngx_http_proxy_module(proxy_pass,proxy_set_header, timeout): https://nginx.org/en/docs/http/ngx_http_proxy_module.html - Dokumentasi
ngx_http_upstream_module: https://nginx.org/en/docs/http/ngx_http_upstream_module.html - Dokumentasi
map(ngx_http_map_module): https://nginx.org/en/docs/http/ngx_http_map_module.html - Dokumentasi
ngx_http_ssl_module: https://nginx.org/en/docs/http/ngx_http_ssl_module.html - Dokumentasi
ngx_http_core_module(try_files,root): https://nginx.org/en/docs/http/ngx_http_core_module.html