> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt # Mastra Cloud から Mastra platform へ移行する Mastra platform は、Mastra Cloud を独立した Studio 製品と Server 製品、CLI 主導のデプロイ、新しい Observability システムに置き換えます。このガイドでは、各移行手順を説明します。 ## 変更点 | 領域 | Mastra Cloud | Mastra platform | | ----------------- | ---------------------------------- | ----------------------------------------------------- | | **製品** | 単一プロジェクト | 独立した Studio と Server | | **デプロイ** | Push 時に自動デプロイ | CLI 主導（`mastra studio deploy`、`mastra server deploy`） | | **プロジェクト作成** | GitHub から import | 初回デプロイ時に CLI がプロジェクトを作成 | | **Storage** | マネージド LibSQL（Cloud Store）またはユーザー管理 | ユーザーがホストするデータベース | | **Observability** | Logger ベース | Exporter を使用する `Observability` クラス | | **環境変数** | プロジェクトのセットアップ時に設定 | 初回デプロイ時に `.env` から初期設定し、以降は Dashboard で管理 | | **URL** | 単一 URL | Studio と Server で別々の URL | ## 始める前に 1. CLI をインストールまたは更新します。 **npm**: ```bash npm install -g mastra@latest ``` **pnpm**: ```bash pnpm add -g mastra@latest ``` **Yarn**: ```bash yarn global add mastra@latest ``` **Bun**: ```bash bun add --global mastra@latest ``` 2. 認証します。 ```bash mastra auth login ``` 3. プロジェクトをローカルでビルドできることを確認します。 ```bash mastra build ``` ## Mastra Cloud Store をホスト型データベースに置き換える Mastra Cloud は、[Turso](https://turso.tech) を基盤とするマネージド libSQL データベースを提供していました。Mastra platform はデータベースをホストしないため、外部でホストするインスタンスを Storage に指定する必要があります。 すでにホスト型データベースを使用していた場合は、既存のデータベース設定を維持してください。接続文字列はハードコードせず、Dashboard の環境変数として設定します。 Cloud Store を使用していた場合は、以下の手順でデータを export し、ユーザーが管理する新しい libSQL データベースへ読み込みます。 ### Cloud Store のデータを export する Cloud Store のデータを export する方法は 2 つあります。Dashboard からダウンロードするか、Turso CLI で手動 Dump を作成します。 #### 方法 A：Dashboard から export する（推奨） [Mastra Dashboard](https://projects.mastra.ai) でプロジェクトを開き、**Runtime → Settings → Storage** へ移動します。**Export Database** ボタンをクリックします。Dashboard が Cloud Store 全体の `.sql` Dump を生成し、Downloads フォルダーへ直接ダウンロードします。 ダウンロードが完了したら、Dump を SQLite データベースファイルへ変換します。 ```bash sqlite3 mydb.db < ~/Downloads/mastra-cloud-dump.sql ``` これで、ローカルでの確認やバックアップが可能で、以降の手順で新しいデータベースのソースとして使用できる、ポータブルな `mydb.db` ファイルが作成されます。 #### 方法 B：Turso CLI で export する コマンドラインで作業する場合や export をスクリプト化する場合は、[Turso CLI](https://docs.turso.tech/cli) でデータベースを直接 Dump できます。この方法には、Dashboard に表示されるデータベース URL と Auth Token が必要です。 1. Dashboard から Cloud Store の認証情報を取得します。 [Mastra Dashboard](https://projects.mastra.ai) でプロジェクトを開き、**Runtime → Settings → Env Variables** へ移動します。Cloud Store を使用するプロジェクトでは、ユーザーの変数とともに以下の 2 つが追加されています。 - `MASTRA_STORAGE_URL`：libSQL 接続文字列（例：`libsql://-.turso.io`）。 - `MASTRA_STORAGE_AUTH_TOKEN`：そのデータベースに限定された、読み取り可能な Auth Token。 各行では、目のアイコンによる表示/非表示、Edit、Delete、Copy Value という標準の環境変数操作を使用できます。**Copy Value** で両方の値をコピーし、以下の Dump コマンドに使用します。 > **注記:** これらの変数は、Cloud Store がプロビジョニングされたプロジェクトにのみ表示されます。Mastra Cloud でユーザー管理のデータベースを使用していた場合は、すでにこれらの認証情報があるため、[Mastra アプリで新しいデータベースを使用する](#point-your-mastra-app-at-the-new-database)へ進んでください。 > **情報:** 変数がない、値を復号できない、または Turso CLI が Token を拒否する場合は、Mastra Cloud アカウントに関連付けられたアドレスから へメールを送り、export するプロジェクトの libSQL URL と Auth Token を依頼してください。プロジェクト名/ID も記載します。ネットワーク上で CLI アクセスがブロックされる場合は、Support に Dump の実行を依頼することもできます。 2. Turso CLI をインストールします。 ```bash brew install tursodatabase/tap/turso ``` ```bash curl -sSfL https://get.tur.so/install.sh | bash ``` Windows と Headless Install のオプションについては、[Turso CLI の概要](https://docs.turso.tech/cli/introduction)を参照してください。 3. データベースを SQL Dump へ export します。 Support から提供された認証情報（または先ほど Dashboard からコピーした値）を環境変数として設定し、データベースをローカルファイルへ Dump します。Dashboard から URL をコピーした場合は、`libsql://` Scheme を `https://` に置き換えてください。Auth Token とともに URL を渡す場合、Turso CLI は HTTPS 形式を要求します。 ```bash export MASTRA_STORAGE_URL="https://-.turso.io" export MASTRA_STORAGE_AUTH_TOKEN="" turso db shell "$MASTRA_STORAGE_URL?authToken=$MASTRA_STORAGE_AUTH_TOKEN" ".dump" > mastra-cloud-dump.sql ``` > **警告:** Auth Token を接続文字列に埋め込む方法は、Turso が推奨するパターンより安全性が低くなります。Token を含む完全な URL が Shell History、Process List、Terminal Log に残る可能性があります。Turso は、`turso auth login` を実行してから、データベース名のみで `turso db shell ".dump" > mastra-cloud-dump.sql` を実行する方法を公式に推奨しています。この手順ではユーザー所有の Turso アカウントにデータベースが存在する必要がありますが、Cloud Store は該当しないため、上記の環境変数を使う例を今回限りの export 手段として示しています。Token の展開自体を避ける場合は、Support に Dump の実行を依頼し、生成された SQL ファイルを送付してもらってください。 生成された `mastra-cloud-dump.sql` には、Thread と Message の履歴、Workflow Snapshot、Trace、Eval Score など、完全なスキーマとデータが含まれます。続行する前に安全な場所へ保管してください。 ### Dump を新しい libSQL データベースへ読み込む Dump は標準の SQL ファイルで、libSQL 互換の任意のデータベースへ読み込めます。以下の例では、新しい Turso ホスト型データベースを使用します。移行前後の構成を同等に保ち、スキーマ変換を避けられます。 1. ユーザー自身の Turso アカウントで Turso CLI を認証します。 ```bash turso auth login ``` Turso アカウントがない場合は、CLI に作成を求められます。プランの詳細は [Turso の料金](https://turso.tech/pricing)を参照してください。 2. 新しいデータベースを作成し、1 回の操作で Dump を読み込みます。 ```bash turso db create mastra-migrated --from-dump ./mastra-cloud-dump.sql ``` `--from-dump` は作成時にローカルの SQLite/libSQL Dump を復元します。後から `turso db shell` へ Statement を Pipe するより高速で安全です。Latency を最小限に抑えるため、Mastra Server の実行場所に近い Region を選択してください。利用可能な Region は `turso db locations` で一覧表示できます。複数の Group を管理する場合は `--group ` を指定します。 数 GB の Dump では `--wait` を追加し、データベースが完全に利用可能になるまで CLI を待機させます。 3. 新しいデータベースの接続認証情報を生成します。 ```bash turso db show mastra-migrated --url turso db tokens create mastra-migrated ``` 最初のコマンドは libSQL URL、2 番目のコマンドは Auth Token を出力します。`LibSQLStore` には両方が必要です。 ### Mastra アプリで新しいデータベースを使用する 新しい認証情報を、ローカルの `.env` または Mastra platform Dashboard の環境変数として設定します。 ```bash TURSO_DATABASE_URL="libsql://mastra-migrated-.turso.io" TURSO_AUTH_TOKEN="" ``` これらの変数を読み取るよう `LibSQLStore` を設定します。 ```ts import { Mastra } from '@mastra/core/mastra' import { LibSQLStore } from '@mastra/libsql' export const mastra = new Mastra({ storage: new LibSQLStore({ id: 'libsql-storage', url: process.env.TURSO_DATABASE_URL!, authToken: process.env.TURSO_AUTH_TOKEN, }), }) ``` すべてのオプションについては、[libSQL Storage リファレンス](https://mastra.zisheng.pro/ja/reference/storage/libsql)を参照してください。 ### 移行を確認する Cloud プロジェクトを停止する前に、新しいデータベースからアプリが必要とするデータを取得できることを確認します。 - `turso db shell mastra-migrated "SELECT name FROM sqlite_master WHERE type='table';"` を実行してテーブルを一覧表示します。出力には Mastra 管理のテーブル（`mastra_threads`、`mastra_messages`、`mastra_workflow_snapshot`、`mastra_traces` など）が含まれている必要があります。 - データが存在する既知のテーブルで行数を取得します。たとえば `turso db shell mastra-migrated "SELECT COUNT(*) FROM mastra_messages;"` を実行し、Cloud Store URL に対して同じクエリを実行した結果と比較します。 - 新しい認証情報で Mastra アプリを起動し、既存の Thread または Workflow Run が [Studio](https://mastra.zisheng.pro/ja/docs/studio/observability) で想定どおり読み込まれることを確認します。 ## Observability 設定を更新する Mastra Cloud は Logger ベースの Tracing を使用していました。Mastra platform は、明示的な Exporter を指定する `Observability` クラスを使用します。 Observability パッケージをインストールします。 **npm**: ```bash npm install @mastra/observability ``` **pnpm**: ```bash pnpm add @mastra/observability ``` **Yarn**: ```bash yarn add @mastra/observability ``` **Bun**: ```bash bun add @mastra/observability ``` **変更前（Mastra Cloud）：** ```ts import { Mastra } from '@mastra/core/mastra' import { PinoLogger } from '@mastra/loggers' export const mastra = new Mastra({ logger: new PinoLogger({ name: 'my-app', level: 'info' }), // traces appear in Cloud dashboard automatically }) ``` **変更後（Mastra platform）：** ```ts import { Mastra } from '@mastra/core/mastra' import { Observability, MastraStorageExporter, MastraPlatformExporter, SensitiveDataFilter, } from '@mastra/observability' export const mastra = new Mastra({ observability: new Observability({ configs: { default: { serviceName: 'my-app', exporters: [new MastraStorageExporter(), new MastraPlatformExporter()], spanOutputProcessors: [new SensitiveDataFilter()], }, }, }), }) ``` - `MastraStorageExporter` は Observability Event を Mastra Storage に永続化し、[Studio](https://mastra.zisheng.pro/ja/docs/studio/observability) で利用できるようにします。 - `MastraPlatformExporter` は、`MASTRA_PLATFORM_ACCESS_TOKEN` が設定されている場合に Observability Event を Mastra platform へ送信します。 - `SensitiveDataFilter` は、export 前に Span データから Password、Token、Key をマスクします。 DuckDB を使用した Metric 向けの Composite Storage など、すべての設定については、[Observability の概要](https://mastra.zisheng.pro/ja/docs/observability/overview)を参照してください。 ## Studio をデプロイする ホスト型 Studio インスタンスをデプロイします。 ```bash mastra studio deploy ``` CLI はプロジェクトをビルドし、Artifact をアップロードしてからデプロイします。初回デプロイ時に、ローカルプロジェクトを Platform に関連付ける `.mastra-project.json` ファイルが作成されます。このファイルをリポジトリへ Commit してください。 ローカルの Env ファイルは任意です。プロジェクトディレクトリに `.env` または `.env.*` ファイルがある場合、デプロイ時にその環境変数がバンドルされます。 `mastra studio projects create` を別途実行せず、非対話形式の 1 Step で新しい Platform プロジェクトを作成するには、`--project` で名前を渡し、`--yes` でデフォルトを受け入れます。 ```bash mastra studio deploy --project "my-new-project" --yes ``` 詳しくは、[Studio のデプロイ](https://mastra.zisheng.pro/ja/docs/studio/deployment)を参照してください。 ### 複数の環境 1 つの Mastra platform プロジェクトでは、`production` や `staging` など、複数の[環境](https://mastra.zisheng.pro/ja/docs/mastra-platform/environments)で同じコードベースを実行します。統一された [`mastra deploy`](https://mastra.zisheng.pro/ja/docs/mastra-platform/deploy) コマンドで各環境へデプロイします。 ```bash mastra deploy --env production --yes mastra deploy --env staging --env-file .env.staging --yes ``` 各環境には専用の URL と環境変数があり、デプロイ履歴も分かれています。 ## Server をデプロイする（任意） 本番 API エンドポイントが必要な場合は、Server をデプロイします。 ```bash mastra server deploy ``` これにより、安定した API URL、環境変数管理、カスタムドメイン対応を備えた独立したデプロイが作成されます。すべての手順については、[Server デプロイガイド](https://mastra.zisheng.pro/ja/docs/mastra-platform/server)を参照してください。 > **注記:** `.env`、`.env.local`、`.env.production` の環境変数は、初回デプロイ時に自動的に含まれます。以降は [Web Dashboard](https://projects.mastra.ai) で環境変数を管理します。 開発専用または個人の Secret をアップロードしないよう、初回デプロイ前にこれらのファイルを確認し、不要な値を削除してください。 ## CI を設定する（任意） Mastra Cloud は Push 時に自動デプロイしていました。Mastra platform は CLI 主導のデプロイを使用し、任意の CI Provider から実行できます。 ### 前提条件 1. API Token を作成します。 ```bash mastra auth tokens create ci-deploy ``` 2. Token を GitHub Actions の Secret（`MASTRA_API_TOKEN` など）として保存します。 3. 最初の手動デプロイで生成された `.mastra-project.json` をリポジトリへ Commit します。 `MASTRA_API_TOKEN` が設定されている場合、CLI は Headless Mode で実行され、すべての対話 Prompt を省略します。 ### main への Push 時に Server をデプロイする Server のデプロイは `.mastra-project.json` から Organization と Project を取得するため、Token 以外の環境変数は不要です。 ```yaml name: Deploy to Mastra Server on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 - uses: actions/setup-node@v4 with: node-version: '22' - run: pnpm install - run: pnpm mastra server deploy --yes --config .mastra-project.json env: MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }} ``` ### main への Push 時に Studio をデプロイする Studio のデプロイでは、`--config` を指定していても、Headless Mode で `MASTRA_ORG_ID` と `MASTRA_PROJECT_ID` の環境変数が必要です。 ```yaml name: Deploy to Mastra Studio on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 - uses: actions/setup-node@v4 with: node-version: '22' - run: pnpm install - run: pnpm mastra studio deploy --yes --config .mastra-project.json env: MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }} MASTRA_ORG_ID: ${{ secrets.MASTRA_ORG_ID }} MASTRA_PROJECT_ID: ${{ secrets.MASTRA_PROJECT_ID }} ``` ## 以前の Cloud プロジェクトを停止する 以前の Mastra Cloud URL を参照する Client を、新しい Server URL または Studio URL へ更新します。[Studio の Observability Dashboard](https://mastra.zisheng.pro/ja/docs/studio/observability)で Trace を確認し、新しい Platform に表示されることを確認します。すべてが正常に動作することを確認したら、以前の Mastra Cloud プロジェクトを削除してください。 ## 関連項目 - [Mastra platform の概要](https://mastra.zisheng.pro/ja/docs/mastra-platform/overview) - [Observability の概要](https://mastra.zisheng.pro/ja/docs/mastra-platform/observability) - [Studio のデプロイ](https://mastra.zisheng.pro/ja/docs/mastra-platform/studio) - [Server のデプロイ](https://mastra.zisheng.pro/ja/docs/mastra-platform/server) - [CLI リファレンス](https://mastra.zisheng.pro/ja/reference/cli/mastra)