zeabur-server-rent

Zeabur サーバーのレンタル

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

レンタルで提供されるのは基本 OS です — ZeaburOS のセットアップはその次の手順です

server rent で提供されるのは、Ubuntu と SSH だけです。それ以外はありません。Zeabur サービスはインストールされないため、レンタルしたばかりのサーバーでは、まだ Zeabur プロジェクトをホストできません。

これは意図された動作であり、失敗ではありません。マシンはユーザーのものであり、docker compose、1Panel、寶塔など、好きなように使えます。ZeaburOS — k3s を基盤とする Zeabur のマネージド環境 — は、別の手順として後からインストールします。このスキルでは、その手順も扱います。

レンタルする前に、希望する OS を確認してください

選択肢は 2 つあり、相互に置き換えられるものではありません。必ず明示的に確認してください。文脈から推測したり、デフォルトを選んだりしないでください。

選択肢	内容	該当する場合
Ubuntu	通常のセルフマネージド VPS です。レンタルが完了すれば、それで終了です。	ユーザーが、自分の好きなように設定できるマシンを望んでいる場合。
ZeaburOS	Ubuntu に Zeabur サービスを加えたものです。このサーバーに Zeabur プロジェクトをデプロイするために必要です。	ユーザーが、このサーバーにプロジェクトをデプロイしたい場合。レンタル後、数分ほど追加でかかります。

次のように質問してください。

このサーバーは ZeaburOS（Zeabur プロジェクトをデプロイできます）でセットアップしますか。それとも、自分で管理する通常の Ubuntu VPS として残しますか？

「アプリをデプロイしたい」という希望は、この質問への回答にはなりません。自分のマシンに docker compose でデプロイするユーザーも大勢います。必ず確認してください。

⚠️ レンタルには実際の費用が発生します — 明示的な確認が必須です

server rent を実行すると、ユーザーの支払い方法または Zeabur の残高にすぐに課金されます。-y フラグを指定すると CLI 自体の確認プロンプトが省略されるため、最後の安全策はあなたです。ユーザーが料金の明示された選択肢を明確に確認するまで、server rent を実行しないでください。

レンタルする前に、次のすべてを 1 つのメッセージでユーザーに提示する必要があります。

• プロバイダー（例：DigitalOcean）
• リージョン（例：New York／nyc3）
• プラン／仕様（例：s-2vcpu-4gb — 2 vCPU／4 GB RAM）
• 月額料金（例：US$27/月）
• ユーザーが選択した OS（上記の手順で選択したもの）
• レンタル時にすぐ課金されること

その後、次のように、はい／いいえで答えられる質問をしてください。

DigitalOcean New York の s-2vcpu-4gb を US$27/月でレンタルし、ZeaburOS としてセットアップします。今すぐお支払い方法に課金されます。購入を確定しますか？

ユーザーがこの料金の選択肢を明確に肯定して確認した後に限り、先に進んでください。

曖昧な返答から購入の同意を推測してはいけません。「2」のような数字だけの返答、「ok」、具体的な料金を提示する前に選んだ選択肢は、同意とはみなされません。数字による返答が有効な同意となるのは、プロバイダー、リージョン、仕様、料金が明記された番号付きの選択肢を、ユーザーがすでに確認している場合に限ります。判断に迷った場合は、レンタルせずに再確認してください。

ワークフロー

1. 利用可能な選択肢を確認する（絞り込みには zeabur-server-catalog スキルを使用）

npx zeabur@latest server catalog -i=false

2. JSON 出力からプロバイダー、リージョン、プランを選ぶ

3. ユーザーが希望する OS を確認する

上記のセクションを参照してください。これにより、手順 6 を実行するかどうかが決まります。

4. 選択肢の正確な内容を提示し、ユーザーから明示的な確認を得る

プロバイダー、リージョン、仕様、月額料金、OS、即時課金について提示します。ユーザーが以前に一般的な意味でサーバーのレンタルを依頼していても、この手順を省略しないでください。

5. レンタルする（確認後に限る）

npx zeabur@latest server rent --provider hetzner --region fsn1 --plan CAX11 -y -i=false

プロビジョニングには数分かかります。マシンが起動するまで、状態を確認してください。

npx zeabur@latest server get <server-id> -i=false

provisioningStatus が READY に、VM STATUS が RUNNING になるまで待ちます。

6. ユーザーが ZeaburOS を選択した場合：Zeabur サービスをインストールする

以下の「サーバーに ZeaburOS をインストールする」を参照してください。Ubuntu を選択した場合は、これで完了です。「通常の Ubuntu VPS を使用する」を参照してください。

サーバーに ZeaburOS をインストールする

まだ何も入っていないマシンでのみ実行してください — レンタルしたばかりのマシン、ベース OS に再インストールしたばかりのマシン、またはメッシュへの参加途中で止まっている WonderMesh デバイスが対象です。稼働中のシステムを消去せず、その上に k3s をインストールします。空のマシンであれば安全ですが、すでに使用中のマシンでは予期しない結果になる可能性があります。

ユーザーがセットアップしたマシンでは実行しないでください。 k3s はポート（6443、NodePort の範囲、4222 の NATS）を使用し、iptables のルールを書き換え、すでに Docker がある場合でも独自のコンテナランタイムを追加します。docker compose、1Panel、寶塔などが稼働しているマシンでは、インストールが成功するかどうかはすでに何がインストールされているかによって異なり、稼働中のものを壊す可能性があります。

そのようなマシンの場合は、代わりにダッシュボードを案内してください。サーバーの Settings → Danger Zone → Reinstall OS から ZeaburOS を選択します。再インストールすれば予測可能な状態になりますが、ディスクは消去されます。そのことを明確に伝え、先にバックアップするよう案内してください。判断するのはユーザーであり、あなたではありません。

切り替えはどちらの方向でも破壊的です。ZeaburOS から標準ディストリビューションへの切り替えも、標準ディストリビューションから ZeaburOS への切り替えも再インストールとなり、どちらもマシンを消去します。

マシンが空であれば、これを実行してください。

まだ Zeabur CLI にはありません — https://api.zeabur.com/graphql の Zeabur GraphQL API を直接呼び出してください。

これを実行する

1 つのブロックで、認証し、インストールを開始して、完了を待ちます。サーバー ID を置き換えて、そのまま実行してください。すべての部分が重要であり、その理由は以下で説明します。

SERVER_ID="<server-id>"

command -v jq >/dev/null 2>&1 || { echo "jq is required to read the API responses" >&2; exit 1; }

# Keep the token out of the process list: write it into a 0600 curl config
# passed with -K, never as -H "Authorization: ..." on the command line.
TOKEN="${ZEABUR_API_KEY:-$(grep '^token:' ~/.config/zeabur/cli.yaml 2>/dev/null | awk '{print $2}')}"
if [ -z "$TOKEN" ]; then
  echo "No Zeabur token found — set ZEABUR_API_KEY or run: npx zeabur@latest auth login" >&2
  exit 1
fi
ZAPI_CFG=$(mktemp)
chmod 600 "$ZAPI_CFG"
trap 'rm -f "$ZAPI_CFG"' EXIT
printf 'header = "Authorization: Bearer %s"\n' "$TOKEN" > "$ZAPI_CFG"
unset TOKEN

zapi() {
  curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
    -H "Content-Type: application/json" -d "$1"
}

# GraphQL reports failures as HTTP 200 with an `errors` array, so a request that
# "succeeded" can still be a hard failure. Stop on one instead of polling past it.
die_on_error() {
  if printf '%s' "$1" | jq -e 'has("errors")' >/dev/null 2>&1; then
    printf '%s' "$1" | jq -r '.errors[] | "\(.extensions.code // "ERROR"): \(.message)\(if .extensions.description then " — " + .extensions.description else "" end)"' >&2
    exit 1
  fi
}

# Start the install. This returns immediately — the work runs in the background.
RESP=$(zapi "{\"query\":\"mutation(\$id: ObjectID!) { installK3s(serverID: \$id) }\",\"variables\":{\"id\":\"$SERVER_ID\"}}")
die_on_error "$RESP"

# Wait for it, against a real 15-minute deadline.
DEADLINE=$(( $(date +%s) + 900 ))
while [ "$(date +%s)" -lt "$DEADLINE" ]; do
  sleep 30
  RESP=$(zapi "{\"query\":\"query(\$id: ObjectID!) { server(_id: \$id) { hasK3s provisioningStatus } }\",\"variables\":{\"id\":\"$SERVER_ID\"}}")
  die_on_error "$RESP"
  HAS_K3S=$(printf '%s' "$RESP" | jq -r '.data.server.hasK3s // "unknown"')
  STATUS=$(printf '%s' "$RESP" | jq -r '.data.server.provisioningStatus // "unknown"')
  echo "hasK3s=$HAS_K3S provisioningStatus=$STATUS"
  if [ "$HAS_K3S" = "true" ]; then echo "ZeaburOS is installed"; exit 0; fi
  if [ "$STATUS" = "FAILED" ]; then echo "Install failed: $RESP" >&2; exit 1; fi
done
echo "Still installing after 15 minutes — check the server's page in the dashboard" >&2
exit 2

各部分がこのようになっている理由：

• ミューテーションが戻ってきても、インストールが完了したわけではありません。 作業はバックグラウンドで実行されます。マシンに SSH 接続し、k3s をインストールして、ノードが起動するのを待つため、数分かかります。true の応答が意味するのは、受け付けられて開始されたことだけです。ミューテーションの結果だけで成功を報告してはいけません。
• 成功の判定は provisioningStatus: "READY" ではなく hasK3s: true です。 ステータスは READY → INITIALIZING → READY と遷移するため、インストール開始前の状態も READY です。これをポーリングすると、早すぎる時点で確認した瞬間に成功と判定されます。しかも、マシンは実際に READY なので、結果は正しく見えてしまいます。
• FAILED は別途チェックします。そのため、インストールに失敗した場合は、時間切れまで待つのではなく待機を終了します。
• すべての応答で、まず errors を確認します。 GraphQL は失敗を、errors 配列があり data がない HTTP 200 として返します。そのため、未認証のトークン、無効なサーバー ID、または以下に記載する前提条件の失敗があると、そうでなければ「まだインストール中」と解釈され、有用な情報が何もないまま 15 分間待つことになります。extensions.code は以下の表にある機械可読コード、extensions.description はユーザー向けの説明です。
• 生の JSON を grep するのではなく、jq で解析します。 grep '"hasK3s":true' は、コロンの後に空白が入った形式で応答が返るだけで機能しなくなり、さらに失敗を見逃します。一致しなかった場合に「まだインストール中」と見なされるためです。同じ理由から、このブロックは jq がない場合、誤った解析を黙って行うのではなく、開始を拒否します。
• 待機時間はカウンターではなく期限で管理します。 リクエスト時間を加えると、30 × sleep 30 は 15 分を超えて実行されます。タイムスタンプと比較することで、指定した上限が実際の上限になります。
• トークンが見つからなければ停止します。 続行すると未認証のリクエストが送信され、結果の 401 は「ログインしていません」ではなく「サーバーが壊れている」と解釈されてしまいます。
• trap は途中のコマンドが失敗した場合でも curl 設定ファイルを削除します。 ツールや Bash の呼び出しごとに新しいシェルが起動するため、ブロック全体をまとめて実行してください。$ZAPI_CFG は次の呼び出しには引き継がれません。

ZEABUR_API_KEY が設定されていれば、そちらを優先してください。そうでなければ、npx zeabur@latest auth login によって書き込まれる ~/.config/zeabur/cli.yaml からトークンを取得します（ユーザーがログインしていない場合は、zeabur-auth スキルを使用してください）。

エラー

次のケースでは、ミューテーションは最初に失敗します。生の GraphQL エラーではなく、その意味を伝えてください。

コード	発生したこと	ユーザーへの説明
K3S_ALREADY_INSTALLED	サーバーではすでに ZeaburOS が稼働しています	対応は不要です。プロジェクトを利用できます
SERVER_NOT_READY	プロビジョニング中です	provisioningStatus: READY になるまで待ってから、再試行してください
K3S_INSTALL_IN_PROGRESS	インストールがすでに実行中、または完了したばかりです	ミューテーションを再送信しないでください。そのままポーリングしてください
SERVER_NOT_FOUND	ID が間違っているか、サーバーが削除されています	server list で ID を再確認してください

トランスポート層でミューテーションがタイムアウトしても、確認せずに再試行しないでください。 サーバー側ではすでにインストールが実行中の可能性があります。まず上記のクエリをポーリングし、サーバーがドキュメントに記載されたインストール前の状態、つまり hasK3s: false かつ provisioningStatus: "READY" に戻った場合にのみ、ミューテーションを再送信してください。

FAILED になったインストールを自動で再試行しないでください。 FAILED は終端状態であり、マシン上でインストールに実際に失敗したことを意味します。再試行しても同じ失敗が繰り返されるだけです。失敗を報告し、ユーザーの判断に任せてください。

支払いエラー

ユーザーに登録済みのクレジットカードがない場合、または残高が不足している場合、CLI は次の内容を返します。

ERROR  Rent server failed: please bind a credit card or recharge credits first
INFO   Please bind a credit card or top up your balance at: https://zeabur.com/account/billing

対応： https://zeabur.com/account/billing で支払い方法の追加または残高のチャージを案内してから、再試行してください。

通常の Ubuntu VPS を使用する場合

ほかに必要な作業はありません。SSH で接続し、ユーザーの好みに合わせてマシンをセットアップしてください（docker compose、1Panel、寶塔など）。zeabur-server-ssh スキルを使用してください。

npx zeabur@latest server exec --id <server-id> -- <command>

このようなマシンには kubectl がなく、管理対象となる Zeabur サービスもありません。

ZeaburOS が稼働していないサーバーに対して、zeabur-project-create を実行しないでください。 Zeabur サービスがないため、そこでプロジェクトを作成しようとしても失敗します。まず ZeaburOS をインストールしてください。