Trung bình DevOps

Healthcheck và depends_on trong Docker Compose: khởi động Laravel, MySQL, Redis cho đúng thứ tự

depends_on dạng ngắn chưa bao giờ chờ MySQL. Xài healthcheck với service_healthy và service_completed_successfully để boot Laravel, MySQL, Redis ổn định.

22 Th11, 2026 11 phút Cập nhật 23 Th10, 2026 5 Khối code
Sơ đồ
graph LR A[mysql healthy] --> C[migrate chạy] C -->|exit code 0| D[app khởi động] B[redis healthy] --> D B --> E[queue khởi động] C -->|exit code 0| E D --> F[app healthy] F --> G[compose up wait trả về]

Một bạn dev mới clone repo, chạy docker compose up, và container app thoát ra với SQLSTATE[HY000] [2002] Connection refused. Chạy lại thì chạy được. Trên CI cũng fail y vậy, khoảng mười lần thì một. Ai đó thêm sleep 15 vô entrypoint, lỗi chập chờn bớt đi, và từ đó mỗi lần khởi động local chậm thêm 15 giây, kể cả trên máy mà MySQL sẵn sàng chỉ sau bốn giây.

Gốc rễ là hiểu sai depends_on. Ở dạng ngắn, nó chỉ sắp thứ tự tạo container: Compose chạy MySQL, rồi chạy app, mà không chờ MySQL nhận connection. Lần boot đầu, image MySQL khởi tạo thư mục data và chạy init script, có thể mất từ 20 tới 60 giây. Lúc đó app đã chạy câu query đầu tiên từ lâu rồi.

Vì sao script wait-for chưa bao giờ đủ

Hồi Compose chưa hỗ trợ điều kiện health, cách sửa phổ biến là một vòng lặp trong entrypoint:

#!/bin/sh
# entrypoint.sh: the "wait-for" approach
until nc -z mysql 3306; do
  echo "waiting for mysql..."
  sleep 1
done
php artisan migrate --force
exec php-fpm

Nó chạy ổn hơn sleep, nhưng kiểm tra sai thứ. Port TCP mở chỉ có nghĩa là có process đang listen, chứ không có nghĩa database đã sẵn sàng: schema có thể chưa có, user trong MYSQL_USER có thể chưa được tạo, Redis có thể vẫn đang load dataset. Vòng lặp không có timeout, nên chỉ cần sai tên host là container treo luôn với dòng "waiting" rất thân thiện. Và logic này bị copy vô mọi image cần nó, nhiều khi cài nc chỉ để xài đúng chỗ này.

Healthcheck dời kiến thức đó về đúng chỗ: chính dependency mô tả cách biết nó đã sẵn sàng, và Compose chờ tới trạng thái đó rồi mới chạy những service phụ thuộc vô nó.

Healthcheck cộng với điều kiện của depends_on

Đây là một stack Laravel có MySQL, Redis, một service migrate chạy một lần, web app và queue worker:

services:
  mysql:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: shop
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    healthcheck:
      # -h 127.0.0.1 forces TCP: the temporary init server has networking disabled
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -p$$MYSQL_ROOT_PASSWORD --silent"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s
      start_interval: 2s

  redis:
    image: redis:7.4-alpine
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s

  migrate:
    image: shop-app:latest
    command: ["php", "artisan", "migrate", "--force"]
    restart: "no"
    depends_on:
      mysql: { condition: service_healthy }

  app:
    image: shop-app:latest
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8080/up"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 20s
    depends_on:
      mysql: { condition: service_healthy, restart: true }
      redis: { condition: service_healthy }
      migrate: { condition: service_completed_successfully }

  queue:
    image: shop-app:latest
    command: ["php", "artisan", "queue:work", "--tries=3", "--max-time=3600"]
    depends_on:
      redis: { condition: service_healthy }
      migrate: { condition: service_completed_successfully }

Dạng dài của depends_on nhận một condition:

  • service_started: mặc định. Chỉ chờ container khởi động.
  • service_healthy: chờ tới khi healthcheck của dependency báo healthy. Nếu nó thành unhealthy hoặc không bao giờ tới được đó, up fail chứ không chạy service phụ thuộc.
  • service_completed_successfully: chờ tới khi dependency thoát với exit code 0. Hợp hoàn hảo cho migration, seeder và build asset.

Các field của healthcheck điều khiển thời gian. interval là khoảng cách giữa hai lần check, timeout là thời gian tối đa của một lần check, retries là số lần fail liên tiếp để bị đánh dấu unhealthy. start_period là khoảng ân hạn mà fail không bị tính, còn start_interval (từ Docker Engine 25) cho phép check dày hơn trong khoảng đó, nên boot nhanh thì phát hiện trong hai giây chứ không phải mười.

Đồ thị khởi động

graph LR A[mysql healthy] --> C[migrate chạy] C -->|exit code 0| D[app khởi động] B[redis healthy] --> D B --> E[queue khởi động] C -->|exit code 0| E D --> F[app healthy] F --> G[compose up wait trả về]

Migration chạy đúng một lần, sau khi MySQL thật sự sẵn sàng, và trước mọi process có thể query một bảng chưa tồn tại. App và worker khởi động song song khi điều kiện riêng của từng cái được thỏa. Không sleep, không vòng lặp, và docker compose up --wait chỉ trả về khi cả đồ thị xanh hết.

Mấy chi tiết giúp check MySQL trung thực

Có hai cái bẫy trong healthcheck của MySQL mà gần như ai cũng dính.

mysqladmin ping vẫn thành công khi bị access denied. Exit code của nó là 0 miễn server đang chạy, kể cả khi xác thực thất bại. Với một check kiểu liveness thì vậy là đúng ý, nhưng đừng hiểu lầm nó là "user của app login được". Nếu cần bảo đảm điều đó, chạy một câu query thật bằng credential của app: mysql -h 127.0.0.1 -u$$MYSQL_USER -p$$MYSQL_PASSWORD -e 'SELECT 1' $$MYSQL_DATABASE.

Server lúc init không phải server thật. Lần chạy đầu, entrypoint bật một server tạm với networking bị tắt để chạy init script, rồi restart nó. Healthcheck kết nối qua socket local có thể báo healthy với server tạm đó, và app kết nối vô đúng lúc nó đang tắt. Ép xài TCP bằng -h 127.0.0.1 làm check fail cho tới khi server thật đang listen.

Để ý luôn cái $$. Compose interpolate $VAR từ shell hoặc file .env lúc parse file. $$ escape nó, để biến được expand bên trong container, nơi MYSQL_ROOT_PASSWORD thật sự được set.

Vận hành stack

Phần lớn giá trị lộ ra khi mình viết script xoay quanh nó:

# Start everything and block until every service is running or healthy (non-zero exit otherwise)
docker compose up -d --wait --wait-timeout 120

docker compose ps                     # STATUS column shows (healthy) / (health: starting)
docker inspect --format '{{json .State.Health.Log}}' shop-mysql-1 | jq '.[-1]'
docker compose logs migrate           # a one-shot service that failed shows why here

--wait biến câu hỏi "stack lên chưa?" thành một exit code, đúng thứ CI cần. Khi có gì đó bị treo, health log trong docker inspect cho thấy chính xác output của mấy lần check gần nhất, thường là đủ để biết mình đang probe sai host, sai port hay một lệnh không có trong image.

Kiểm thử stack trên CI

Thứ tự khởi động là hạ tầng, nhưng test được như code. Gắn group cho vài test Pest chỉ có ý nghĩa bên trong môi trường compose:

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Redis;
use Illuminate\Support\Facades\Schema;

it('reaches mysql through the compose network', function () {
    expect(DB::select('select 1 as ok')[0]->ok)->toEqual(1);
})->group('compose');

it('ran the migrations before the app started', function () {
    expect(Schema::hasTable('migrations'))->toBeTrue()
        ->and(DB::table('migrations')->count())->toBeGreaterThan(0);
})->group('compose');

it('reads back what it writes to redis', function () {
    Redis::set('compose:smoke', 'ok');

    expect(Redis::get('compose:smoke'))->toBe('ok');
})->group('compose');

Rồi chạy chúng trên một stack mới khởi động trong CI:

docker compose up -d --wait --wait-timeout 180 || { docker compose ps; docker compose logs --tail=50; exit 1; }
docker compose exec -T app php artisan test --group=compose
docker compose down -v

Nhánh || { ...; exit 1; } in ra trạng thái và log gần nhất của mọi service trước khi fail, nên build đỏ là biết ngay healthcheck nào không bao giờ pass. Bắt đầu từ volume sạch sau down -v mỗi lần cũng giúp chạy qua đường boot lần đầu chậm chạp mà máy local hiếm khi gặp.

Những lỗi hay gặp

Lệnh healthcheck không có trong image. curl không có sẵn trong nhiều image slim và Alpine, và thiếu binary thì nhìn y như container unhealthy. Kiểm tra bằng docker compose exec app which curl, hoặc xài wget -qO- hay một script PHP nhỏ.

Tưởng depends_on lo luôn lỗi lúc runtime. Điều kiện chỉ được xét khi Compose khởi động service. Nếu một tiếng sau MySQL crash, app không bị dừng hay restart. restart: true chỉ restart service phụ thuộc khi chính Compose restart dependency, ví dụ docker compose restart mysql. App vẫn cần retry và timeout connection hợp lý.

Coi service chạy một lần như service chạy lâu dài. Service migrate mà để restart: unless-stopped sẽ lặp mãi, và service_completed_successfully không bao giờ thấy lần thoát cuối cùng. Service chạy một lần cần restart: "no".

Interval quá dày. Healthcheck mỗi giây trên mọi service đốt CPU laptop và làm ngập health log. Xài start_interval ngắn để phát hiện nhanh lúc boot và interval thoải mái hơn về sau.

Tưởng healthcheck của Compose sẽ restart container. Docker Engine thuần chỉ đánh dấu container unhealthy chứ không restart. Muốn restart theo health thì cần orchestrator hoặc một watchdog riêng.

Khi nào nên xài điều kiện health, khi nào không

Xài service_healthy cho mọi dependency có state mà app cần lúc boot: database, cache, search engine, message broker. Xài service_completed_successfully cho mấy bước setup phải xong trước: migration, seeder, tạo bucket trong MinIO, build frontend.

Giữ service_started (hoặc bỏ luôn depends_on) cho mấy service chịu được việc dependency tới trễ, như reverse proxy tự retry upstream hay worker có vòng lặp reconnect riêng. Ràng buộc đồ thị quá chặt sẽ biến một service tùy chọn bị thiếu thành cả stack không chịu khởi động.

Vòng lặp wait-for vẫn có chỗ đứng khi dependency nằm ngoài Compose, ví dụ database managed trên CI hay init container trong Kubernetes, nơi không có điều kiện của Compose. Kể cả vậy, cho vòng lặp một timeout và kiểm tra sẵn sàng bằng một câu query thật, chứ đừng chỉ coi port có mở không. Và ở môi trường nào cũng vậy, giữ logic retry trong chính app: healthcheck làm việc khởi động trở nên chắc chắn, chứ không làm dependency bất tử.

Thử thách tương tác

Thử thách

Luyện tập ngay điều vừa học. Viết lời giải, mở gợi ý nếu bí.

Đề bài

Mô phỏng quy tắc khởi động của Docker Compose. canStart(deps, states) bên JavaScript / can_start(deps, states) bên Python trả true khi mọi điều kiện dependency đều thỏa. deps map tên service với một trong 'service_started', 'service_healthy' hoặc 'service_completed_successfully'; điều kiện khác thì throw Error (JS) hoặc raise ValueError (Python). states map tên service với object/dict có status ('created', 'running' hoặc 'exited'), health ('healthy', 'unhealthy', 'starting' hoặc null/None) và exitCode (JS) / exit_code (Python). Dependency không có trong states thì không thỏa. service_started cần status 'running'; service_healthy cần status 'running' và health 'healthy'; service_completed_successfully cần status 'exited' và exit code 0. deps rỗng thì xem như thỏa. startupOrder(services) / startup_order(services) nhận một map từ tên service tới danh sách tên dependency và trả về thứ tự khởi động: service nào cũng đứng sau mọi dependency của nó, và khi nhiều service cùng sẵn sàng thì lấy cái nhỏ nhất theo thứ tự alphabet trước. Throw Error (JS) / raise ValueError (Python) khi một dependency không phải service đã biết (message bên JS phải chứa 'unknown service') hoặc khi có vòng lặp phụ thuộc (message bên JS phải chứa 'cycle').

Code khởi tạo

python
CONDITIONS = {"service_started", "service_healthy", "service_completed_successfully"}


def can_start(deps: dict[str, str], states: dict[str, dict]) -> bool:
    """deps:   {"mysql": "service_healthy", "migrate": "service_completed_successfully"}
    states: {"mysql": {"status": "running", "health": "healthy", "exit_code": None}, ...}
    """
    # TODO: unknown condition -> ValueError
    # TODO: a dependency missing from states -> not satisfied
    # TODO: service_started -> status == "running"
    # TODO: service_healthy -> status == "running" and health == "healthy"
    # TODO: service_completed_successfully -> status == "exited" and exit_code == 0
    raise NotImplementedError


def startup_order(services: dict[str, list[str]]) -> list[str]:
    # TODO: topological order; when several services are ready, take them alphabetically
    # TODO: unknown dependency or a cycle -> ValueError
    raise NotImplementedError
javascript
const CONDITIONS = ['service_started', 'service_healthy', 'service_completed_successfully'];

/**
 * deps:   { mysql: 'service_healthy', migrate: 'service_completed_successfully' }
 * states: { mysql: { status: 'running', health: 'healthy', exitCode: null }, ... }
 */
function canStart(deps, states) {
  // TODO: unknown condition -> throw Error
  // TODO: a dependency missing from states -> not satisfied
  // TODO: service_started -> status === 'running'
  // TODO: service_healthy -> status === 'running' && health === 'healthy'
  // TODO: service_completed_successfully -> status === 'exited' && exitCode === 0
  throw new Error('TODO');
}

/** services: { app: ['mysql', 'redis'], mysql: [], redis: [] } */
function startupOrder(services) {
  // TODO: topological order; when several services are ready, take them alphabetically
  // TODO: unknown dependency or a cycle -> throw Error
  throw new Error('TODO');
}

Lời giải của bạn

Gợi ý

Đã mở hết gợi ý
Gợi ý 1

Validate mọi điều kiện trước, rồi mới so từng dependency với state của nó

Gợi ý 2

Để tính thứ tự, xài thuật toán Kahn: lặp lại việc lấy service không còn dependency nào

Gợi ý 3

Sắp xếp các service sẵn sàng và mỗi bước chỉ lấy cái đầu tiên, rồi gỡ nó khỏi tập dependency của mọi service khác

Gợi ý 4

Nếu còn service mà không cái nào sẵn sàng thì đó là vòng lặp phụ thuộc

Lời giải · python
CONDITIONS = {"service_started", "service_healthy", "service_completed_successfully"}


def can_start(deps: dict[str, str], states: dict[str, dict]) -> bool:
    """deps:   {"mysql": "service_healthy", "migrate": "service_completed_successfully"}
    states: {"mysql": {"status": "running", "health": "healthy", "exit_code": None}, ...}
    """
    for name, condition in deps.items():
        if condition not in CONDITIONS:
            raise ValueError(f"Unknown condition: {condition}")

    for name, condition in deps.items():
        state = states.get(name)
        if state is None:
            return False
        status = state.get("status")
        if condition == "service_started" and status != "running":
            return False
        if condition == "service_healthy" and not (status == "running" and state.get("health") == "healthy"):
            return False
        if condition == "service_completed_successfully" and not (status == "exited" and state.get("exit_code") == 0):
            return False
    return True


def startup_order(services: dict[str, list[str]]) -> list[str]:
    for name, deps in services.items():
        for dep in deps:
            if dep not in services:
                raise ValueError(f"{name} depends on unknown service {dep}")

    remaining = {name: set(deps) for name, deps in services.items()}
    order: list[str] = []
    while remaining:
        ready = sorted(name for name, deps in remaining.items() if not deps)
        if not ready:
            raise ValueError("Dependency cycle between: " + ", ".join(sorted(remaining)))
        current = ready[0]
        order.append(current)
        del remaining[current]
        for deps in remaining.values():
            deps.discard(current)
    return order
Lời giải · javascript
const CONDITIONS = ['service_started', 'service_healthy', 'service_completed_successfully'];

/**
 * deps:   { mysql: 'service_healthy', migrate: 'service_completed_successfully' }
 * states: { mysql: { status: 'running', health: 'healthy', exitCode: null }, ... }
 */
function canStart(deps, states) {
  for (const condition of Object.values(deps)) {
    if (!CONDITIONS.includes(condition)) throw new Error(`Unknown condition: ${condition}`);
  }

  return Object.entries(deps).every(([name, condition]) => {
    const s = states[name];
    if (!s) return false;
    if (condition === 'service_started') return s.status === 'running';
    if (condition === 'service_healthy') return s.status === 'running' && s.health === 'healthy';
    return s.status === 'exited' && s.exitCode === 0;
  });
}

/** services: { app: ['mysql', 'redis'], mysql: [], redis: [] } */
function startupOrder(services) {
  for (const [name, deps] of Object.entries(services)) {
    for (const dep of deps) {
      if (!(dep in services)) throw new Error(`${name} depends on unknown service ${dep}`);
    }
  }

  const remaining = new Map(Object.entries(services).map(([n, d]) => [n, new Set(d)]));
  const order = [];
  while (remaining.size > 0) {
    const ready = [...remaining].filter(([, d]) => d.size === 0).map(([n]) => n).sort();
    if (ready.length === 0) {
      throw new Error(`Dependency cycle between: ${[...remaining.keys()].sort().join(', ')}`);
    }
    const current = ready[0];
    order.push(current);
    remaining.delete(current);
    for (const d of remaining.values()) d.delete(current);
  }
  return order;
}

Cùng chủ đề DevOps