Khắc phục lỗi 'exec format error' trong Docker: Không tương thích kiến trúc CPU

Bối cảnh: Lỗi 'exec format error' do CPU không tương thích

Bạn đang cố gắng chạy một Docker container và nó thất bại ngay lập tức với một thông báo khó hiểu:

standard_init_linux.go:228: exec user process caused "exec format error"

Lỗi này thường xuất hiện khi tệp thực thi bên trong Docker image của bạn được biên dịch cho một kiến trúc CPU khác với máy chủ đang chạy Docker. Hãy hình dung nó giống như việc cố gắng chạy một ứng dụng Windows trên máy Mac mà không có lớp tương thích – máy sẽ đơn giản là không hiểu các hướng dẫn.

Điều này đã trở nên đặc biệt phổ biến với sự phát triển của phần cứng dựa trên ARM, đặc biệt là Apple Silicon Macs (chip M1, M2, M3) và các instance đám mây dựa trên ARM (như AWS Graviton). Nhiều Docker image hiện có được xây dựng cho kiến trúc amd64 (x86-64), và nếu bạn cố gắng chạy chúng trực tiếp trên máy arm64, bạn sẽ gặp phải trở ngại này.

Cá nhân tôi đã gặp lỗi này vô số lần khi di chuyển các dự án từ các máy Intel Mac cũ sang M1 MacBook Pro mới của mình, hoặc khi triển khai lên các máy chủ dựa trên ARM.

Gỡ lỗi không tương thích kiến trúc CPU

Khi bạn thấy lỗi exec format error, điều đầu tiên cần xác nhận là liệu đây có thực sự là vấn đề về kiến trúc hay không. Dưới đây là cách kiểm tra:

1. Xác định kiến trúc của máy chủ (Host Machine)

Mở terminal của bạn và chạy:

uname -m

Các kết quả điển hình:

• x86_64 hoặc amd64: Bạn đang sử dụng máy Intel/AMD 64-bit.
• aarch64 hoặc arm64: Bạn đang sử dụng máy ARM 64-bit (ví dụ: Apple Silicon Mac, Raspberry Pi, AWS Graviton).

2. Xác định kiến trúc dự kiến của Docker Image

Bạn có thể kiểm tra image mà bạn đang cố gắng chạy. Thay thế your-image-name:tag bằng image thực tế của bạn.

docker inspect your-image-name:tag | grep Architecture

Hoặc, đối với các image hỗ trợ nhiều nền tảng, bạn có thể cần sử dụng docker manifest inspect:

docker manifest inspect your-image-name:tag

Tìm các trường "platform" và "architecture". Nếu máy chủ của bạn là arm64 và kiến trúc của image là amd64 (hoặc ngược lại), bạn đã tìm thấy nguyên nhân.

Giải pháp: Đồng bộ kiến trúc hoặc xây dựng Multi-Platform Images

Khi bạn đã xác nhận sự không tương thích về kiến trúc, bạn có một vài cách để giải quyết. Cách tiếp cận tốt nhất phụ thuộc vào việc bạn kiểm soát quá trình xây dựng image hay chỉ đang sử dụng các image công khai.

Tùy chọn 1: Sử dụng Image Multi-Platform hiện có (Nếu có)

Nhiều image phổ biến hiện nay cung cấp hỗ trợ đa nền tảng. Thông thường, Docker sẽ tự động kéo kiến trúc phù hợp cho máy chủ của bạn. Tuy nhiên, đôi khi bạn cần chỉ định rõ ràng.

Kiểm tra tài liệu của image hoặc trang Docker Hub. Nếu nó hỗ trợ kiến trúc của bạn, bạn có thể chỉ cần kéo lại hoặc sử dụng một tag cụ thể.

docker pull your-image-name:tag # Docker có thể tự chọn bản phù hợp
docker pull your-image-name:tag-arm64 # Hoặc một tag cụ thể cho kiến trúc của bạn

Tùy chọn 2: Tự xây dựng Image Multi-Platform bằng Docker Buildx (Khuyến nghị)

Nếu bạn đang tự xây dựng các image của mình, Docker Buildx là công cụ tốt nhất để tạo ra các image hoạt động trên các kiến trúc khác