zeabur-startup-order

Zeabur の起動順序に関する問題

Zeabur CLI の実行には、必ず npx zeabur@latest を使用してください。 zeabur を直接実行したり、ほかのインストール方法を使用したりしないでください。npx が利用できない場合は、先に Node.js をインストールしてください。

症状

Connection refused :5432
connection to server at "X" failed
OperationalError: connection failed

原因

依存サービス（DB／Redis）の準備が整う前に、サービスが起動しています。dependencies で保証されるのはコンテナーの起動順序のみであり、サービスが接続を受け付けていることまでは保証されません。

修正方法（推奨）：依存サービスに healthCheck を設定する

データベース／Redis サービスに healthCheck を追加すると、ポートが接続を受け付ける状態になるまで Zeabur が待機してから、依存するサービスを起動します。アプリのコマンドを変更する必要はありません。

テンプレートの YAML を編集します（YAML のリファレンスには zeabur-template スキルを使用してください）。

- name: postgresql
  spec:
    ports:
      - id: database
        port: 5432
        type: TCP
    healthCheck:
      type: TCP
      port: database    # references the port ID above

- name: redis
  spec:
    ports:
      - id: database
        port: 6379
        type: TCP
    healthCheck:
      type: TCP
      port: database

修正方法（代替）：コマンドに待機ループを追加する

テンプレートを変更できない場合（zeabur-template スキルを使用してください）、アプリのコマンドに待機処理を追加します（コマンドは必ず source の中に記述してください）。

spec:
  source:
    image: myapp:latest
    command:
      - /bin/sh
      - -c
      - "until nc -z postgres 5432; do sleep 1; done && node server.js"

すぐにできる修正

DB の準備が整っている場合は、失敗したサービスを再起動するだけで解決します。

npx zeabur@latest service restart --id <service-id> -y -i=false

問題が起動順序ではなく、データベースのマイグレーションにおける待機ループに関するものの場合は、zeabur-migration スキルを使用してください。