Chuyển tới nội dung chính

aaPanel: Khắc Phục Lỗi 504 Gateway Timeout

Giới Thiệu​

Lỗi "504 Gateway Timeout" là một trong những sự cố phổ biến mà người quản trị máy chủ phải đối mặt, đặc biệt là khi chạy các ứng dụng web phức tạp. Trong môi trường aaPanel, lỗi này thường xảy ra khi máy chủ web (Nginx hoặc Apache) không nhận được phản hồi kịp thời từ máy chủ ngược dòng (upstream server), mà trong hầu hết các trường hợp là PHP-FPM (FastCGI Process Manager) đang xử lý các tập lệnh PHP của bạn.

Nguyên nhân chính dẫn đến lỗi 504 bao gồm:

  • Tập lệnh PHP chạy quá lâu: Do truy vấn cơ sở dữ liệu chậm, vòng lặp vô hạn, hoặc xử lý dữ liệu lớn.
  • Thiếu tài nguyên máy chủ: CPU, RAM hoặc I/O bị quá tải.
  • Cấu hình timeout không phù hợp: Thời gian chờ giữa máy chủ web và PHP-FPM quá ngắn.
  • Lỗi ứng dụng: Code lỗi hoặc gặp sự cố.

Bài viết này sẽ hướng dẫn bạn các bước chi tiết để chẩn đoán và khắc phục lỗi 504 Gateway Timeout trên aaPanel.

📋 Thời gian: ~15-30 phút | Độ khó: Trung bình

Yêu Cầu​

Để thực hiện theo hướng dẫn này, bạn cần:

  • Một máy chủ đã cài đặt aaPanel và hoạt động.
  • Quyền truy cập SSH (root hoặc người dùng có quyền sudo) vào máy chủ.
  • Hiểu biết cơ bản về cấu hình máy chủ web (Nginx/Apache) và PHP.

Các Bước Thực Hiện​

Bước 1: Kiểm tra nhật ký lỗi (Error Logs)​

Việc đầu tiên và quan trọng nhất khi gặp bất kỳ lỗi nào là kiểm tra nhật ký. Nhật ký lỗi sẽ cung cấp manh mối về nguyên nhân gốc rễ của sự cố.

💡 Mẹo: Luôn bắt đầu từ nhật ký lỗi để tiết kiệm thời gian chẩn đoán.

Bạn có thể kiểm tra nhật ký thông qua giao diện aaPanel hoặc qua SSH.

Qua aaPanel:

  1. Đăng nhập vào bảng điều khiển aaPanel.
  2. Điều hướng đến mục "Website" ở thanh bên trái.
  3. Chọn trang web của bạn và nhấp vào "Logs".
  4. Kiểm tra các tab "Access Log" và "Error Log" để tìm các thông báo lỗi liên quan đến 504 hoặc các lỗi PHP.
  5. Ngoài ra, kiểm tra "System Log" trong mục "Logs" chính của aaPanel để xem các lỗi hệ thống.

Qua SSH: Sử dụng SSH để truy cập vào máy chủ của bạn và kiểm tra nhật ký:

# Xem nhật ký lỗi Nginx cho một trang web cụ thể
tail -f /www/wwwlogs/your_domain.com.error.log

# Xem nhật ký truy cập Nginx
tail -f /www/wwwlogs/your_domain.com.log

# Xem nhật ký PHP-FPM (có thể khác tùy phiên bản PHP)
# Ví dụ cho PHP 7.4
tail -f /www/server/php/74/var/log/php-fpm.log

# Hoặc kiểm tra thư mục chung cho nhật ký PHP-FPM
ls -l /var/log/php-fpm/

⚠️ Lưu ý: Thay thế your_domain.com và 74 bằng tên miền và phiên bản PHP tương ứng của bạn.

Bước 2: Điều chỉnh cấu hình PHP-FPM​

PHP-FPM thường là nguyên nhân chính gây ra lỗi 504 nếu tập lệnh PHP của bạn chạy quá lâu hoặc cần nhiều tài nguyên.

  1. Đăng nhập vào aaPanel.
  2. Điều hướng đến "App Store" -> "Installed".
  3. Tìm phiên bản PHP bạn đang sử dụng cho trang web bị lỗi (ví dụ: PHP-7.4) và nhấp vào "Settings".

2.1. Cấu hình php.ini​

Trong phần "Configuration File" (hoặc "php.ini"), tìm và điều chỉnh các giá trị sau:

  • max_execution_time: Thời gian tối đa (tính bằng giây) mà một tập lệnh có thể chạy. Tăng giá trị này nếu tập lệnh của bạn cần nhiều thời gian hơn. 
    max_execution_time = 300 ; Tăng lên 300 giây (5 phút) hoặc hơn nếu cần
  • memory_limit: Lượng bộ nhớ tối đa mà một tập lệnh có thể sử dụng. Nếu tập lệnh của bạn xử lý lượng dữ liệu lớn, nó có thể cần nhiều bộ nhớ hơn. 
    memory_limit = 256M ; Tăng lên 256MB, 512MB hoặc cao hơn tùy nhu cầu

Sau khi thay đổi, nhấp vào "Save".

2.2. Cấu hình PHP-FPM (Pool Settings)​

Trong phần "PHP-FPM Settings" (hoặc "Service Configuration"), điều chỉnh các giá trị sau:

  • request_terminate_timeout: Thời gian tối đa (tính bằng giây) mà một yêu cầu FastCGI được phép xử lý. Nếu vượt quá, nó sẽ bị hủy. 
    request_terminate_timeout = 300 ; Nên khớp hoặc cao hơn max_execution_time
  • pm.max_children: Số lượng tiến trình con tối đa có thể được tạo. Nếu số lượng này quá thấp, tất cả các tiến trình con có thể bận và không thể xử lý các yêu cầu mới, dẫn đến timeout. Tăng giá trị này nếu máy chủ của bạn có đủ RAM. 
    pm.max_children = 50 ; Tăng dần tùy theo tài nguyên RAM của bạn
    ⚠️ Cảnh báo: Tăng pm.max_children quá cao có thể dẫn đến hết RAM và làm treo máy chủ. Hãy giám sát việc sử dụng RAM sau khi thay đổi.
  • pm.start_servers, pm.min_spare_servers, pm.max_spare_servers: Các cài đặt này kiểm soát số lượng tiến trình PHP-FPM sẵn sàng và có thể giúp xử lý tải đột biến tốt hơn. Bạn có thể điều chỉnh chúng nếu pm.max_children đã được tăng.

Sau khi thay đổi, nhấp vào "Save".

2.3. Khởi động lại PHP-FPM​

Sau khi thay đổi cấu hình PHP-FPM, bạn cần khởi động lại dịch vụ để các thay đổi có hiệu lực. Trong phần "PHP-FPM Settings", nhấp vào "Restart". ✅ Thành công: Sau khi khởi động lại, hãy kiểm tra lại trang web của bạn.

Bước 3: Điều chỉnh cấu hình Web Server (Nginx/Apache)​

Nếu PHP-FPM đã được cấu hình đúng nhưng lỗi 504 vẫn tiếp diễn, có thể máy chủ web của bạn (Nginx hoặc Apache) đang hết thời gian chờ trước khi PHP-FPM có cơ hội hoàn thành công việc.

  1. Đăng nhập vào aaPanel.
  2. Điều hướng đến "Website" ở thanh bên trái.
  3. Chọn trang web của bạn và nhấp vào "Settings".
  4. Chọn tab "Nginx Config" hoặc "Apache Config" tùy thuộc vào máy chủ web bạn đang sử dụng.

3.1. Cấu hình Nginx​

Tìm khối location ~ .php$ và thêm hoặc điều chỉnh các dòng proxy_read_timeout sau:

# Thêm hoặc điều chỉnh các dòng sau trong khối http hoặc server hoặc location ~ .php$
http {
    # ...
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
    # ...
    server {
        # ...
        location ~ .php$ {
            # ...
            fastcgi_connect_timeout 300s; # Đối với FastCGI
            fastcgi_send_timeout 300s;   # Đối với FastCGI
            fastcgi_read_timeout 300s;   # Đối với FastCGI
            # ...
        }
    }
}

💡 Mẹo: Đối với aaPanel, các cài đặt fastcgi_timeout thường được ưu tiên hơn proxy_timeout khi proxy tới PHP-FPM. Đảm bảo rằng các giá trị này đủ cao, ít nhất bằng request_terminate_timeout của PHP-FPM.

Nhấp vào "Save" sau khi thay đổi.

3.2. Cấu hình Apache​

Nếu bạn đang sử dụng Apache với mod_proxy_fcgi hoặc mod_proxy, bạn có thể cần điều chỉnh ProxyTimeout.

# Thêm vào httpd.conf hoặc cấu hình VirtualHost của bạn
<VirtualHost *:80>
    # ...
    ProxyTimeout 300
    # ...
</VirtualHost>

Nhấp vào "Save" sau khi thay đổi.

3.3. Khởi động lại Web Server​

Sau khi thay đổi cấu hình Nginx hoặc Apache, bạn cần khởi động lại dịch vụ:

  • Đối với Nginx: Trong aaPanel, điều hướng đến "App Store" -> "Installed" -> "Nginx" -> "Settings" -> "Restart".
  • Đối với Apache: Trong aaPanel, điều hướng đến "App Store" -> "Installed" -> "Apache" -> "Settings" -> "Restart". ✅ Thành công: Sau khi khởi động lại, hãy kiểm tra lại trang web của bạn.

Bước 4: Kiểm tra tài nguyên hệ thống​

Đôi khi, lỗi 504 không phải do cấu hình timeout mà do máy chủ của bạn thực sự bị quá tải.

  1. Trong aaPanel: Điều hướng đến "Server Status" ở thanh bên trái.
  2. Kiểm tra các biểu đồ CPU, RAM và Disk I/O. Nếu chúng thường xuyên ở mức cao (gần 100%), máy chủ của bạn có thể đang thiếu tài nguyên.

Qua SSH: Sử dụng các lệnh sau để kiểm tra tài nguyên:

  • top hoặc htop: Theo dõi việc sử dụng CPU và RAM theo thời gian thực và các tiến trình đang chiếm dụng tài nguyên.
  • free -h: Kiểm tra việc sử dụng RAM.
  • df -h: Kiểm tra dung lượng đĩa.
  • iostat -xz 1 10: Kiểm tra I/O của đĩa (cần cài đặt sysstat).

Nếu tài nguyên bị thiếu hụt, bạn có thể cần:

  • Nâng cấp gói máy chủ (CPU, RAM).
  • Tối ưu hóa ứng dụng của bạn để sử dụng ít tài nguyên hơn (xem Bước 5).

Bước 5: Tối ưu hóa ứng dụng (nếu có thể)​

Nếu các bước trên không giải quyết được vấn đề hoặc bạn nhận thấy các tập lệnh PHP vẫn chạy quá lâu, vấn đề có thể nằm ở chính ứng dụng của bạn.

  • Tối ưu hóa truy vấn cơ sở dữ liệu: Đảm bảo các truy vấn SQL của bạn hiệu quả, sử dụng chỉ mục (index) phù hợp.
  • Sử dụng bộ nhớ đệm (caching): Triển khai bộ nhớ đệm cho các nội dung tĩnh, truy vấn cơ sở dữ liệu hoặc kết quả tính toán phức tạp.
  • Kiểm tra mã nguồn: Tìm kiếm các vòng lặp vô hạn, xử lý dữ liệu không hiệu quả hoặc các cuộc gọi API bên ngoài bị chặn.
  • Phân trang (pagination): Tránh tải tất cả dữ liệu cùng một lúc; sử dụng phân trang cho các danh sách lớn.

Troubleshooting​

  • Vẫn lỗi 504 sau khi tăng timeout:

    • ⚠️ Kiểm tra kỹ nhật ký: Có thể có một lỗi fatal trong ứng dụng PHP khiến nó bị crash hoặc không thể hoàn thành, ngay cả khi timeout đã được tăng.
    • Đảm bảo rằng tất cả các dịch vụ (PHP-FPM, Nginx/Apache) đã được khởi động lại thành công sau khi thay đổi cấu hình.
    • Kiểm tra tường lửa (firewall) hoặc SELinux có đang chặn kết nối giữa máy chủ web và PHP-FPM không (ít phổ biến trong aaPanel nhưng vẫn có thể xảy ra).

  • Lỗi 502 Bad Gateway thay vì 504:

    • Lỗi 502 thường chỉ ra rằng máy chủ web không thể kết nối với PHP-FPM. Điều này có thể do PHP-FPM bị crash, không chạy, hoặc có lỗi trong cấu hình socket/port.
    • Kiểm tra trạng thái của PHP-FPM: 
      systemctl status php-fpm-74.service # Thay 74 bằng phiên bản PHP của bạn
    • Nếu nó không chạy, hãy thử khởi động lại: 
      systemctl restart php-fpm-74.service

  • Các thay đổi cấu hình không có hiệu lực:

    • Đảm bảo bạn đã lưu các thay đổi và khởi động lại đúng dịch vụ.
    • Kiểm tra xem có tệp cấu hình nào bị ghi đè không (ví dụ: các tệp cấu hình do aaPanel tạo tự động).

Kết Luận​

Lỗi 504 Gateway Timeout trên aaPanel thường là dấu hiệu của việc các tập lệnh PHP chạy quá lâu hoặc máy chủ thiếu tài nguyên. Bằng cách thực hiện theo các bước trên, bạn có thể chẩn đoán và khắc phục hầu hết các trường hợp lỗi này.

Best practices:

  • Giám sát thường xuyên: Theo dõi hiệu suất máy chủ (CPU, RAM, Disk I/O) và nhật ký lỗi để phát hiện sớm các vấn đề.
  • Tối ưu hóa mã nguồn: Đảm bảo ứng dụng của bạn được viết hiệu quả, đặc biệt là các phần tương tác với cơ sở dữ liệu hoặc API bên ngoài.
  • Cấu hình phù hợp: Điều chỉnh các giá trị timeout và tài nguyên PHP-FPM/Web Server dựa trên tải thực tế và tài nguyên máy chủ của bạn.
  • Sử dụng bộ nhớ đệm: Triển khai các giải pháp bộ nhớ đệm (Redis, Memcached, OPcache) để giảm tải cho máy chủ.

Chúc bạn thành công!