Sửa lỗi API Docker 'Client Is Newer Than Server'

Tại sao lỗi này xảy ra

Lỗi này thường bắt đầu bằng một lệnh thông thường. Bạn chạy docker ps hoặc docker-compose up, và thay vì thấy các container, bạn lại nhận được lỗi không khớp phiên bản. Điều này xảy ra vì Docker sử dụng kiến trúc client-server. Client là công cụ terminal của bạn, và Server (Daemon) là engine chạy các container.

Cả hai giao tiếp qua REST API. Nếu gần đây bạn đã cập nhật Docker Desktop lên phiên bản 4.28 trở lên, client của bạn có khả năng đã được nâng cấp lên API phiên bản 1.44. Tuy nhiên, nếu máy chủ từ xa của bạn đang chạy phiên bản cũ hơn như Docker 20.10.x, nó chỉ hiểu API 1.41. Server từ chối kết nối vì nó không nhận diện được các tính năng mới hơn mà client đang cố gắng sử dụng.

Giải pháp 1: Buộc Client sử dụng API cũ hơn

Cách khắc phục nhanh nhất mà không cần cài đặt gì thêm là yêu cầu Docker CLI "hạ cấp" giao tiếp xuống mức của server. Docker được thiết kế để tương thích ngược, vì vậy việc này rất an toàn và hiệu quả.

Linux và macOS

Thiết lập biến môi trường cho phiên làm việc terminal hiện tại như sau:

export DOCKER_API_VERSION=1.41

Để duy trì thiết lập này, hãy thêm nó vào profile của shell. Đối với người dùng Zsh, hãy chạy lệnh sau:

echo 'export DOCKER_API_VERSION=1.41' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell)

Nếu bạn đang làm việc trong PowerShell, hãy sử dụng lệnh này để khắc phục tạm thời:

$env:DOCKER_API_VERSION = "1.41"

Để thay đổi vĩnh viễn, hãy mở menu Start và tìm kiếm "Edit the system environment variables" (Chỉnh sửa biến môi trường hệ thống). Thêm một biến mới tên là DOCKER_API_VERSION với giá trị là 1.41.

Giải pháp 2: Nâng cấp Docker Engine

Nếu bạn có quyền truy cập SSH vào server, nâng cấp engine là giải pháp tốt nhất về lâu dài. Điều này đảm bảo bạn có các bản vá bảo mật và cải thiện hiệu suất mới nhất. Trên server Ubuntu hoặc Debian, quá trình này mất khoảng 30 giây:

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
sudo systemctl restart docker

Sau khi cập nhật, server sẽ hỗ trợ API mới hơn và lỗi sẽ biến mất.

Giải pháp 3: Xử lý Docker Compose V2

Docker Compose hiện đại (lệnh docker compose) thường tự động tuân thủ biến DOCKER_API_VERSION. Nếu bạn vẫn đang sử dụng file thực thi docker-compose cũ, nó có thể hoạt động khác đi. Chúng tôi khuyên bạn nên chuyển sang plugin Docker Compose V2 để tránh những rắc rối từ phiên bản cũ.

Xác minh: Đã thành công chưa?

Kiểm tra trạng thái kết nối bằng cách chạy:

docker version

Kiểm tra các trường API version. Cả Client và Server hiện tại sẽ hiển thị các con số tương thích. Nếu bạn thấy 1.41 cho cả hai, bạn đã sẵn sàng.

Client:
 API version:  1.41

Server:
 Engine:
  API version: 1.41 (phiên bản tối thiểu 1.12)

Mẹo chuyên nghiệp để phòng ngừa

• Đồng bộ môi trường: Cố gắng giữ phiên bản Docker cục bộ của bạn trong khoảng một hoặc hai bản phát hành phụ (minor release) so với server production.
• Căn chỉnh CI/CD: Nếu GitHub Actions hoặc GitLab runner của bạn gặp lỗi này, hãy kiểm tra phiên bản docker-image được sử dụng trong file YAML của pipeline.
• Phiên bản riêng cho từng dự án: Bạn có thể tạo một file .env trong thư mục dự án với nội dung COMPOSE_API_VERSION=1.41. Điều này buộc mọi người trong nhóm sử dụng cùng một phiên bản API cho dự án cụ thể đó.