Hướng dẫn cấu hình Khắc phục lỗi 502 Bad Gateway trên Nginx trên VPS/Server (A-Z)

Chào bạn. Với tư cách là một Quản trị hệ thống, tôi hiểu rằng lỗi 502 Bad Gateway là một trong những lỗi gây ức chế nhất vì nó không chỉ ra ngay lập tức vấn đề nằm ở đâu. Về bản chất, Nginx đang đóng vai trò là một Proxy (cổng chào), và nó không nhận được phản hồi hợp lệ từ các dịch vụ phía sau (Backend) như PHP-FPM, Node.js, Python hoặc Docker.

Dưới đây là quy trình xử lý chuẩn hóa, đảm bảo tính ổn định và bảo mật cho hệ thống của bạn.

## Yêu cầu chuẩn bị

Trước khi can thiệp vào hệ thống, đảm bảo VPS của bạn đáp ứng các điều kiện tối thiểu để tránh lỗi phát sinh do cạn kiệt tài nguyên:

• Hệ điều hành: Linux (Ubuntu 20.04+, CentOS 7+, Debian 10+).
• RAM: Tối thiểu 1GB (Nếu RAM thấp, MySQL/PHP-FPM thường bị crash dẫn đến lỗi 502).
• Quyền hạn: Truy cập Root hoặc tài khoản có quyền sudo.

## Cảnh báo quan trọng

NGUYÊN TẮC VÀNG: Trước khi chỉnh sửa bất kỳ file cấu hình nào hoặc khởi động lại dịch vụ:

1. Backup/Snapshot: Thực hiện Snapshot VPS trên trình quản lý của nhà cung cấp.
2. Backup Config: Sao lưu file cấu hình gốc bằng lệnh:

   cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

3. Không thử sai trên Production: Nếu có thể, hãy tái lập lỗi trên môi trường Staging trước.

## Hướng dẫn cài đặt và xử lý (Từng bước)

Bước 1: Phân tích Log lỗi (Bắt buộc)

Đừng đoán mò. Hãy để Log dẫn đường. Đây là bước quan trọng nhất của một chuyên gia.

tail -n 50 /var/log/nginx/error.log

Giải thích: Lệnh này hiển thị 50 dòng cuối cùng của file log lỗi Nginx. Hãy tìm các từ khóa như “connect failed”, “permission denied”, hoặc “upstream prematurely closed connection”.

Bước 2: Kiểm tra trạng thái dịch vụ Backend

Lỗi 502 thường xảy ra khi dịch vụ xử lý code (PHP, Node,…) bị chết.

Đối với PHP-FPM (Phổ biến nhất):

# Kiểm tra phiên bản PHP đang dùng (vớ dụ 7.4, 8.1, 8.2)
ls /var/run/php/
# Kiểm tra trạng thái (Ví dụ PHP 8.1)
systemctl status php8.1-fpm

Nếu dịch vụ đang inactive hoặc failed, hãy khởi động lại:

systemctl restart php8.1-fpm

Bước 3: Cấu hình khớp nối giữa Nginx và PHP-FPM

Một lỗi phổ biến là Nginx gọi đến một Socket file không tồn tại hoặc sai đường dẫn.

Mở file cấu hình site của bạn (thường ở /etc/nginx/sites-available/):

nano /etc/nginx/sites-available/default

File cấu hình mẫu chuẩn (Best Practice):

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ .php$ {
        include snippets/fastcgi-php.conf;

        # Đảm bảo đường dẫn .sock này chính xác với phiên bản PHP đã cài đặt
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;

        # Tăng timeout để tránh 502 khi xử lý script nặng
        fastcgi_read_timeout 300;
        fastcgi_connect_timeout 300;
        fastcgi_send_timeout 300;
    }
}

Bước 4: Xử lý lỗi Buffers (Dành cho Web lớn/Proxy)

Nếu Backend của bạn trả về Header quá lớn, Nginx sẽ ngắt kết nối và báo lỗi 502. Hãy thêm các dòng sau vào block http trong /etc/nginx/nginx.conf:

nano /etc/nginx/nginx.conf

Thêm vào trong block http { ... }:

proxy_buffer_size          128k;
proxy_buffers              4 256k;
proxy_busy_buffers_size    256k;
fastcgi_buffer_size        128k;
fastcgi_buffers            4 256k;

## Kiểm tra hoạt động (Verify)

Sau khi chỉnh sửa, TUYỆT ĐỐI không restart Nginx ngay. Bạn phải kiểm tra cú pháp:

# Kiểm tra cú pháp cấu hình
nginx -t

Nếu kết quả trả về syntax is ok và test is successful, lúc này mới an toàn để reload:

# Reload để áp dụng cấu hình mà không làm gián đoạn kết nối hiện tại
systemctl reload nginx

Kiểm tra lại trạng thái các dịch vụ quan trọng:

systemctl status nginx
netstat -plntu # Kiểm tra các cổng đang lắng nghe

## Xử lý sự cố (Common Troubleshooting)

1. Lỗi “13: Permission denied” trong log

Lỗi này xảy ra khi Nginx không có quyền đọc file Socket của PHP-FPM.

• Cách sửa: Kiểm tra file /etc/php/X.X/fpm/pool.d/www.conf. Đảm bảo các dòng sau không bị comment:

  listen.owner = www-data
  listen.group = www-data
  listen.mode = 0660

  Sau đó restart PHP-FPM.

2. Lỗi do SELinux (Thường gặp trên CentOS/RHEL)

SELinux chặn Nginx kết nối với Backend.

• Cách kiểm tra: getenforce (Nếu trả về Enforcing).
• Cách sửa tạm thời để test: setenforce 0.
• Cách sửa triệt để:

  setsebool -P httpd_can_network_connect 1

3. Lỗi 502 khi dùng Docker

Nginx không thể kết nối tới Container Backend do sai tên Network hoặc Container bị restart liên tục.

• Cách sửa: Kiểm tra log container: docker logs <container_name>. Đảm bảo proxy_pass trong Nginx trỏ đúng IP hoặc tên Service trong Docker Compose.

4. Cạn kiệt tài nguyên (OOM Killer)

Kiểm tra xem RAM có bị hết không:

dmesg | grep -i kill

Nếu thấy “Out of memory: Kill process”, bạn cần nâng cấp RAM hoặc tối ưu lại MySQL/PHP-FPM (giảm pm.max_children).

Lời khuyên cuối cùng: Luôn giữ hệ thống tối giản. Càng ít cấu hình thừa, hệ thống càng ổn định. Chúc bạn xử lý thành công!

See more: Khắc phục lỗi 502 Bad Gateway trên Nginx.

Discover: Python Trick.