SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor · Cập nhật ngày 2026-10-21

Docker Compose: command và entrypoint khác gì?

ENTRYPOINT chạy chương trình, còn command truyền đối số. Xem đủ 4 cách override trong Compose và vì sao đặt entrypoint sẽ xóa CMD của image.

Lệnh command và entrypoint của Docker Compose, trong một quy tắc

Trong Docker Compose, entrypoint: đặt chương trình sẽ chạy và command: đặt các đối số truyền cho chương trình đó. Tiến trình của container là danh sách entrypoint, nối với danh sách command ở cuối. Mọi hành vi khác trên trang này đều bắt nguồn từ câu đó.

Hai key này tương ứng với hai chỉ thị trong Dockerfile. entrypoint: thay thế ENTRYPOINT của image. command: thay thế CMD của image. Chúng không độc lập với nhau, và đây là điểm khiến nhiều người gặp khó: đặt entrypoint: cũng loại bỏ CMD của image. Đặc tả Compose nêu rõ điều này. Nếu entrypoint khác null, Compose sẽ bỏ qua command mặc định của image.

Đọc những gì image đã khai báo

Trước khi ghi đè bất kỳ nội dung nào, hãy xem image đã cung cấp sẵn những gì.

docker image inspect --format '{{json .Config.Entrypoint}}' postgres:16
docker image inspect --format '{{json .Config.Cmd}}' postgres:16

Bạn nhận được ["docker-entrypoint.sh"] và ["postgres"], nên container chạy docker-entrypoint.sh postgres. Script đó tạo thư mục dữ liệu trong lần khởi động đầu tiên, đọc các biến POSTGRES_*, hạ quyền xuống user postgres, rồi thực thi các đối số được truyền vào. Xác định chính xác phần nào bạn muốn thay đổi là quyết định quan trọng nhất. Để truyền một flag cho database, bạn thay thế command:. Nếu thay thế entrypoint:, toàn bộ bước thiết lập đó sẽ không chạy.

Bốn tổ hợp, thể hiện trên một image nhỏ

Tạo một image chỉ có nhiệm vụ in danh sách đối số mà nó được khởi chạy cùng.

FROM alpine:3.20
ENTRYPOINT ["/bin/echo", "ep"]
CMD ["cmd"]
docker build -t argdemo .
services:
  demo:
    image: argdemo

Chạy docker compose up sau mỗi lần chỉnh sửa và đọc dòng duy nhất mà nó ghi vào log.

  • Không đặt key nào. Process là /bin/echo ep cmd và log hiển thị ep cmd.
  • Chỉ đặt command: ["cmd2"]. Process là /bin/echo ep cmd2. Entrypoint không thay đổi, chỉ có các đối số thay đổi.
  • Chỉ đặt entrypoint: ["/bin/echo", "ep2"]. Process là /bin/echo ep2 và log hiển thị ep2. cmd từ image bị loại bỏ mà không có cảnh báo nào.
  • Đặt cả hai key. Process là /bin/echo ep2 cmd2. Đây là trường hợp duy nhất bạn kiểm soát toàn bộ danh sách đối số.

Vì sao đặt entrypoint sẽ xóa CMD của image

CMD của image được ghi dưới dạng danh sách đối số mặc định cho ENTRYPOINT của image đó. Khi thay entrypoint, các đối số này sẽ thuộc về một chương trình không còn chạy nữa. Vì vậy Compose loại bỏ chúng thay vì tạo một command line mà tác giả image không hề dự định. docker run --entrypoint cũng hoạt động giống như vậy. Đây là hành vi của Docker, không phải lỗi riêng của Compose.

Hệ quả rất cụ thể. nginx:1.27 khai báo ENTRYPOINT ["/docker-entrypoint.sh"] và CMD ["nginx", "-g", "daemon off;"]. Khi đặt entrypoint: /custom-init.sh, script của bạn sẽ khởi động với một danh sách đối số rỗng. Một script kết thúc bằng exec "$@" theo cách thông thường sẽ không có gì để exec. Khi đó exec không làm gì, script chạy đến dòng cuối, rồi container thoát với code 0 mà không có thông báo lỗi nào.

Tự thêm lại các đối số:

services:
  web:
    image: nginx:1.27
    entrypoint: /custom-init.sh
    command: ["nginx", "-g", "daemon off;"]

Quy tắc cần nhớ: mỗi khi đặt entrypoint:, hãy quyết định luôn command: trong cùng lần chỉnh sửa.

Dạng exec và dạng shell, và điểm khác biệt của Compose

Dockerfile hỗ trợ 2 cú pháp. CMD ["nginx", "-g", "daemon off;"] là dạng exec: binary chạy trực tiếp, không có shell tham gia. CMD nginx -g "daemon off;" là dạng shell: Docker chuyển thành /bin/sh -c 'nginx -g "daemon off;"', nên shell chạy trước và chương trình của bạn trở thành tiến trình con của shell.

Compose không áp dụng quy tắc đó, và đây là điểm khiến nhiều người nhầm lẫn. Chuỗi trong command: được tách thành các đối số rồi thực thi trực tiếp, không có wrapper /bin/sh -c. Tài liệu tham chiếu của Compose nêu rõ: trường command không chạy trong context SHELL được định nghĩa trong image. Vì vậy, nếu cần các tính năng của shell, bạn phải tự gọi shell.

Đó là lý do command: echo "hello $$HOSTNAME" in ra nguyên văn hello $HOSTNAME. Không có shell nào đọc chuỗi này, nên không có gì mở rộng nó. Khi cần shell, hãy gọi shell:

services:
  demo:
    image: alpine:3.20
    command: /bin/sh -c 'echo "hello $$HOSTNAME"'

Tín hiệu, PID 1 và thao tác docker compose down sạch sẽ

docker compose stop và docker compose down gửi tín hiệu dừng container đến PID 1 bên trong từng container. Tín hiệu đó là SIGTERM, trừ khi STOPSIGNAL của image hoặc stop_signal: của service đặt một tín hiệu khác. Sau đó Compose chờ tối đa stop_grace_period rồi chỉ gửi SIGKILL nếu container vẫn đang chạy. Thời gian chờ mặc định là 10 giây.

PID 1 có hành vi đặc biệt trong Linux. Kernel không áp dụng hành động mặc định của tín hiệu cho PID 1. Vì vậy, tiến trình không cài SIGTERM handler sẽ đơn giản bỏ qua SIGTERM khi chạy với PID 1. Tiến trình đó sẽ chạy hết thời gian chờ rồi bị kill ngay, làm gián đoạn mọi kết nối đang mở hoặc transaction chưa commit.

Đặt shell trước chương trình làm tình huống này dễ xảy ra hơn, vì shell là PID 1 và hầu hết shell không chuyển tiếp tín hiệu cho tiến trình con. Một số shell tự thay thế bằng lệnh cuối trong chuỗi -c, nên đôi khi chương trình của bạn vẫn nhận PID 1. Điều này phụ thuộc vào shell và chuỗi lệnh cụ thể, vì vậy không được đoán. Hãy đọc giá trị đó:

docker compose exec -T web cat /proc/1/cmdline | tr '\0' ' '; echo

Nếu PID 1 hiển thị là /bin/sh -c ... thay vì chương trình của bạn, có 2 cách sửa. Dùng exec form trong image, hoặc giữ shell và chuyển quyền điều khiển tiến trình bằng exec:

services:
  web:
    image: myapp:1.4
    command: /bin/sh -c 'exec myapp --config /etc/myapp.toml'

exec thay thế tiến trình shell bằng chương trình của bạn thay vì fork một tiến trình con. Vì vậy, chương trình của bạn kế thừa PID 1 và nhận được tín hiệu.

Một số chương trình tạo tiến trình con nhưng không bao giờ reap chúng, khiến xuất hiện zombie process, vì PID 1 cũng là reaper. Compose có một tùy chọn cho trường hợp này:

services:
  web:
    image: myapp:1.4
    init: true
    stop_grace_period: 30s

init: true chạy một init process nhỏ với vai trò PID 1. Process này chuyển tiếp tín hiệu đến chương trình của bạn và reap các tiến trình con. stop_grace_period cho phép quá trình shutdown thực sự chậm có thêm thời gian. Nếu chương trình của bạn cần một tín hiệu khác, stop_signal: SIGQUIT thay đổi tín hiệu mà Compose gửi. Dùng docker image inspect --format '{{.Config.StopSignal}}' nginx:1.27 để xem image hiện đang yêu cầu tín hiệu nào.

Một stack mà docker compose down luôn mất 10 giây cho mỗi service cho thấy không có tiến trình nào xử lý SIGTERM. Hãy sửa việc đó trước khi đổ lỗi cho tooling, và xem sự khác nhau giữa docker compose down và stop để biết mỗi subcommand xóa những gì.

Sự khác nhau giữa exec và shell cũng xuất hiện ở một nơi khác. Healthcheck viết dưới dạng test: ["CMD", "curl", "-f", "http://localhost/"] sẽ chạy binary trực tiếp, còn test: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"] sẽ chạy thông qua shell để || có ý nghĩa. Cách viết healthcheck cho Compose để báo lỗi trung thực giải thích các phần còn lại của trường đó.

Thêm một flag vào image chính thức

Đây là phần hầu hết người đọc cần. Bạn muốn thêm một flag cho postgres nhưng không được làm ảnh hưởng đến script khởi tạo.

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    command: postgres -c max_connections=200 -c shared_buffers=256MB

volumes:
  pgdata:

Chỉ command: được thay đổi, nên docker-entrypoint.sh vẫn chạy và vẫn thực thi nội dung bạn cung cấp. Hãy kiểm tra kết quả thay vì mặc định cho rằng mọi thứ đúng:

docker compose up -d db
docker compose exec -T db psql -U postgres -c 'show max_connections;'

Output phải hiển thị 200. Nếu vẫn hiển thị 100, hãy chạy docker compose config và xác nhận command bạn mong đợi có trong output sau khi hợp nhất. Compose hợp nhất các file override bằng cách thay thế hoàn toàn command, không nối thêm vào đó. Vì vậy, file thứ hai cũng đặt command: sẽ âm thầm ghi đè giá trị trước đó.

${POSTGRES_PASSWORD} ở trên được Compose mở rộng trên host từ file .env trước khi container tồn tại. File biến môi trường và secret trong Compose giải thích giá trị đó có thể được lưu an toàn ở đâu.

Chạy migration một lần bằng docker compose run

docker compose run tạo một container mới từ cùng định nghĩa service và thay thế command bằng nội dung bạn nhập sau tên service. Entrypoint của image vẫn chạy, nên container được chuẩn bị giống hệt container chạy lâu dài.

docker compose run --rm app python manage.py migrate
  • --rm xóa container khi command kết thúc. Nếu không dùng tùy chọn này, mỗi lần chạy sẽ để lại một container đã dừng, có thể xem trong docker compose ps -a.
  • Các port không được publish. Container run bỏ qua ports: của service, trừ khi bạn thêm --service-ports, nên không thể xung đột với service đang chạy.
  • Các dependency được khởi động trước. Mọi thành phần trong depends_on sẽ chạy trước command của bạn, còn --no-deps sẽ bỏ qua bước đó.
  • Container nhận một tên được tạo tự động như myproject-app-run-9f2c1a, nên không bao giờ trùng với container của service.

Để thay thế cả entrypoint, có một flag cho việc này:

docker compose run --rm --entrypoint /bin/sh app -c 'python manage.py migrate'

Danh sách argument thu được là /bin/sh -c 'python manage.py migrate', vì các từ sau tên service vẫn là command. docker compose exec là công cụ còn lại và hoạt động khác: nó chạy một process bên trong container đã chạy sẵn, đồng thời hoàn toàn bỏ qua cả entrypoint: và command:. Dùng run cho task cần container mới, và dùng exec để kiểm tra bên trong container đang chạy. Bảng tra cứu command của Compose trình bày các subcommand còn lại cạnh nhau.

Tại sao container của tôi thoát ngay lập tức?

Hãy bắt đầu bằng exit code vì nó giúp thu hẹp nguyên nhân nhanh chóng.

docker compose ps -a
docker compose logs app

Exit code 0 và không có output. Lệnh đã chạy và kết thúc. Nguyên nhân thường gặp nhất là một entrypoint: đã ghi đè và kéo theo CMD của image, khiến entrypoint chạy với danh sách đối số rỗng và không có gì để chuyển tiếp.

Lỗi kết thúc bằng permission denied. Script không có executable bit bên trong image, thường do bit này chưa từng được đặt cho file trong repository. Hãy đặt bit này tại thời điểm build bằng COPY --chmod=0755 entrypoint.sh /entrypoint.sh.

Lỗi kết thúc bằng no such file or directory đối với một file bạn nhìn thấy rõ trong image. Script có line ending kiểu Windows. Khi đó, dòng đầu tiên của script đọc thành #!/bin/sh cộng với một byte carriage return, nên kernel tìm một interpreter có chứa byte đó trong tên và không tìm thấy. Chạy dos2unix entrypoint.sh, sau đó thêm * text eol=lf vào .gitattributes để lỗi này không quay lại.

executable file not found in $PATH. Chương trình được chỉ định trong command: không nằm trong bất kỳ thư mục nào thuộc PATH của container. Image có thể không chứa chương trình đó, chương trình được cài ở bên ngoài PATH (hãy ghi full path thay thế), hoặc bạn đã ghi một shell built-in như cd ở nơi chỉ chấp nhận một chương trình thực.

Vào shell trong image khi entrypoint bị lỗi

Khi entrypoint dừng trước khi bạn kịp kiểm tra, hãy thay thế nó:

docker compose run --rm --entrypoint /bin/sh app

Nếu lệnh này lỗi với stat /bin/sh: no such file or directory, image không có /bin/sh. Các image dựa trên Distroless và scratch thường hoàn toàn không có shell. Bạn vẫn có thể đọc filesystem từ bên ngoài mà không khởi động entrypoint:

docker create --name probe myapp:1.4
docker export probe | tar -tv | head -40
docker rm probe

Khi cần giữ container chạy để có thể attach nhiều lần, hãy chạy nó bằng một process không bao giờ thoát. Đặt cấu hình này trong một file override không commit:

services:
  app:
    entrypoint: ["tail", "-f", "/dev/null"]
    command: []

command: [] không bắt buộc, vì đặt entrypoint: đã xóa CMD của image. Tuy vậy, ghi rõ nó giúp người đọc file sau này hiểu được chủ đích cấu hình. Khởi động container rồi vào shell:

docker compose -f compose.yaml -f compose.debug.yaml up -d app
docker compose exec app /bin/sh

Bây giờ hãy chạy entrypoint thật bằng tay và theo dõi điểm nó dừng. Như vậy, thông báo lỗi sẽ xuất hiện trên terminal thay vì trong một container đã dừng từ nửa giây trước. Nếu bạn vẫn đang dựng stack đầu tiên, stack Compose đầu tiên trên VPS giải thích cấu trúc file mà toàn bộ phần trên giả định.

FAQ

Vì sao container của tôi thoát ngay sau khi chạy docker compose up?

Kiểm tra docker compose ps -a để biết exit code. Exit 0 và không có output thường có nghĩa là bạn đã đặt entrypoint: cho service. Việc này cũng đã xóa CMD của image, khiến entrypoint chạy với danh sách argument rỗng rồi kết thúc. Thêm lại các argument bằng command:. Lỗi kết thúc bằng permission denied có nghĩa là entrypoint script chưa có quyền thực thi. Lỗi kết thúc bằng no such file or directory đối với một file đang tồn tại có nghĩa là script dùng line ending của Windows, nên dòng shebang của nó chỉ đến một interpreter không tồn tại.

Đặt entrypoint trong Compose có xóa CMD của image không?

Có. Nếu entrypoint khác null, Compose sẽ bỏ qua command mặc định mà image khai báo. Đây là hành vi được documented và phù hợp với docker run --entrypoint. Lý do là CMD của image được viết dưới dạng các argument cho ENTRYPOINT của image đó. Vì vậy, khi thay entrypoint, các argument cũ không còn thuộc về thành phần nào nữa. Đặt command: trong cùng service nếu entrypoint mới vẫn cần argument.

Chuỗi trong Compose command có được chạy qua shell không?

Không. Khác với CMD trong Dockerfile, chuỗi trong command: của Compose được tách thành các argument và chạy trực tiếp, không có wrapper /bin/sh -c. Vì vậy, Compose không khởi động shell bên trong container để tự mở rộng $VARIABLE cho bạn. Khi cần shell, hãy tự gọi shell, như trong command: /bin/sh -c 'echo "hello $$HOSTNAME"'. $$ được dùng để escape dấu dollar, để Compose truyền nó vào container thay vì mở rộng nó trên host.

Vì sao docker compose down mất 10 giây đối với một container?

Compose gửi stop signal đến PID 1 (SIGTERM, trừ khi image hoặc service đặt giá trị khác), chờ tối đa stop_grace_period (mặc định là 10 giây), rồi gửi SIGKILL nếu container vẫn đang chạy. Kernel không áp dụng hành động mặc định của signal cho PID 1. Vì vậy, một chương trình không có SIGTERM handler sẽ bỏ qua signal và luôn chờ hết khoảng thời gian này. Dùng docker compose exec -T app cat /proc/1/cmdline | tr '\0' ' ' để xác định PID 1 thực sự là gì. Nếu đó là shell, hãy chuyển image sang exec form hoặc thêm exec bên trong chuỗi shell. Nếu process tạo các child process nhưng không bao giờ reap chúng, hãy đặt init: true cho service.

Bài viết này có hữu ích không?