วิธีตั้งค่า nginx reverse proxy อย่างละเอียดทุกขั้นตอน
เรียนรู้วิธีเขียนคอนฟิก nginx reverse proxy บน Ubuntu 24.04 ตั้งแต่การตั้งค่า proxy_pass การส่ง Header ที่จำเป็นสำหรับแอปพลิเคชัน การรองรับ Websockets จนถึงการจัดการไฟล์อัปโหลด
หน้าที่ของคอนฟิก nginx reverse proxy
nginx reverse proxy จะรับคำขอที่เข้ามาทางพอร์ต 80 และพอร์ต 443 แล้วส่งต่อคำขอแต่ละรายการไปยังแอปพลิเคชันที่กำลังฟัง (listen) อยู่บนพอร์ตภายในเครื่อง จากนั้นจึงส่งคำตอบของแอปพลิเคชันนั้นกลับไปยังเบราว์เซอร์ คอนฟิกดังกล่าวจะเป็นบล็อก server เพียงบล็อกเดียวและมีความยาวไม่มาก ความยากเกือบทั้งหมดจะอยู่ที่ 5 หรือ 6 บรรทัดที่ทำหน้าที่แจ้งให้แอปพลิเคชันของคุณทราบว่าไคลเอนต์ตัวจริงคือใครและใช้โปรโตคอลใด
เนื้อหาทั้งหมดด้านล่างนี้สร้างขึ้นใหม่บน Ubuntu 24.04 โดยใช้แพ็กเกจ nginx จาก distribution โดยมีจุดเริ่มต้นคือแอปพลิเคชันที่ตอบสนองบน 127.0.0.1:3000 อยู่แล้ว หากคุณยังไม่ได้ตัดสินใจเลือกใช้พร็อกซีตัวใด การเปรียบเทียบ nginx กับ Caddy และ Traefik คือบทความที่คุณควรอ่านเป็นอันดับแรก สิ่งที่ตามมาคือรายละเอียดของคอนฟิก nginx ทีละบรรทัด
ให้ทดสอบคอนฟิกเหล่านี้บนเซิร์ฟเวอร์ของคุณเอง ตรวจสอบการเปลี่ยนแปลงทุกครั้งด้วย sudo nginx -t ก่อนทำการ reload และอ่านผลลัพธ์ที่แสดงออกมา
ตำแหน่งที่ nginx เก็บไฟล์คอนฟิกบน Ubuntu
sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/ไฟล์หลักคือ /etc/nginx/nginx.conf ซึ่งกำหนดตัวเลือกส่วนกลางไว้ภายในบล็อก http { } จากนั้นจะดึงไฟล์จากสองไดเรกทอรีคือ /etc/nginx/conf.d/*.conf และ /etc/nginx/sites-enabled/* บน Ubuntu และ Debian คุณสามารถเขียนไฟล์คอนฟิกแยกหนึ่งไฟล์ต่อหนึ่งเว็บไซต์ไว้ใน /etc/nginx/sites-available/ และเปิดใช้งานโดยการสร้าง symlink ไปยัง /etc/nginx/sites-enabled/ การลบ symlink จะเป็นการปิดใช้งานเว็บไซต์นั้นโดยที่ไฟล์คอนฟิกยังคงอยู่
คำสั่ง (directive) สองรายการที่ใช้ในภายหลังจะทำงานได้เฉพาะในบริบท http เท่านั้น ไม่สามารถใช้ภายในบล็อก server ได้ นั่นคือ map และ upstream ให้ใส่คำสั่งเหล่านี้ไว้ในไฟล์แยกต่างหากภายใต้ /etc/nginx/conf.d/ เนื่องจากไดเรกทอรีดังกล่าวถูกรวมเข้ามาที่ระดับ http
แพ็กเกจนี้มาพร้อมกับเว็บไซต์ที่เปิดใช้งานไว้แล้วชื่อ default ซึ่งถูกกำหนดค่าเป็น default_server หมายความว่ามันจะตอบสนองต่อทุกคำขอที่ส่วนหัว Host ไม่ตรงกับ server_name ใดๆ ในคอนฟิกของคุณ ตราบใดที่เว็บไซต์นี้ยังเปิดใช้งานอยู่ คำขอที่ไม่ตรงกับชื่อโดเมนของคุณจะถูกส่งไปยังเว็บไซต์นี้แทนที่จะเป็นแอปของคุณ ให้ลบ symlink ออกเมื่อเว็บไซต์ของคุณทำงานได้ตามปกติแล้ว
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginxบล็อกเซิร์ฟเวอร์ขนาดเล็กที่สุดสำหรับการทำ Proxy ให้แอปพลิเคชันเดียว
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
}
}บันทึกไฟล์นี้เป็น /etc/nginx/sites-available/app.example.com จากนั้นเปิดใช้งานและโหลดการตั้งค่าใหม่
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; จะผูกกับ IPv4 และ listen [::]:80; จะผูกกับ IPv6 หากละบรรทัดที่สองไว้ การเชื่อมต่อ IPv6 ทั้งหมดที่เข้ามายังเซิร์ฟเวอร์ของคุณจะถูกปฏิเสธ เบราว์เซอร์แบบ dual-stack ที่ค้นหา DNS (domain name system) แล้วได้ record เป็น AAAA มักจะถอยกลับไปใช้ IPv4 ทำให้ปัญหาถูกบดบังไป แต่ผู้ใช้งานที่ใช้ IPv6 เท่านั้น หรือไคลเอนต์ที่พยายามเชื่อมต่อเฉพาะที่อยู่แรกที่ได้รับ จะพบกับข้อผิดพลาดการเชื่อมต่อถูกปฏิเสธ ในขณะที่ผู้ใช้งานผ่าน IPv4 ทุกคนยังคงเข้าใช้งานเว็บไซต์ได้ตามปกติ รายงานข้อผิดพลาดที่คุณได้รับจึงมักระบุว่า "ใช้งานได้ปกติสำหรับฉัน"
server_name จะถูกนำไปเทียบกับ header Host ที่เบราว์เซอร์ส่งมา คุณสามารถระบุชื่อโดเมนหลายชื่อได้โดยคั่นด้วยช่องว่าง หากไม่มีบล็อกใดตรงกัน Nginx จะใช้บล็อกที่เป็น default_server ซึ่งเป็นเหตุผลว่าทำไมเว็บไซต์ที่ติดตั้งมาพร้อมกับแพ็กเกจจึงต้องถูกลบออก
location / เป็นการจับคู่แบบ prefix กับ path ของคำขอ และ / จะจับคู่กับทุก path ส่วน proxy_pass คือที่อยู่ที่ Nginx จะเปิดการเชื่อมต่อเข้าไปหา ควรให้แอปพลิเคชันผูกไว้กับ 127.0.0.1 เท่านั้น เพื่อให้เส้นทางเดียวที่จะเข้าถึงได้คือผ่านทาง Nginx หากแอปพลิเคชันทำงานในคอนเทนเนอร์ ให้ publish พอร์ตเป็น 127.0.0.1:3000:3000 แทนที่จะเป็น 3000:3000 เพราะ Docker จะเขียนกฎของตัวเองและเปิดพอร์ตข้าม ufw ไปโดยตรง ทำให้พอร์ตที่เปิดไว้สามารถเข้าถึงได้จากอินเทอร์เน็ตไม่ว่า ufw จะตั้งค่าไว้อย่างไรก็ตาม Docker ได้ระบุถึง chain DOCKER-USER ว่าเป็นจุดสำหรับกรอง traffic ดังกล่าว แต่การผูกไว้กับ 127.0.0.1 เป็นวิธีแก้ไขที่ง่ายกว่า
บรรทัด curl จะส่ง header Host ที่ถูกต้องจากตัวเซิร์ฟเวอร์เอง เพื่อให้คุณสามารถทดสอบบล็อกนี้ได้ก่อนที่จะชี้ DNS ไปยังที่ใดก็ตาม
สิ่งที่ nginx ส่งไปยัง upstream เมื่อคุณไม่ได้กำหนดค่าอื่นเพิ่มเติม
proxy_pass เพียงอย่างเดียวจะปิดบังข้อมูล 4 ประการจากแอปพลิเคชันของคุณ
แพ็กเกจ nginx 1.24.0 ที่มาพร้อมกับ Ubuntu 24.04 จะสื่อสารกับ backend ด้วย HTTP/1.0 เป็นค่าเริ่มต้นและส่ง Connection: close ทำให้ทุกคำขอต้องเปิดการเชื่อมต่อ upstream ใหม่เสมอและไม่สามารถอัปเกรดโปรโตคอลได้ ส่วน nginx 1.29.7 ซึ่งปล่อยออกมาในเดือนมีนาคม 2026 ได้เปลี่ยนค่าเริ่มต้นเหล่านี้ โดยตั้งแต่เวอร์ชันนั้นเป็นต้นไป nginx จะสื่อสารกับ upstream ด้วย HTTP/1.1 ไม่ส่ง header Connection และนำการเชื่อมต่อใน pool กลับมาใช้ใหม่แทนการเปิดการเชื่อมต่อใหม่ในทุกคำขอ อย่างไรก็ตาม การอัปเกรด WebSocket ยังคงต้องใช้ header ตามที่แสดงไว้ในส่วนถัดไป
header Host จะถูกเขียนทับด้วยค่าใน proxy_pass ซึ่งก็คือ 127.0.0.1:3000 ส่งผลให้แอปที่สร้างลิงก์แบบสัมบูรณ์ (absolute links) จาก Host สร้างลิงก์ที่ไม่มีใครภายนอกเซิร์ฟเวอร์สามารถเปิดใช้งานได้
การเชื่อมต่อที่ส่งถึงแอปมาจาก nginx ทำให้แอปมองเห็นที่อยู่ของไคลเอนต์เป็น 127.0.0.1 ส่งผลให้ทุกบรรทัดใน log และทุกการจำกัดอัตรา (rate limit) ภายในแอปบันทึกเป็นตัว proxy แทนที่จะเป็นผู้เข้าชมจริง
แอปไม่สามารถทราบได้ว่าเบราว์เซอร์ใช้ HTTPS เนื่องจากเป็นการเชื่อมต่อแบบ HTTP ธรรมดาบน loopback address
การเพิ่ม 4 บรรทัดนี้จะแก้ไขปัญหาทั้งหมดดังกล่าวได้
ส่วนหัว 4 รายการที่ต้องตั้งค่า และสิ่งที่แต่ละรายการช่วยให้แบ็กเอนด์มองเห็น
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 จะระบุชื่อโดเมนที่ผู้เข้าชมพิมพ์เข้ามา $host คือชื่อที่ได้จากคำขอโดยตัดพอร์ตออกและแปลงเป็นตัวพิมพ์เล็ก การตั้งค่านี้ช่วยให้แอปพลิเคชันของคุณสร้าง absolute URL ได้ถูกต้อง เช่น การเปลี่ยนเส้นทางหลังเข้าสู่ระบบ หรือลิงก์ในอีเมลรีเซ็ตรหัสผ่าน หากไม่ตั้งค่า แอปพลิเคชันจะใช้ 127.0.0.1:3000 เป็นชื่อของตัวเอง ค่าเริ่มต้น proxy_redirect ของ nginx จะเขียนทับส่วนหัว Location หรือ Refresh ที่ชี้ไปยังที่อยู่ proxy_pass ทำให้การเปลี่ยนเส้นทางหลังเข้าสู่ระบบมักจะทำงานได้ถูกต้อง แต่ absolute URL ที่แอปเขียนลงในหน้าเว็บและอีเมล เช่น ลิงก์รีเซ็ตรหัสผ่าน จะชี้ไปยัง 127.0.0.1:3000 ซึ่งเป็นที่อยู่ที่เบราว์เซอร์ของผู้เข้าชมไม่สามารถเข้าถึงได้ หากแอปของคุณต้องการพอร์ตด้วยเนื่องจากคุณให้บริการบนพอร์ต 8080 ให้ใช้ $http_host ซึ่งเป็นส่วนหัวที่ตรงกับสิ่งที่ไคลเอนต์ส่งมาทุกประการ
X-Real-IP จะระบุค่าเดียวคือ $remote_addr ซึ่งเป็นที่อยู่ที่ nginx ยอมรับการเชื่อมต่อเข้ามา แอปพลิเคชันจะอ่านค่านี้เพื่อใช้ใน access log และการทำ rate limiting ของตัวเอง
X-Forwarded-For จะระบุรายการที่อยู่ $proxy_add_x_forwarded_for จะผนวก $remote_addr ต่อท้ายสิ่งที่ไคลเอนต์ใส่มาในส่วนหัวนั้นอยู่แล้ว ทำให้ค่าที่ได้ถูกคั่นด้วยเครื่องหมายจุลภาคและรายการที่ nginx เพิ่มเข้าไปจะอยู่ท้ายสุด รายละเอียดนี้เป็นตัวตัดสินว่าส่วนหัวนั้นเชื่อถือได้หรือไม่ เนื่องจากไคลเอนต์สามารถส่ง X-Forwarded-For อะไรก็ได้ที่ต้องการ ดังนั้นแอปที่อ่านค่าจากรายการแรกอาจถูกหลอกด้วยที่อยู่ใดก็ได้ เมื่อ nginx ทำหน้าที่เป็น edge server ให้เขียน $remote_addr แทนและละทิ้งค่าที่ไคลเอนต์ส่งมา หากมี CDN หรือพร็อกซีอื่นอยู่ด้านหน้า ให้ใช้ set_real_ip_from และ real_ip_header จากโมดูล realip เพื่อให้ $remote_addr กลายเป็นที่อยู่จริงของไคลเอนต์
X-Forwarded-Proto จะระบุค่า http หรือ https เฟรมเวิร์กจะอ่านค่านี้เพื่อตัดสินใจว่าจะทำเครื่องหมายคุกกี้เป็น Secure หรือไม่ และจะบังคับเปลี่ยนเส้นทางไปยัง HTTPS หรือไม่ หากละเว้นส่วนหัวนี้ในไซต์ที่ใช้ TLS แอปที่ตั้งค่าให้บังคับ HTTPS จะมองเห็นค่าเป็น http และตอบกลับด้วยการเปลี่ยนเส้นทางไปยังที่อยู่ HTTPS จากนั้นเมื่อได้รับคำขอถัดไปผ่าน nginx ก็ยังคงมองเห็นค่าเป็น http และทำการเปลี่ยนเส้นทางซ้ำอีกครั้ง จนเบราว์เซอร์ยอมแพ้และแสดงข้อผิดพลาด ERR_TOO_MANY_REDIRECTS
การทำซ้ำบรรทัดทั้งสี่นี้ในทุก location จะทำให้การตั้งค่าไม่สอดคล้องกัน ควรนำไปรวมไว้ในไฟล์เดียวแล้วใช้คำสั่ง include แทน
# /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;
}การสืบทอดค่าในส่วนนี้มีข้อควรระวัง คือ location จะสืบทอดคำสั่ง proxy_set_header จาก server block ก็ต่อเมื่อ location นั้นไม่มีการกำหนดค่าของตัวเอง หากคุณเพิ่ม proxy_set_header เข้าไปใน location เพียงรายการเดียว ส่วนหัวทั้งหมดที่กำหนดไว้ในระดับ server จะถูกยกเลิกสำหรับ location นั้น ดังนั้นควรเก็บค่าทั้งหมดไว้ในระดับเดียว หรือใช้คำสั่ง include เพื่อเรียกใช้ snippet ในทุก location ที่มีการทำ proxy
ทำไมแอป WebSocket ของฉันถึงเชื่อมต่อได้แล้วตัดการเชื่อมต่อ?
เพราะค่าเริ่มต้นไม่อนุญาตให้ทำการอัปเกรด และค่า read timeout เริ่มต้นจะปิด tunnel ที่ไม่มีการใช้งานหลังจากผ่านไป 60 วินาที WebSocket เริ่มต้นด้วยคำขอ HTTP ที่มี Upgrade: websocket และ Connection: Upgrade ซึ่งเป็น hop-by-hop headers หมายความว่า proxy ควรจะประมวลผล header เหล่านี้แทนที่จะส่งต่อ และใน nginx 1.24.0 บน Ubuntu 24.04 โปรโตคอล upstream เริ่มต้นคือ HTTP/1.0 ซึ่งไม่มีกลไกการอัปเกรดเลย ทั้งสองอย่างจึงต้องถูกกำหนดค่ากลับเข้าไปด้วยตนเอง
ให้ใส่ map ไว้ในบริบท http โดยแยกไว้ในไฟล์ของมันเอง
# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}จากนั้นจึงกำหนดค่า 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 เพื่อให้ location เดียวสามารถรองรับทราฟฟิกได้ทั้งสองประเภท ในคำขอปกติ $http_upgrade จะว่างเปล่า ดังนั้น $connection_upgrade จะกลายเป็น close แต่ในคำขออัปเกรดจะมีค่าเป็น websocket ดังนั้น header ที่ส่งไปยัง upstream จึงเป็น Connection: upgrade การระบุ proxy_set_header Connection "upgrade"; แบบตายตัวจะส่ง header นั้นไปในทุกคำขอหน้าเว็บปกติด้วย ซึ่ง backend บางตัวอาจตอบกลับคำขอเหล่านั้นด้วยสถานะ 400
proxy_http_version 1.1; เป็นค่าเริ่มต้นตั้งแต่ nginx 1.29.7 เป็นต้นไป ดังนั้นในเวอร์ชันเหล่านั้นบรรทัดดังกล่าวจะไม่มีผลและไม่ก่อให้เกิดปัญหา ส่วนในแพ็กเกจ 1.24.0 จำเป็นต้องระบุบรรทัดนี้ ส่วนบรรทัด Upgrade และ Connection จำเป็นต้องมีในทุกเวอร์ชัน เพราะ nginx ไม่ส่งผ่าน header สองตัวนี้โดยอัตโนมัติ
proxy_read_timeout คือสาเหตุที่ทำให้เกิดรายงานว่า "โหลดได้แล้วหยุดอัปเดต" ค่าเริ่มต้นคือ 60 วินาที โดยวัดจากช่วงว่างระหว่างการอ่านข้อมูลจาก backend สองครั้ง ไม่ใช่ระยะเวลาทั้งหมดของ connection ดังนั้น WebSocket ที่ไม่มีการรับส่งข้อมูลเป็นเวลา 60 วินาทีจะถูก nginx ปิด และ console ของเบราว์เซอร์จะแสดงการปิด socket ด้วยรหัส 1006 แอปที่ส่ง heartbeat ของตัวเองบ่อยกว่านาทีละครั้งจะไม่พบปัญหานี้ ส่วนแอปที่ไม่ทำเช่นนั้นจะถูกตัดการเชื่อมต่อเมื่อครบนาที ปัญหานี้มักพบในโปรแกรมแก้ไขข้อมูลแบบเรียลไทม์และแดชบอร์ด โดยมี n8n ที่ติดตั้งเองหลัง HTTPS เป็นตัวอย่างที่พบบ่อย
เหตุใด trailing slash ใน proxy_pass ถึงเปลี่ยน URL ของคุณ?
กฎมีอยู่ประโยคเดียว หาก proxy_pass ลงท้ายด้วย URI (uniform resource identifier) แม้จะเป็นเพียง / เปล่าๆ nginx จะลบส่วนของ request path ที่ตรงกับ prefix ของ location ออก แล้วนำ URI นั้นไปใส่แทน หาก proxy_pass สิ้นสุดที่ host และ port ตัว request path จะถูกส่งผ่านไปโดยไม่มีการเปลี่ยนแปลง
location /app/ {
proxy_pass http://127.0.0.1:3000/;
}คำขอสำหรับ /app/status จะไปถึง backend ในรูปแบบ /status
location /app/ {
proxy_pass http://127.0.0.1:3000;
}คำขอสำหรับ /app/status จะไปถึง backend ในรูปแบบ /app/status
รูปแบบที่คุณต้องการขึ้นอยู่กับแอปพลิเคชัน แอปที่มีการตั้งค่า base-path หรือ sub-folder ต้องการรูปแบบที่สอง โดยต้องระบุค่า /app ไว้ในการตั้งค่า แอปที่ไม่รู้จัก prefix เลยต้องการรูปแบบแรก รูปแบบแรกมีผลกระทบที่คุณจะเห็นได้ทันที คือ HTML ที่แอปส่งกลับมายังคงมี absolute path เช่น /static/main.css ซึ่งเบราว์เซอร์จะร้องขอจาก site root ทำให้ไม่มี location ใดตรงกับคำขอ และหน้าเว็บจะแสดงผลโดยไม่มีการจัดรูปแบบ (styling) แท็บ network ในเบราว์เซอร์จะแสดงให้เห็นว่าคำขอ asset เหล่านั้นได้รับสถานะ 404 วิธีแก้ไขคือการตั้งค่า base-path ของตัวแอปเอง หรือเพิ่ม location /static/ ตัวที่สองที่ชี้ไปยัง backend เดียวกัน
regex location ไม่สามารถระบุ URI ใน proxy_pass ได้ sudo nginx -t จะปฏิเสธการตั้งค่าและระบุสาเหตุไว้ว่า: "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 หากต้องการเปลี่ยน path ภายใน regex location ให้ใช้ rewrite ที่ลงท้ายด้วย break นำหน้า proxy_pass ที่ไม่มี URI แทน และ ความต่างระหว่างแฟล็ก last กับ break ของคำสั่ง rewrite คือสิ่งที่ตัดสินว่าคำขอจะถูกส่งต่อไปยัง backend จาก location นั้น หรือถูกนำกลับไปค้นหา location ใหม่
ปัญหาประเภทนี้ทั้งหมดจะหมดไปเมื่อแต่ละแอปมีชื่อโดเมนเป็นของตนเอง app.example.com ซึ่งถูก proxy มาจาก location / การใช้ sub-path จะคุ้มค่ากับความยุ่งยากก็ต่อเมื่อคุณไม่สามารถเพิ่ม DNS record ได้เท่านั้น
ฉันจะกำหนด backend มากกว่าหนึ่งรายการภายใต้ชื่อเดียวได้อย่างไร?
ให้ใช้บล็อก upstream โดยบล็อกนี้อยู่ในบริบท http ดังนั้นให้เขียนไว้เหนือบล็อก server ในไฟล์เดียวกัน หรือใน /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;
}จากนั้นระบุชื่อในส่วน location ด้วยคำสั่ง proxy_pass http://app_backend;
วิธีเริ่มต้นคือ round robin ส่วน least_conn จะส่งคำขอไปยัง backend ที่มีจำนวนการเชื่อมต่อใช้งานอยู่น้อยที่สุด ซึ่งเหมาะกับคำขอที่มีระยะเวลาประมวลผลไม่เท่ากัน ส่วน ip_hash จะผูกที่อยู่ของไคลเอนต์ไว้กับ backend รายใดรายหนึ่ง คุณจำเป็นต้องใช้ ip_hash เมื่อแอปพลิเคชันเก็บ session ไว้ในหน่วยความจำของตัวเอง เพราะการทำ round robin สลับไปมาระหว่าง backend สองตัวจะทำให้ผู้ใช้หลุดจากระบบแบบสุ่ม เนื่องจากคำขอถูกส่งไปยัง instance ที่ไม่มีข้อมูล session นั้น การย้าย session ไปเก็บไว้ใน shared storage เป็นวิธีแก้ปัญหาที่ดีกว่า
max_fails=3 fail_timeout=30s หมายความว่าหากการเชื่อมต่อล้มเหลว 3 ครั้งภายใน 30 วินาที เซิร์ฟเวอร์นั้นจะถูกนำออกจากระบบเป็นเวลา 30 วินาที เมื่อเซิร์ฟเวอร์ทุกตัวในบล็อกอยู่ในสถานะดังกล่าว ไคลเอนต์จะได้รับข้อผิดพลาด 502 และ error log จะแสดงข้อความ no live upstreams while connecting to upstream
keepalive 32 จะคงการเชื่อมต่อที่ไม่ได้ใช้งานกับ backend ไว้สูงสุด 32 รายการต่อหนึ่ง worker process ซึ่งช่วยลดขั้นตอน TCP handshake ในคำขอส่วนใหญ่ สำหรับ nginx 1.24.0 บน Ubuntu 24.04 บรรทัดนี้คือสิ่งที่เปิดใช้งาน cache ตั้งแต่ nginx 1.29.7 เป็นต้นไป cache จะถูกเปิดใช้งานโดยค่าเริ่มต้น แต่ค่าเริ่มต้นตามเอกสารคือ keepalive 32 local; และพารามิเตอร์ local จะป้องกันไม่ให้การเชื่อมต่อที่ถูก cache ไว้ถูกแชร์ข้าม location อื่น ดังนั้นในเวอร์ชัน 1.29.7 ขึ้นไป การเขียน keepalive 32; เพียงอย่างเดียวไม่ใช่แค่การระบุค่าเริ่มต้น แต่การละ local ไว้จะทำให้ทุก location ที่ proxy ไปยัง upstream เดียวกันสามารถนำการเชื่อมต่อที่อยู่ใน pool มาใช้ซ้ำได้ ซึ่งเป็นการเปลี่ยนแปลงจากพฤติกรรมเริ่มต้น ในเวอร์ชันดังกล่าว ให้ละบรรทัดนี้ไว้หรือเขียน keepalive 32 local; เพื่อคงค่าเริ่มต้นไว้ และเขียนแบบไม่มีพารามิเตอร์เฉพาะเมื่อต้องการการแชร์การเชื่อมต่อเท่านั้น พารามิเตอร์ local เป็นของใหม่ใน 1.29.7 ดังนั้นแพ็กเกจ 1.24.0 จึงไม่รองรับ สำหรับ HTTP backend การตั้งค่าที่ nginx แนะนำสำหรับ pool คือการตั้ง proxy_http_version เป็น 1.1 (หรือ 2 ใน nginx 1.29.4 ขึ้นไป) โดยล้าง header Connection ที่ส่งไปยัง upstream ออก นอกจากนี้ nginx ยังระบุถึงการเชื่อมต่อแบบถาวรของ HTTP/1.0 ซึ่งทำได้โดยการส่ง Connection: Keep-Alive ไปยัง backend ที่รองรับ แต่ระบุว่าวิธีนี้ไม่แนะนำ ตั้งแต่เวอร์ชัน 1.29.7 เป็นต้นไป ทั้งสองส่วนของการตั้งค่าที่แนะนำถือเป็นค่าเริ่มต้นแล้ว สำหรับเวอร์ชัน 1.24.0 ให้เพิ่ม proxy_http_version 1.1; และ proxy_set_header Connection ""; ลงใน location ด้วยตนเอง มิฉะนั้น nginx จะยังคงส่ง HTTP/1.0 พร้อม Connection: close และ pool จะไม่ถูกนำมาใช้ซ้ำ หาก location เดียวกันมีการใช้ WebSocket map ด้วย ให้เปลี่ยนกรณีว่างจาก close เป็นสตริงว่าง เพื่อให้คำขอปกติไม่มี header Connection และสามารถนำการเชื่อมต่อใน pool มาใช้ซ้ำได้
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}ชื่อภายในบล็อก upstream จะถูก resolve เมื่อ nginx เริ่มทำงาน หาก backend ของคุณเป็นคอนเทนเนอร์ที่ได้รับที่อยู่ใหม่เมื่อรีสตาร์ท nginx จะยังคงใช้ที่อยู่เดิมจนกว่าคุณจะ reload nginx 1.27.3 ขึ้นไปสามารถติดตามการเปลี่ยนแปลงดังกล่าวได้โดยไม่ต้อง reload ผ่าน resolver, การใช้ zone ในบล็อก upstream และพารามิเตอร์ resolve ในแต่ละบรรทัด server แต่แพ็กเกจ 1.24.0 ยังไม่มีฟีเจอร์นี้ ภายในเครือข่าย Docker คุณสามารถย้ายการค้นหาที่อยู่ไปไว้ที่เวลาประมวลผลคำขอได้โดยใช้ embedded resolver
resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;เมื่อคอนเทนเนอร์มีการสร้างและทำลายบ่อยครั้งจนคุณต้องคอยแก้ไขไฟล์คอนฟิกของ nginx อยู่ตลอดเวลา การใช้ proxy ที่อ่านค่าจาก container labels จะเป็นเครื่องมือที่ดีกว่า Traefik สำหรับแอปพลิเคชัน Docker Compose หลายรายการ จะสร้างเส้นทาง (routes) จากตัวคอนเทนเนอร์โดยตรง
เหตุใดการอัปโหลดจึงล้มเหลวด้วยข้อผิดพลาด 413 Request Entity Too Large?
client_max_body_size มีค่าเริ่มต้นที่ 1 megabyte คำขอที่มีขนาดใหญ่กว่านี้จะถูก nginx ปฏิเสธก่อนที่แอปของคุณจะได้รับ และ log ของข้อผิดพลาดจะบันทึกว่า client intended to send too large body ให้เพิ่มค่านี้ใน server block หรือใน location ที่มีการอัปโหลดเกิดขึ้น
client_max_body_size 512m;ค่า 0 จะเป็นการปิดการตรวจสอบนี้โดยสมบูรณ์ แอปพลิเคชันของคุณมีขีดจำกัดของตัวเองเช่นกัน ดังนั้นหากยังคงพบข้อผิดพลาด 413 หลังจากเปลี่ยนค่านี้แล้ว แสดงว่าข้อผิดพลาดมาจากฝั่ง backend และการตั้งค่าการอัปโหลดของตัวแอปเองคือจุดถัดไปที่ควรตรวจสอบ
โดยปกติ nginx จะอ่าน request body ทั้งหมดก่อนที่จะเปิดการเชื่อมต่อกับ upstream โดยจะเขียนข้อมูลขนาดใหญ่ลงในไฟล์ชั่วคราวบนดิสก์ก่อน วิธีนี้ช่วยป้องกันแอปจาก client ที่ทำงานช้า เพราะ backend จะได้รับข้อมูลการอัปโหลดด้วยความเร็วเต็มที่ในระดับ local สำหรับการอัปโหลดขนาดใหญ่มาก คุณสามารถเลือกใช้การสตรีมแทนได้
proxy_request_buffering off;ในกรณีนี้ backend จะได้รับ body ทันทีที่ข้อมูลมาถึงและต้องสามารถจัดการกับข้อมูลนั้นได้ นอกจากนี้ nginx จะสูญเสียความสามารถในการลองส่งคำขอซ้ำไปยัง upstream อื่น เนื่องจาก body ได้ถูกส่งออกไปแล้ว
client_body_timeout ซึ่งมีค่าเริ่มต้นที่ 60 วินาที จะมีผลระหว่างการอ่าน body สองครั้งที่ต่อเนื่องกัน แทนที่จะเป็นระยะเวลาทั้งหมดของการอัปโหลด การอัปโหลดที่ช้าแต่ต่อเนื่องจะยังคงทำงานได้ ส่วนการอัปโหลดที่หยุดชะงักจะถูกตัดการเชื่อมต่อ
การทำ Response buffering และการตั้งค่าที่ทำให้การแสดงผลแบบสดใช้งานไม่ได้
proxy_buffering ถูกเปิดใช้งานเป็นค่าเริ่มต้นและโดยปกติแล้วเป็นสิ่งที่คุณต้องการ Nginx จะอ่านการตอบกลับจากแอปของคุณให้เร็วที่สุดเท่าที่แอปจะเขียนได้ จากนั้นจะพักข้อมูลไว้และส่งต่อไปยังไคลเอนต์ที่ช้าตามความเร็วของไคลเอนต์นั้นๆ ทำให้ worker ของแอปทำงานเสร็จสิ้นได้เร็วขึ้น แทนที่จะต้องค้างอยู่กับการดาวน์โหลดที่ช้าตลอดทั้งกระบวนการ
การตั้งค่านี้จะทำให้การตอบกลับแบบ streaming ใช้งานไม่ได้ โดย Server-sent events และการแสดงผล log แบบสดจะไม่ปรากฏให้ผู้ใช้เห็นจนกว่า buffer จะเต็ม ให้ปิดการทำ buffering เฉพาะในตำแหน่งนั้นเท่านั้น
proxy_buffering off;หากคุณเป็นผู้ควบคุมแอป วิธีที่ดีกว่าคือการส่ง header X-Accel-Buffering: no ไปพร้อมกับการตอบกลับแบบ streaming เท่านั้น Nginx จะอ่าน header ดังกล่าวในการตอบกลับแต่ละครั้งและปิดการทำ buffering เฉพาะรายการนั้น ทำให้หน้าเว็บทั่วไปยังคงได้รับประโยชน์จากการทำ buffering อยู่
เมื่อ error log แจ้งว่า upstream sent too big header while reading response header from upstream แสดงว่า header ของการตอบกลับมีขนาดใหญ่เกินกว่าจะใส่ใน buffer เดียวได้ proxy_buffer_size มีค่าเริ่มต้นเป็นหน่วยความจำหนึ่งหน้า (memory page) ซึ่งมีขนาด 4 หรือ 8 กิโลไบต์ขึ้นอยู่กับแพลตฟอร์ม หากมี cookie ที่ยาวหรือ header สำหรับการยืนยันตัวตนที่มีขนาดใหญ่จะทำให้เกิดการ overflow ให้เพิ่มค่าทั้งสองรายการนี้ขึ้น
proxy_buffer_size 16k;
proxy_buffers 8 16k;TLS ควรอยู่ในส่วนใดของ config นี้?
ที่ nginx ซึ่งอยู่หน้าทุกอย่างที่กล่าวมาข้างต้น TLS (transport layer security) จะสิ้นสุดที่ proxy และการเชื่อมต่อจาก nginx ไปยังแอปจะยังคงเป็น HTTP ปกติผ่าน loopback address ซึ่งไม่มีสิ่งอื่นใดบนเครือข่ายที่สามารถอ่านข้อมูลได้ แอปจะทราบว่าผู้เข้าชมใช้ HTTPS จาก X-Forwarded-Proto ซึ่งเป็น header ลำดับที่สี่จากทั้งหมดสี่รายการ
อย่าเขียน path ของ certificate ด้วยตนเอง ให้ชี้ DNS record ไปที่เซิร์ฟเวอร์ เปิด firewall และปล่อยให้ Certbot แก้ไข server block นี้ด้วยตัวเอง โดยมันจะเพิ่มบรรทัด listen 443 ssl พร้อมกับ path ของ ssl_certificate รวมถึงการ redirect จาก port 80 การออกใบรับรอง Let's Encrypt สำหรับ nginx ด้วย Certbot ครอบคลุมขั้นตอนการออกใบรับรองและตัวตั้งเวลาการต่ออายุ
sudo ufw allow 'Nginx Full'
sudo ufw statusNginx Full คือ application profile ที่แพ็กเกจ nginx ติดตั้งให้ ซึ่งจะเปิด port 80 และ port 443 พร้อมกัน port 80 จำเป็นต้องเปิดไว้สำหรับการตรวจสอบ HTTP-01 renewal challenge แม้ว่าผู้เข้าชมทุกคนจะถูก redirect ไปยัง HTTPS แล้วก็ตาม
ทดสอบการตั้งค่าแล้วจึงโหลดซ้ำ
sudo nginx -t
sudo systemctl reload nginxnginx -t จะตรวจสอบไฟล์ที่ถูกรวมเข้ามาทั้งหมด หากพบข้อผิดพลาด ระบบจะรายงานว่าการทดสอบสำเร็จหรือแสดงไฟล์และบรรทัดที่เกิดปัญหาให้ทราบ โปรดอ่านผลลัพธ์ดังกล่าวก่อนทำการโหลดซ้ำ การโหลดซ้ำด้วยการตั้งค่าที่ผิดพลาดจะไม่ส่งผลใดๆ เนื่องจาก Nginx จะยังคงให้บริการด้วยการตั้งค่าเดิม ทำให้เว็บไซต์ยังคงทำงานได้ตามปกติในขณะที่การแก้ไขของคุณไม่มีผลใดๆ ทั้งสิ้น systemctl restart มีพฤติกรรมที่ต่างออกไปและส่งผลเสียมากกว่า เนื่องจากการรีสตาร์ทจะหยุดการทำงานของเซิร์ฟเวอร์ก่อน หากการตั้งค่ามีข้อผิดพลาดจะส่งผลให้ Nginx ไม่สามารถทำงานได้เลย ควรเลือกใช้การโหลดซ้ำเป็นค่าเริ่มต้น และเก็บการรีสตาร์ทไว้ใช้เฉพาะกรณีที่จำเป็นต้องทำเท่านั้น
sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'บรรทัด ss จะแสดงให้เห็นว่าโพรเซสใดกำลังใช้งานพอร์ตแต่ละพอร์ตอยู่ เพื่อให้คุณยืนยันได้ว่าแอปพลิเคชันกำลังรับฟังการเชื่อมต่อในจุดที่ proxy_pass ระบุไว้จริง หากต้องการไล่ตรวจสอบให้ครบทุกชั้น แล็บตรวจสอบว่าพร็อกซีทำงานจริงหรือไม่ จะพาคุณรัน nginx -t, ss, curl และอ่าน log ตามลำดับ พร้อมวิธีอ่าน 502 Bad Gateway ให้รู้ว่าปัญหาอยู่ตรงจุดใด
ความล้มเหลวที่คุณจะพบจริง
502 Bad Gateway พร้อม connect() failed (111: Connection refused) while connecting to upstream ใน error log ไม่มีบริการใดฟังอยู่ที่ที่อยู่ตามที่ระบุใน proxy_pass แอปพลิเคชันอาจหยุดทำงาน ถูกผูกไว้กับพอร์ตอื่น หรือผูกไว้กับที่อยู่ภายในคอนเทนเนอร์ที่โฮสต์ไม่สามารถเข้าถึงได้
502 พร้อม no live upstreams while connecting to upstream เซิร์ฟเวอร์ทุกตัวในบล็อก upstream ถูกทำเครื่องหมายว่าล้มเหลวโดย max_fails ให้ซ่อมแซมแบ็กเอนด์เหล่านั้น nginx จะลองเชื่อมต่อใหม่อีกครั้งเมื่อ fail_timeout หมดอายุ
504 Gateway Time-out พร้อม upstream timed out (110: Connection timed out) while reading response header from upstream แบ็กเอนด์ยอมรับการเชื่อมต่อแล้วแต่ไม่ส่งข้อมูลใดๆ กลับมาเป็นเวลา proxy_read_timeout วินาที การเพิ่มค่า timeout เป็นวิธีที่ถูกต้องสำหรับรายงานที่ช้าจริง แต่เป็นวิธีที่ผิดสำหรับแอปพลิเคชันที่ค้าง
ทุก path ส่งกลับ 404 จากแอปพลิเคชัน กฎเรื่อง trailing slash ได้เขียน path ใหม่ ให้เปรียบเทียบ path ที่แอปพลิเคชันบันทึกใน log กับ path ที่คุณร้องขอ
เว็บไซต์อื่นตอบกลับมา server_name ไม่ตรงกับ header Host คำขอดังกล่าวจึงหลุดไปที่บล็อก default_server
หน้าเว็บโหลดได้ แต่หน้าจอค้างหลังจากผ่านไปประมาณหนึ่งนาที นี่คือกรณีของ WebSocket: ขาดการจัดการ Upgrade หรือค่า proxy_read_timeout ยังคงเป็น 60 วินาที
FAQ
ทำไม nginx ถึงคืนค่า 502 Bad Gateway หลังจากที่ฉันเพิ่ม proxy_pass?
nginx ไม่สามารถเปิดการเชื่อมต่อกับที่อยู่ที่ระบุใน proxy_pass ได้ ให้ตรวจสอบ log ข้อผิดพลาดที่ /var/log/nginx/error.log เพื่อดูสาเหตุ: connect() failed (111: Connection refused) while connecting to upstream หมายความว่าไม่มีบริการใดกำลังฟังอยู่ที่พอร์ตนั้น และ no live upstreams หมายความว่าเซิร์ฟเวอร์ทุกตัวในบล็อก upstream ถูกทำเครื่องหมายว่าล้มเหลว ให้รันคำสั่ง sudo ss -lntp | grep 3000 เพื่อดูว่าโพรเซสใดกำลังใช้งานพอร์ตนั้นอยู่และผูกไว้กับที่อยู่ใด แอปพลิเคชันที่ผูกไว้กับที่อยู่ภายในคอนเทนเนอร์ หรือผูกกับพอร์ตที่ไม่ตรงกับที่คุณระบุไว้ จะทำให้เกิดข้อผิดพลาดนี้เสมอ
ทำไมแอปของฉันถึงตัดการเชื่อมต่อหลังจากผ่านไปประมาณหนึ่งนาทีเมื่ออยู่หลัง nginx?
การเชื่อมต่อดังกล่าวเป็น WebSocket และ proxy_read_timeout ยังคงค่าเริ่มต้นไว้ที่ 60 วินาที ซึ่งเป็นการวัดระยะห่างระหว่างการอ่านข้อมูลสองครั้งจากฝั่ง backend ซ็อกเก็ตที่ไม่มีการรับส่งข้อมูลจะถูก nginx ปิดการเชื่อมต่อ และคอนโซลของเบราว์เซอร์จะรายงานรหัสปิดการเชื่อมต่อ 1006 ให้ตั้งค่า proxy_http_version 1.1 (ซึ่งเป็นค่าเริ่มต้นตั้งแต่ nginx 1.29.7 แต่ไม่มีในแพ็กเกจ 1.24.0 ที่มากับ Ubuntu 24.04), ส่งผ่าน Upgrade และ Connection ด้วยคำสั่ง map บน $http_upgrade และเพิ่มค่า proxy_read_timeout ให้เป็นค่าที่สูงขึ้น เช่น 3600s หากไม่มี header Upgrade การอัปเกรดการเชื่อมต่อจะไม่เกิดขึ้นเลย ทำให้แอปพลิเคชันต้องถอยกลับไปใช้การ polling หรือไม่แสดงผลข้อมูลอัปเดตแบบเรียลไทม์
เครื่องหมาย slash ปิดท้ายใน proxy_pass มีผลหรือไม่?
มีผล และมันจะเปลี่ยน path ที่ฝั่ง backend ได้รับ ตัวอย่างเช่น หากใช้ location /app/ และ proxy_pass http://127.0.0.1:3000/ คำขอสำหรับ /app/status จะไปถึง backend ในรูปแบบ /status เนื่องจาก URI ใดๆ ที่ต่อท้าย host และพอร์ตจะเข้ามาแทนที่ prefix ของ location ที่จับคู่ไว้ หากคุณตัดเครื่องหมาย slash ปิดท้ายออก คำขอเดิมจะไปถึงในรูปแบบ /app/status การตัด prefix ออกมักจะทำให้ลิงก์ของไฟล์ asset ในแอปพลิเคชันเสีย เนื่องจากลิงก์เหล่านั้นยังคงเป็น absolute path และจะเกิดข้อผิดพลาด 404 ที่ root ของเว็บไซต์ ดังนั้นแอปพลิเคชันที่มีการตั้งค่า base-path จึงควรใช้รูปแบบที่ส่งผ่าน path ไปโดยตรงจะเหมาะสมกว่า
ทำไมแอปพลิเคชันของฉันถึงบันทึก log ว่าผู้เข้าชมทุกคนมี IP address เป็น 127.0.0.1?
เพราะการเชื่อมต่อที่แอปได้รับนั้นมาจาก nginx บน loopback address จริงๆ ที่อยู่ของผู้เข้าชมจะไปถึงแอปได้ก็ต่อเมื่อคุณตั้งค่า header ไว้เท่านั้น: ใช้ proxy_set_header X-Real-IP $remote_addr; สำหรับค่าเดียว และ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; สำหรับการต่อท้ายใน chain จากนั้นต้องตั้งค่าแอปพลิเคชันให้เชื่อถือ header เหล่านั้น โปรดจำไว้ว่าไคลเอนต์สามารถส่ง X-Forwarded-For ของตนเองมาได้ ดังนั้นเมื่อ nginx ทำหน้าที่เป็น edge server ให้เขียนทับด้วย $remote_addr แทนการต่อท้าย
ฉันจำเป็นต้องใช้ TLS ในการเชื่อมต่อระหว่าง nginx กับแอปของฉันหรือไม่?
ไม่จำเป็นหากแอปทำงานบนเซิร์ฟเวอร์เดียวกันและผูกไว้กับ 127.0.0.1 เพราะ traffic นั้นไม่ได้ออกไปนอกเครื่อง ให้ทำ TLS termination ที่ nginx, ใช้ proxy_pass เป็น HTTP ธรรมดาบน loopback และส่ง X-Forwarded-Proto $scheme เพื่อให้แอปทราบว่าผู้เข้าชมใช้ HTTPS หาก backend อยู่บนโฮสต์อื่นผ่านเครือข่ายที่คุณไม่สามารถควบคุมได้ การเชื่อมต่อช่วงนั้นจำเป็นต้องมีการป้องกันของตัวเอง ไม่ว่าจะเป็นการใช้ HTTPS ไปยัง backend หรือการสร้างอุโมงค์ส่วนตัวระหว่างเครื่องทั้งสอง