LinuxUnity LinuxUnity

Bài viết / Docker

Docker Compose: services, depends_on, healthcheck và network

Dựng stack Node.js và PostgreSQL tối giản bằng Docker Compose, hiểu service discovery, named volume, depends_on condition và dùng docker compose config để kiểm tra cấu hình trước khi chạy.

28/08/2026 17 phút đọc 8 lượt xem

PP Peter Parker

Trong bài này

docker run là công cụ tuyệt vời để làm quen với việc khởi chạy một container đơn lẻ. Nhưng chỉ cần ứng dụng lớn thêm một chút — có App, có Database, có hàng tá biến môi trường cần truyền vào, có volume cần mount, có network cần cấu hình, và có thứ tự khởi động không thể tuỳ tiện — thì dòng lệnh terminal sẽ nhanh chóng phình to thành một chuỗi tham số dài dằng dặc mà chính bạn cũng ngại đọc lại sau một tuần.

Đó chính là lúc Docker Compose bước vào cuộc chơi.

File Compose không thay thế Dockerfile, mà bổ sung cho nó. Nếu Dockerfile trả lời câu hỏi "đóng gói (build) image như thế nào", thì Docker Compose (YAML) trả lời câu hỏi "các container vận hành (run) cùng nhau ra sao": dùng image nào, gắn ổ đĩa (volume) ở đâu, giao tiếp qua network nào, ai khởi động trước — ai khởi động sau.

Trước khi bước vào ví dụ thực tế, hãy điểm qua những khái niệm nền tảng làm nên "xương sống" của Compose.

Ba khái niệm cốt lõi trong Docker Compose

Mở bất kỳ file compose.yaml (hay docker-compose.yml) nào ra, bạn sẽ luôn thấy ba thành phần cấp cao (top-level elements) sau:

Services (Dịch vụ) — đơn vị runtime trung tâm của Compose. Một service mô tả cách một (hoặc nhiều) container được chạy. Chẳng hạn: service frontend chạy React, service backend chạy Node.js, service database chạy PostgreSQL.

Networks (Mạng lưới) — về bản chất, container sinh ra đã bị cô lập với nhau. Networks định nghĩa luật chơi cho việc giao tiếp giữa chúng. Compose tự động tạo một network nội bộ riêng cho project, nhờ đó các service có thể gọi nhau bằng tên (qua DNS nội bộ) thay vì phải nhớ địa chỉ IP tĩnh.

Volumes (Không gian lưu trữ) — khi một container bị xoá, mọi dữ liệu bên trong nó cũng biến mất theo. Volumes cho phép dữ liệu (như các bản ghi database) tồn tại độc lập với vòng đời của container: dù bạn có dừng, xoá, hay tạo lại container bao nhiêu lần, dữ liệu gắn vào volume vẫn nguyên vẹn.

Bộ khung của một file Compose

Trước khi lao vào lab, hãy nhìn tổng thể "bộ khung" mà mọi file Compose đều tuân theo:

yaml
services:
  service-name:
    # Định nghĩa service

volumes:
  volume-name:
    # Cấu hình volume

networks:
  network-name:
    # Cấu hình network

Trong ba khối này, chỉ services là bắt buộc — volumes và networks chỉ xuất hiện khi bạn cần khai báo tường minh (ví dụ named volume, hoặc network cô lập ngoài network mặc định). Đây cũng là lý do vì sao rất nhiều file Compose "tối giản" ngoài thực tế chỉ có mỗi services: mà vẫn chạy tốt.

A.imagehaybuild: lấy sẵn hay tự đóng gói?

Mỗi service cần một nguồn image, và có hai lựa chọn:

yaml
services:
  db:
    image: postgres:16-alpine   # dùng image có sẵn từ registry

  api:
    build: ./api                # tự build từ Dockerfile trong thư mục ./api

Với những thành phần hạ tầng chuẩn (database, cache, message queue...), gần như luôn nên dùng image có sẵn — không có lý do gì để tự build lại PostgreSQL. build chỉ dành cho code của chính bạn. Khi cần kiểm soát sâu hơn (build args, Dockerfile khác tên mặc định, build context riêng), build có thể mở rộng thành object:

yaml
services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile.prod
      args:
        - NODE_ENV=production

B.ports: publish ra ngoài như thế nào

Ở phần Lab phía sau, bạn sẽ thấy service postgres không có ports: — đó là lựa chọn có chủ đích. Nhưng khi một service thực sự cần publish (như App HTTP), cú pháp có vài biến thể đáng nhớ:

text
services:
  web:
    ports:
      - "8080:80"              # host:container — cố định cổng host
      - "3000"                 # chỉ định cổng container, Docker tự chọn cổng host ngẫu nhiên
      - "127.0.0.1:8080:80"    # chỉ bind vào localhost của host, không lộ ra mạng ngoài

Biến thể thứ ba (127.0.0.1:...) đáng chú ý nhất về mặt bảo mật: nó cho phép bạn debug từ chính máy host mà không vô tình mở port ra toàn bộ mạng — một lựa chọn trung gian giữa "publish hoàn toàn" và "không publish gì" như DB trong lab.

C. Environment variables: inline hayenv_file

text
services:
  api:
    environment:
      - NODE_ENV=production
      - DB_HOST=db

Cách viết inline phù hợp với vài biến ít thay đổi. Nhưng khi số lượng biến tăng lên, hoặc bạn cần tách biệt giá trị theo môi trường (dev/staging/prod) mà không sửa trực tiếp file YAML, env_file là lựa chọn sạch hơn:

text
services:
  api:
    env_file:
      - .env
      - .env.local

Lưu ý: env_file chỉ nên chứa cấu hình không nhạy cảm, hoặc secret ở dạng đã được quản lý qua .gitignore nghiêm ngặt — nguyên tắc "không đưa secret vào Git" ở phần Lab áp dụng y hệt cho .env.

D. Volumes: named volume và bind mount là hai thứ khác nhau

Đây là điểm rất dễ gây nhầm lẫn với người mới:

text
services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data                     # named volume
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql     # bind mount

volumes:
  pgdata:   # named volume phải được khai báo ở top-level

Named volume (pgdata:...) do Docker quản lý hoàn toàn — bạn không cần (và không nên) quan tâm dữ liệu vật lý nằm ở đâu trên host. Đây là lựa chọn đúng cho dữ liệu cần bền vững như database, đúng như phân tích ở phần D của mục Lab bên dưới.

Bind mount (./init.sql:...) lại ánh xạ trực tiếp một file/thư mục cụ thể từ host vào container. Nó hữu ích để inject file cấu hình, script khởi tạo, hoặc — trong môi trường dev — đồng bộ code trực tiếp từ host vào container để có hot-reload. Nhưng bind mount không phù hợp cho dữ liệu sống còn, vì nó gắn chặt với đường dẫn vật lý trên host, không portable.

Ghi nhớ ngắn gọn: named volume dùng cho state cần Docker quản lý, bind mount dùng cho file cần bạn quản lý.

Lab App + Database

Để thấy rõ ba khái niệm trên phối hợp với nhau như thế nào, chúng ta sẽ dựng một stack nhỏ: một Node.js HTTP App gọi tới PostgreSQL. Lab này đủ gọn để chạy trên máy local, nhưng vẫn được thiết kế có healthcheck, named volume và private database network — đúng tinh thần của một hệ thống production thu nhỏ.

Cấu trúc lab:

text
compose-101/
├── compose.yaml
├── Dockerfile
├── package.json
├── package-lock.json
└── server.js

package.json:

text
{
  "name": "compose-101",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "pg": "8.16.0"
  }
}

server.js:

javascript
import http from "node:http";
import pg from "pg";

const { Pool } = pg;
const port = Number(process.env.PORT || 3000);
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

async function databaseReady() {
  await pool.query("select 1");
}

const server = http.createServer(async (request, response) => {
  if (request.url === "/livez") {
    response.writeHead(200).end("ok");
    return;
  }

  if (request.url === "/readyz") {
    try {
      await databaseReady();
      response.writeHead(200).end("ready");
    } catch {
      response.writeHead(503).end("database unavailable");
    }
    return;
  }

  response.writeHead(200, { "content-type": "application/json" });
  response.end(JSON.stringify({ ok: true }));
});

server.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`));

Dockerfile:

text
FROM node:24-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./
USER node
EXPOSE 3000
CMD ["node", "server.js"]

Compose file tối giản nhưng có dependency đúng

compose.yaml:

text
services:
  app:
    build:
      context: .
    environment:
      NODE_ENV: production
      PORT: "3000"
      DATABASE_URL: postgres://demo:change-me-locally@postgres:5432/demo
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "127.0.0.1:3000:3000"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/livez').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 15s
      timeout: 3s
      retries: 5
      start_period: 10s
    networks:
      - internal

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: demo
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: change-me-locally
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 10s
      timeout: 3s
      retries: 10
      start_period: 10s
    networks:
      - internal

volumes:
  postgres_data:

networks:
  internal:

Password trong lab chỉ tồn tại để ví dụ chạy được ngay. Không copy pattern này sang production .env hoặc Git repository. Production secret cần được inject từ secret mechanism của runtime (Vault, secret manager của cloud provider, hoặc Docker/Kubernetes secret).

Phân tích cấu hình trong Lab

Nhìn lướt qua, file YAML này có vẻ rất đơn giản. Nhưng phía sau từng dòng cấu hình là một quyết định mang tính kiến trúc.

A. Network & Service Discovery

compose-network

Compose đặt tên network, volume và container dựa theo tên project (mặc định là tên thư mục chứa file compose).

Cả app và postgres cùng nằm trong một network nội bộ. Compose tự động sinh bản ghi DNS theo tên service, nên thay vì dò IP, app có thể gọi thẳng tới database qua URL dạng postgres://user:pass@postgres:5432/db.

Nguyên tắc vàng: không dùng localhost trong chuỗi kết nối của container App. Bên trong container App, localhost chính là bản thân nó — không phải là database.

Để ý rằng service postgres hoàn toàn không có mục ports:. Điều đó có nghĩa máy host (laptop/VPS của bạn) không thể kết nối tới cổng 5432 từ bên ngoài. Đây là một ranh giới bảo mật rất đẹp: database không cần "phơi" ra ngoài, chỉ những service cùng network (như App) mới gọi được tới nó.

B. Lifecycle:depends_onkhông đơn thuần là thứ tự trên giấy

Nếu chỉ viết:

yaml
depends_on:
  - postgres

thì Compose chỉ đảm bảo container Postgres được lệnh khởi động trước App — chứ không đảm bảo "container đang chạy" đồng nghĩa với "database đã sẵn sàng nhận query". Postgres vẫn cần vài giây để khởi tạo data directory trước khi thực sự phục vụ.

Vì vậy chúng ta cần condition: service_healthy. Compose sẽ chờ đến khi healthcheck của Postgres báo pass (tức là đã truy vấn được thật sự) rồi mới cho App khởi động.

Sự thật cần nhìn thẳng: ngay cả service_healthy cũng không thay thế được logic retry ở tầng ứng dụng. Mạng chập chờn, DB restart giữa chừng — những tình huống này vẫn có thể xảy ra bất cứ lúc nào. depends_on chỉ giải quyết được thứ tự lúc startup; còn việc xử lý dependency failure lúc runtime vẫn là trách nhiệm của chính ứng dụng.

C. Healthcheck: "Sống" khác với "Sẵn sàng"

liveness-readiness

Lab của chúng ta có hai endpoint để minh hoạ sự khác biệt này:

  • /livez: xác nhận Node process đang sống và còn tiếp nhận HTTP request (đây là endpoint Docker healthcheck đang sử dụng).
  • /readyz: xác nhận Node process thực sự truy vấn được database tại đúng thời điểm kiểm tra.

Không có endpoint nào "đúng" cho mọi tình huống. Nếu bạn để readiness check bắt buộc phải kèm theo DB healthy, thì khi DB tạm thời gián đoạn, App của bạn sẽ bị Load Balancer loại khỏi nhóm phục vụ ngay lập tức — dù lúc đó App vẫn hoàn toàn có thể trả về một trang "Bảo trì" hợp lệ. Chọn endpoint nào cho readiness check là một quyết định phụ thuộc vào yêu cầu vận hành thực tế của sản phẩm, không có công thức chung.

D. Bảo toàn dữ liệu với Named Volume

Dữ liệu của Postgres được lưu vào một Named Volume. Nhờ vậy, dù bạn cập nhật image hay thay đổi cấu hình khiến container bị tạo lại, dữ liệu vẫn được giữ nguyên.

yaml
volumes:
  - postgres_data:/var/lib/postgresql/data
text
docker compose config --volumes
docker volume ls

Lệnh nguy hiểm cần tránh: đừng bao giờ chạy docker compose down -v nếu bạn muốn giữ lại dữ liệu. Cờ -v sẽ xoá sạch mọi Named Volume thuộc project. Trong lab, việc này giúp "dọn dẹp nhanh gọn" — nhưng ở môi trường có dữ liệu thật, đó là một hành động phá huỷ không thể vãn hồi.

docker compose config

Trước khi chạy up, hãy tập thói quen chạy lệnh config trước. File Compose thường không đứng một mình — nó có thể bị chi phối bởi biến môi trường (.env), file override, v.v. Chỉ đọc YAML gốc chưa chắc bạn đã thấy đúng cấu hình mà Docker thực sự sẽ áp dụng.

text
docker compose config # full configuration render
docker compose config --services # list services
docker compose config --volumes # list volumes
docker compose config --quiet # syntax validation - quiet mode

Khởi động lab:

text
docker compose up --build -d
docker compose ps
docker compose logs --tail=100 app postgres
curl -i http://127.0.0.1:3000/livez
curl -i http://127.0.0.1:3000/readyz

Dọn lab nhưng giữ data:

text
docker compose down

Dọn lab và xóa database data, chỉ dùng khi cố ý reset:

text
docker compose down -v

Command cheatsheet

Ngoài up, down và config đã nhắc ở trên, đây là bộ lệnh Compose bạn sẽ gõ gần như mỗi ngày khi làm việc với lab hay hệ thống thật.

Khởi động & build

bash
docker compose up            # chạy foreground, thấy log trực tiếp, Ctrl+C để dừng
docker compose up -d         # chạy nền (detached)
docker compose up --build    # build lại image trước khi khởi động

Dừng & dọn dẹp

text
docker compose down            # dừng và xoá container, giữ nguyên volume
docker compose down -v         # xoá luôn named volume — cẩn trọng như đã nói ở phần D
docker compose down --rmi all  # xoá luôn cả image đã build/pull

Quan sát hệ thống

bash
docker compose ps              # xem trạng thái từng service
docker compose logs            # xem log toàn bộ services
docker compose logs -f api     # theo dõi log real-time của riêng service api
docker compose logs --tail 100 # chỉ xem 100 dòng log gần nhất

Vào bên trong container

bash
docker compose exec api bash
docker compose exec db psql -U taskuser

Chạy lệnh một lần

text
docker compose run api npm test        # tạo container mới chỉ để chạy lệnh này
docker compose run --rm api npm test   # tương tự, nhưng tự xoá container sau khi xong

exec và run dễ bị dùng lẫn lộn: exec chạy lệnh trong một container đang sống, còn run tạo một container mới chỉ để thực thi lệnh rồi thôi — dùng đúng ngữ cảnh sẽ tránh được tình trạng container test rác tồn đọng theo thời gian.

Scale service

bash
docker compose up -d --scale worker=3    # chạy 3 instance của service worker

Đây là cách nhanh nhất để mô phỏng việc scale ngang ngay trên local, dù tất nhiên không thay thế được orchestration thật sự (Kubernetes, Swarm) ở production.

restartpolicy không phải HA

Compose hỗ trợ restart policy để Docker tự khởi động lại container khi process crash hoặc daemon restart:

text
services:
  api:
    restart: unless-stopped

Có 4 giá trị hợp lệ, mỗi giá trị mang một "triết lý" khác nhau:

  • no (mặc định): không tự restart trong bất kỳ trường hợp nào. Phù hợp cho các one-off job hoặc script chạy một lần.
  • always: luôn restart, kể cả khi bạn chủ động dừng bằng docker stop rồi khởi động lại Docker daemon. Ít dùng vì có thể "hồi sinh" cả những container bạn cố tình tắt.
  • on-failure: chỉ restart khi container thoát với exit code khác 0 (tức là crash thật sự), không restart khi bạn chủ động dừng.
  • unless-stopped: restart trong hầu hết trường hợp — kể cả khi Docker daemon restart — trừ khi bạn chủ động docker stop container đó.

Trong lab và phần lớn service production, unless-stopped là lựa chọn cân bằng nhất.

Nhưng restart policy chỉ hoạt động ở một tầng rất hẹp: nó hữu ích trên một host đơn lẻ, không tạo ra multi-host availability, không replicate database, và không chống được sự cố hỏng ổ cứng của chính host đó.

Đừng dùng restart loop để che giấu lỗi cấu hình ứng dụng. Nếu process crash vì migration lỗi, secret sai, hay schema database không tương thích, restart policy chỉ tạo ra một vòng lặp log noise cho tới khi disk đầy hoặc có người can thiệp thủ công.

Những bẫy cần tránh

Khi đứng trước một file Compose dài 500 dòng ở môi trường production, bạn không cần thuộc lòng từng dòng YAML. Thay vào đó, hãy đi theo mạch câu hỏi kiến trúc sau:

  • Service nào mở port ra ngoài, service nào ẩn hoàn toàn bên trong?
  • Volume nào chứa dữ liệu sống còn (source of truth), volume nào chỉ đơn thuần là cache?
  • Ai đang chờ ai (healthcheck)?
  • Restart policy có đang che giấu một lỗi crash lặp đi lặp lại của ứng dụng hay không? (Lưu ý: các restart policy như unless-stopped không phải là High Availability — chúng không chống được sự cố hỏng ổ cứng hay thay thế cho việc replicate database.)

3 lỗi thường gặp:

  1. Tin tưởng tuyệt đối vàodepends_on: ứng dụng vẫn cần có timeout/retry logic riêng, thay vì phó mặc hoàn toàn cho Compose.
  2. Indocker compose configra public CI log: hành động này có thể vô tình làm lộ secret lấy từ .env.
  3. Publish port của database ra ngoài một cách bừa bãi: chỉ vì "app không kết nối được" mà nhiều người vội mở thẳng port DB ra public, thay vì kiểm tra lại tên service trong network nội bộ trước.

Một lưu ý thêm: giới hạn tài nguyên

File Compose trong lab (và phần lớn ví dụ học tập) thường không giới hạn CPU/memory cho từng service — container có thể ăn tài nguyên vô tội vạ nếu code có bug (leak, vòng lặp vô hạn...). Ở production, nên khai báo giới hạn tường minh:

text
services:
  api:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          memory: 256M

limits là trần tối đa container được phép dùng — vượt quá, container có thể bị OOM kill. reservations là mức tài nguyên tối thiểu được đảm bảo dành riêng cho service đó. Thiếu resource limits không gây lỗi ngay lập tức, nhưng là nguyên nhân phổ biến của những sự cố kiểu "một container ăn hết RAM làm sập cả node" — loại lỗi rất khó debug nếu không nhìn đúng chỗ ngay từ đầu.

Tổng kết

Docker Compose vượt xa vai trò của một công cụ gộp các lệnh docker run cho đỡ mỏi tay. Nó giúp document hoá toàn bộ topology của ứng dụng — từ network isolation, mount point, cho đến startup lifecycle — thành một bản thiết kế có thể đọc lại bất cứ lúc nào.

Nhưng Compose chỉ quản lý ở tầng infrastructure cục bộ. Để ứng dụng thực sự "production-ready", tư duy của người kỹ sư cần đi xa hơn nội dung file YAML. Ba nguyên tắc "mỏ neo" nên luôn mang theo:

  • Lifecycle Order không thay thế Application Resilience.
  • Default Secure với network nội bộ.
  • Cẩn trọng tuyệt đối với State (đặc biệt là cờ -v).

Khi đã nắm vững những lăng kính phân tích này — ai gọi ai, ai đợi ai, ai lưu cái gì, ai phơi ra ngoài — thì việc làm chủ Docker Compose không còn dừng ở việc đọc đúng cú pháp, mà trở thành hành trình thiết kế có chủ ý từng mắt xích của một hệ thống.