zeabur-object-storage

Zeabur オブジェクトストレージのデプロイと統合

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

オブジェクトストレージをデプロイする

デプロイする前に、必ず先に zeabur-template スキルを読み込んでください。 Zeabur テンプレートとは何か、どのように機能するか、どのようにデプロイするかを理解するためです。このスキルでは、オブジェクトストレージ固有の統合のみを扱います。テンプレートに関する知識はすべて zeabur-template に記載されています。

ストレージテンプレートを検索します。

npx zeabur@latest template search minio -i=false --json

デプロイ数が最も多いテンプレートを選びます。

• ユーザーから指定がない場合は、MinIO をデフォルトとして選択します。 最も広くサポートされており、Web コンソールが組み込まれ、デフォルトのバケットが自動作成されます。
• 軽量・最小構成を希望する場合や、RustFS について具体的に言及している場合は、RustFS を推奨します。

---

デプロイ後：接続方法

オブジェクトストレージに必要なものは、S3 API エンドポイント（接続方法）、アクセスキー＋シークレットキー（認証方法）、およびバケット名です。

接続方法 — service network

npx zeabur@latest service network --id <storage-service-id> -i=false

以下の情報が表示されます。

• プライベートネットワーク — S3 API 用の内部 hostname:port（例：minio.zeabur.internal:9000）
• パブリックネットワーク — HTTP ポートの場合、外部からアクセスするにはドメインのバインドが必要であることが表示されます

MinIO と RustFS のポートは HTTP タイプのため、パブリックアクセスにはポートフォワーディングではなく、ドメインのバインドを使用します。ダッシュボードで API ポートにドメインをバインドすると、外部 S3 エンドポイント（例：https://minio-api.zeabur.app）を取得できます。

認証方法 — variable list

npx zeabur@latest variable list --id <storage-service-id> -i=false

アクセスキー、シークレットキー、その他の認証情報が一覧表示されます。

---

MinIO

認証情報（variable list から取得）

変数	説明
MINIO_USERNAME	アクセスキー ID（デフォルト：minio）
MINIO_PASSWORD	シークレットアクセスキー（自動生成）
MINIO_DEFAULT_BUCKET	デフォルトのバケット名（デフォルト：zeabur）
MINIO_CONSOLE_URL	Web コンソールの URL

アプリから接続する（同じプロジェクト）

アプリサービスに次の環境変数を設定します。

S3_ENDPOINT=http://minio.zeabur.internal:9000
S3_ACCESS_KEY=${MINIO_USERNAME}
S3_SECRET_KEY=${MINIO_PASSWORD}
S3_BUCKET=zeabur
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

S3 エンドポイントは変数として公開されていないため、service network の内部ホスト名を使ってハードコードする必要があります。

ローカルマシンから接続する

API ポートにドメインをバインドし、そのドメインをエンドポイントとして使用します。

# MinIO Client (mc)
mc alias set zeabur https://MINIO_API_DOMAIN MINIO_USERNAME MINIO_PASSWORD
mc ls zeabur/
mc cp local-file.txt zeabur/zeabur/

# AWS CLI
aws --endpoint-url https://MINIO_API_DOMAIN s3 ls

Web コンソール

ブラウザーで MINIO_CONSOLE_URL を開き、MINIO_USERNAME / MINIO_PASSWORD を使ってログインします。MinIO は初回起動時に zeabur バケットを自動作成します。

---

RustFS

認証情報（variable list から取得）

変数	説明
RUSTFS_USERNAME	アクセスキー ID（デフォルト：rustfs）
RUSTFS_PASSWORD	シークレットアクセスキー（自動生成）

アプリから接続する（同じプロジェクト）

アプリサービスに次の環境変数を設定します。

S3_ENDPOINT=http://rustfs.zeabur.internal:9000
S3_ACCESS_KEY=${RUSTFS_USERNAME}
S3_SECRET_KEY=${RUSTFS_PASSWORD}
S3_BUCKET=my-bucket
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

S3 エンドポイントは変数として公開されていないため、service network の内部ホスト名を使ってハードコードする必要があります。また、正確なサービス名を確認するには service list も参照してください（rustfs ではなく RustFS の可能性があります）。

最初にバケットを作成する必要があります。 MinIO とは異なり、RustFS の初期状態ではバケットがありません。

ローカルマシンから接続する

API ポートにドメインをバインドしてから、次のようにします。

mc alias set zeabur https://RUSTFS_API_DOMAIN RUSTFS_USERNAME RUSTFS_PASSWORD
mc mb zeabur/my-bucket
mc ls zeabur/

Web コンソール

ブラウザーでポート 9001 にバインドしたドメインを開き、RUSTFS_USERNAME / RUSTFS_PASSWORD を使ってログインします。アプリでファイルをアップロードする前に、バケットを作成してください。

---

SDK の例

S3 互換 SDK には、エンドポイント、アクセスキー、シークレットキー、リージョン、および forcePathStyle: true が必要です。

// Node.js (AWS SDK v3)
const { S3Client } = require("@aws-sdk/client-s3");
const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
  region: "us-east-1",
  forcePathStyle: true,
});

# Python (boto3)
import boto3, os
s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
    region_name="us-east-1",
)

// Go (aws-sdk-go-v2)
cfg, _ := config.LoadDefaultConfig(ctx,
    config.WithRegion("us-east-1"),
    config.WithCredentialsProvider(
        credentials.NewStaticCredentialsProvider(accessKey, secretKey, ""),
    ),
)
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.BaseEndpoint = aws.String(endpoint)
    o.UsePathStyle = true
})

---

注意事項

1. forcePathStyle は必須です — 設定しない場合、S3 SDK は仮想ホスト形式の URL（http://bucket.host:9000/key）を使用するため、名前解決できません。「bucket not found」エラーの主な原因です。
2. アップロード前にバケットを作成してください（RustFS） — MinIO は zeabur バケットを自動作成しますが、RustFS は作成しません。コンソールまたは mc mb で作成してください。
3. S3 エンドポイントはテンプレート変数ではありません — service network のホスト名（内部）またはバインドされたドメイン（外部）を使用して、直接指定してください。
4. 変数参照 — Zeabur ではフラットな名前空間を使用します。${MINIO_USERNAME} などは Zeabur Dashboard から設定してください。${} の展開には CLI の既知のバグがあります。
5. コンソールと API のポート — MinIO：API は 9000、コンソールは 9090 です。RustFS：API は 9000、コンソールは 9001 です。アプリは API ポートに接続します。