Sửa lỗi Nginx: [emerg] module is not binary compatible

Tình huống lỗi

Bạn có thể gặp lỗi này ngay sau khi cập nhật hệ thống (apt upgrade hoặc yum update) hoặc sau khi di chuyển cấu hình Nginx giữa các máy chủ một cách thủ công. Khi bạn cố gắng khởi động hoặc reload Nginx, nó sẽ thất bại, và việc chạy nginx -t sẽ hiển thị một thông báo quan trọng:

nginx: [emerg] module "/etc/nginx/modules/ngx_http_geoip_module.so" is not binary compatible
nginx: configuration file /etc/nginx/nginx.conf test failed

Lỗi này ngăn Nginx khởi động, khiến website của bạn bị ngoại tuyến. Nó thường xảy ra với các module như GeoIP, Image Filter, hoặc PageSpeed khi file Nginx core binary và dynamic module (file .so) không đồng bộ với nhau.

Tại sao Binary Compatibility lại quan trọng

Không giống như một số ứng dụng sử dụng Plugins/APIs ổn định, các Nginx dynamic modules được liên kết chặt chẽ với Nginx binary. Nginx sử dụng một cấu trúc nội bộ gọi là Application Binary Interface (ABI). Mỗi khi Nginx được biên dịch, chữ ký của nó sẽ được nhúng vào các module.

Nếu bạn cập nhật phiên bản Nginx từ 1.18.0 lên 1.20.1, nhưng vẫn giữ file ngx_http_geoip_module.so cũ từ bản build 1.18.0, các cấu trúc bộ nhớ sẽ không khớp. Nginx phát hiện sự không khớp này trong quá trình thực thi chỉ thị load_module và dừng tiến trình để ngăn chặn hiện tượng memory corruption hoặc các sự cố không mong muốn.

Bước 1: Chẩn đoán lỗi Version Mismatch

Trước khi áp dụng bản sửa lỗi, hãy xác nhận phiên bản Nginx bạn đang chạy và so sánh nó với phiên bản dự kiến của module.

nginx -V

Tìm kiếm flag --with-compat trong kết quả đầu ra. Nếu Nginx được biên dịch với --with-compat, nó sẽ có khả năng chịu lỗi cao hơn một chút đối với sự khác biệt phiên bản, nhưng các bản cập nhật lớn vẫn sẽ làm hỏng các module. Hãy lưu lại số phiên bản (ví dụ: 1.24.0).

Giải pháp A: Đồng bộ hóa qua Package Manager (Dễ nhất)

Nếu bạn cài đặt Nginx bằng một package manager như apt hoặc yum, sự không khớp thường xảy ra do gói module bị giữ lại hoặc được cập nhật từ một repository khác. Cách sửa lỗi đáng tin cậy nhất là cài đặt lại gói module cụ thể khớp với phiên bản Nginx hiện tại của bạn.

Trên Ubuntu/Debian:

# Cập nhật danh sách repository
sudo apt update

# Cài đặt lại Nginx core và module đang gặp sự cố
sudo apt install --reinstall nginx-core libnginx-mod-http-geoip

Trên CentOS/RHEL:

sudo yum reinstall nginx-mod-http-geoip

Nếu lỗi vẫn tiếp diễn, có thể là do bạn đang sử dụng repository chính thức của Nginx (nginx.org) trong khi module được cài đặt từ repository mặc định của hệ điều hành (hoặc ngược lại). Hãy đảm bảo tất cả các thành phần của Nginx đều đến từ cùng một nguồn.

Giải pháp B: Biên dịch Module thủ công (Nâng cao)

Nếu bạn đang sử dụng một bản build Nginx tùy chỉnh hoặc một module không có trong các repository tiêu chuẩn, bạn phải biên dịch module đó dựa trên Nginx source code hiện tại.

1. Tải xuống Nginx source tương ứng

Tìm phiên bản của bạn bằng nginx -v và tải xuống chính xác source code đó.

wget http://nginx.org/download/nginx-$(nginx -v 2>&1 | cut -d '/' -f 2).tar.gz
tar -xzvf nginx-*.tar.gz
cd nginx-*

2. Cấu hình môi trường build

Bạn cần sử dụng chính xác các cấu hình flags giống như file Nginx binary hiện tại. Bạn có thể lấy các thông tin này từ nginx -V.

# Sao chép các 'configure arguments' từ nginx -V và thêm flag cho module
./configure --with-compat --add-dynamic-module=/path/to/module/source

3. Chỉ biên dịch các module

Thay vì chạy toàn bộ lệnh make install, bạn chỉ cần các file module.

make modules

4. Thay thế file .so cũ

Module mới sẽ nằm trong thư mục objs/. Hãy sao chép nó vào thư mục Nginx modules.

sudo cp objs/ngx_http_geoip_module.so /etc/nginx/modules/
# Kiểm tra quyền truy cập
sudo chmod 644 /etc/nginx/modules/ngx_http_geoip_module.so

Xác minh

Sau khi bạn đã thay thế module hoặc cài đặt lại các gói, hãy luôn kiểm tra cấu hình trước khi khởi động lại dịch vụ.

sudo nginx -t

Nếu bạn thấy syntax is ok và test is successful, bạn có thể khởi động lại Nginx một cách an toàn:

sudo systemctl restart nginx

Cách ngăn chặn lỗi này trong tương lai

Để tránh việc phải can thiệp thủ công sau mỗi lần cập nhật hệ thống, hãy tuân thủ các quy tắc sau:

Sử dụng Repository chính thức: Chỉ nên sử dụng duy nhất repository của Nginx.org hoặc repository ổn định của hệ điều hành. Việc trộn lẫn chúng là nguyên nhân hàng đầu gây ra lỗi binary compatibility.
Apt Pinning: Nếu bạn biên dịch Nginx thủ công, hãy sử dụng apt-mark hold nginx để ngăn package manager tự động cập nhật binary mà không cập nhật các module tùy chỉnh của bạn.
Tự động hóa: Nếu bạn sử dụng các module tùy chỉnh, hãy viết script cho quá trình "Download -> Configure -> Make Modules" để chạy như một phần của CI/CD hoặc quy trình thiết lập máy chủ.