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_pass tanpa menebak.
  • Meneruskan empat header yang membuat aplikasi tahu siapa pengunjungnya.
  • Meneruskan koneksi WebSocket dengan pola map yang 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:

http://192.168.100.50:3000

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.id diarahkan 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 konteks http.
  • 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-For bisa 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

πŸ“š Referensi