從 Mastra Cloud 遷移至 Mastra 平台

Mastra 平台以獨立的 Studio 及伺服器產品、由 CLI 驅動的部署，以及全新的可觀察性系統取代 Mastra Cloud。本指南會帶你完成每個步驟。

變更內容

範疇	Mastra Cloud	Mastra 平台
產品	單一項目	獨立的 Studio 及伺服器
部署	推送時自動部署	由 CLI 驅動（mastra studio deploy、mastra server deploy）
建立項目	從 GitHub 匯入	CLI 在首次部署時建立項目
儲存空間	受管理的 LibSQL（Cloud Store），或使用自備服務	使用自備的託管資料庫
可觀察性	以 logger 為基礎	配合 exporter 的 Observability 類別
環境變數	建立項目時設定	首次部署時從 .env 載入初始值，其後在控制台管理
URL	單一 URL	獨立的 Studio 及伺服器 URL

開始之前

1. 安裝或更新 CLI：

   npm

   npm install -g mastra@latest

   pnpm

   pnpm add -g mastra@latest

   Yarn

   yarn global add mastra@latest

   Bun

   bun add --global mastra@latest

2. 驗證身分：

   mastra auth login

3. 確認項目可在本機成功建置：

   mastra build

以託管資料庫取代 Mastra Cloud Store

Mastra Cloud 提供由 Turso 支援的受管理 libSQL 資料庫。Mastra 平台不會為你託管資料庫，因此你需要將儲存空間指向外部託管的執行個體。

如果你本來已使用託管資料庫（「自備服務」），請保留現有資料庫設定。請確保連線字串已在控制台中設為環境變數，而不是直接寫入程式碼。

如果你使用 Cloud Store，請依照以下步驟匯出資料，並載入你控制的新 libSQL 資料庫。

匯出 Cloud Store 資料

你可以透過兩種方式匯出 Cloud Store 資料：從控制台下載，或使用 Turso CLI 手動建立 dump。

選項 A：從控制台匯出（建議）

在 Mastra 控制台開啟項目，前往 Runtime → Settings → Storage，然後按一下 Export Database 按鈕。控制台會產生 Cloud Store 的完整 .sql dump，並直接下載至「下載項目」資料夾。

下載完成後，將 dump 轉換成 SQLite 資料庫檔案：

sqlite3 mydb.db < ~/Downloads/mastra-cloud-dump.sql

你現在已有可攜式 mydb.db 檔案，可在本機檢查、備份，或在以下步驟中作為新資料庫的來源。

選項 B：透過 Turso CLI 匯出

如果你偏好使用命令列，或需要以指令碼執行匯出，可直接使用 Turso CLI dump 資料庫。此方式需要資料庫 URL 及驗證權杖，兩者都會顯示於控制台。

1. 從控制台取得 Cloud Store 憑證。

   在 Mastra 控制台開啟項目，前往 Runtime → Settings → Env Variables。由 Cloud Store 支援的項目會在你自己的變數旁注入兩個變數：

   • MASTRA_STORAGE_URL：libSQL 連線字串（例如 libsql://<db-name>-<org>.turso.io）。
   • MASTRA_STORAGE_AUTH_TOKEN：範圍限於該資料庫並具備讀取權限的驗證權杖。

   每一列都支援標準環境變數操作，包括使用眼睛切換按鈕顯示／隱藏、Edit、Delete 及 Copy Value。使用 Copy Value 複製兩個值，供下方的 dump 命令使用。

   備註

   這些變數只會在使用 Cloud Store 佈建的項目中顯示。如果你在 Mastra Cloud 使用自備資料庫，便已擁有這些憑證，可以直接前往將 Mastra 應用程式指向新資料庫。

   資訊

   如果變數不存在、值無法解密，或 Turso CLI 拒絕權杖，請使用與 Mastra Cloud 帳戶關聯的電郵地址，傳送電郵至 support@mastra.ai，索取要匯出項目的 libSQL URL 及驗證權杖。請附上項目名稱／ID。如果你的網絡封鎖 CLI 存取，支援人員亦可代為執行 dump。

2. 安裝 Turso CLI。

   macOS

   brew install tursodatabase/tap/turso

   Linux / WSL

   curl -sSfL https://get.tur.so/install.sh | bash

   關於 Windows 及無人值守安裝選項，請參閱 Turso CLI 簡介。

3. 將資料庫匯出為 SQL dump。

   將支援人員提供的憑證（或之前已從控制台複製的值）設為環境變數，然後將資料庫 dump 至本機檔案。如果 URL 複製自控制台，請將 libsql:// scheme 改為 https://；同時傳入 URL 及驗證權杖時，Turso CLI 需要 HTTPS 格式。

   export MASTRA_STORAGE_URL="https://<db-name>-<org>.turso.io"
   export MASTRA_STORAGE_AUTH_TOKEN="<token-from-dashboard-or-support>"
   
   turso db shell "$MASTRA_STORAGE_URL?authToken=$MASTRA_STORAGE_AUTH_TOKEN" ".dump" > mastra-cloud-dump.sql

   注意

   將驗證權杖嵌入連線字串，不及 Turso 建議的方式安全；包含權杖的完整 URL 可能會出現在 shell 歷程、程序清單及終端機記錄中。Turso 官方建議先執行 turso auth login，然後只按資料庫名稱 dump：turso db shell <database-name> ".dump" > mastra-cloud-dump.sql。此流程要求資料庫位於你擁有的 Turso 帳戶內，但 Cloud Store 並非如此，因此上方提供環境變數範例，作為這次單次匯出的替代方式。如果你想完全避免插入權杖，請要求支援人員代為執行 dump，並將產生的 SQL 檔案傳送給你。

   產生的 mastra-cloud-dump.sql 包含完整 schema 及資料：thread 和訊息歷程、Workflow snapshot、Trace，以及 eval 分數。繼續前請將它儲存於安全位置。

將 dump 載入新的 libSQL 資料庫

dump 是標準 SQL 檔案，可以載入任何兼容 libSQL 的資料庫。以下範例使用由 Turso 託管的新資料庫，以維持相同的遷移方式並避免轉換 schema。

1. 使用你自己的 Turso 帳戶驗證 Turso CLI。

   turso auth login

   如果你沒有 Turso 帳戶，CLI 會提示你建立一個。方案詳情請參閱 Turso 定價。

2. 在一個步驟內建立新資料庫並載入 dump。

   turso db create mastra-migrated --from-dump ./mastra-cloud-dump.sql

   --from-dump 會在建立資料庫時還原本機 SQLite/libSQL dump，比事後透過 turso db shell 管道輸送陳述式更快、更安全。選擇接近 Mastra 伺服器執行位置的區域，以盡量減低延遲；使用 turso db locations 列出可用區域。如果你管理多個群組，請傳入 --group <group-name>。

   如果 dump 達數 GB，請加入 --wait，讓 CLI 阻塞直至資料庫完全可用。

3. 為新資料庫產生連線憑證。

   turso db show mastra-migrated --url
   turso db tokens create mastra-migrated

   第一個命令會輸出 libSQL URL，第二個命令則輸出驗證權杖。LibSQLStore 需要兩者才能運作。

將 Mastra 應用程式指向新資料庫

在本機 .env 或 Mastra 平台控制台中，將新憑證設為環境變數：

.env

TURSO_DATABASE_URL="libsql://mastra-migrated-<org>.turso.io"
TURSO_AUTH_TOKEN="<token-from-turso-db-tokens-create>"

設定 LibSQLStore 從這些變數讀取資料：

src/mastra/index.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 儲存空間參考。

驗證遷移

停用 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 執行可在 Studio 中按預期載入。

更新可觀察性設定

Mastra Cloud 使用以 logger 為基礎的 tracing。Mastra 平台使用配合明確 exporter 的 Observability 類別。

安裝可觀察性套件：

npm

npm install @mastra/observability

pnpm

pnpm add @mastra/observability

Yarn

yarn add @mastra/observability

Bun

bun add @mastra/observability

遷移前（Mastra Cloud）：

src/mastra/index.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 平台）：

src/mastra/index.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 將可觀察性事件保存至 Mastra Storage，供 Studio 使用。
• 設定 MASTRA_PLATFORM_ACCESS_TOKEN 後，MastraPlatformExporter 會將可觀察性事件傳送至 Mastra 平台。
• SensitiveDataFilter 會在匯出前遮蔽 span 資料中的密碼、權杖及金鑰。

完整設定（包括配合 DuckDB 儲存指標的複合儲存空間）請參閱可觀察性概覽。

部署 Studio

部署託管的 Studio 執行個體：

mastra studio deploy

CLI 會先建置項目並上載 artifact，然後再部署。首次部署時，系統會建立 .mastra-project.json 檔案，將本機項目連結至平台。請將此檔案提交至儲存庫。

本機環境檔案並非必要。如果項目目錄中有 .env 或 .env.* 檔案，部署時會將其中的環境變數一併封裝。

如要以一個非互動式步驟建立新的平台項目（而不是另外執行 mastra studio projects create），請使用 --project 傳入名稱，並使用 --yes 接受預設值：

mastra studio deploy --project "my-new-project" --yes

詳情請參閱 Studio 部署。

多個環境

單一 Mastra 平台項目可在多個環境中執行相同程式碼庫，例如 production 及 staging。使用統一的 mastra deploy 命令部署至各個環境：

mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes

每個環境都有專用 URL、環境變數及獨立部署歷程。

部署伺服器（可選）

如果需要生產環境 API 端點，請部署伺服器：

mastra server deploy

這會建立獨立部署，提供穩定的 API URL、環境變數管理及自訂網域支援。完整步驟請參閱伺服器部署指南。

備註

首次部署時，系統會自動包含 .env、.env.local 及 .env.production 中的環境變數。其後請透過網頁控制台管理環境變數。 首次部署前，請檢查並清理這些檔案，以免上載只供開發使用或屬於個人的機密資料。

設定 CI（可選）

Mastra Cloud 會在推送時自動部署。Mastra 平台採用由 CLI 驅動的部署方式，可從任何 CI Provider 執行。

先決條件

1. 建立 API 權杖：

   mastra auth tokens create ci-deploy

2. 將權杖儲存為 GitHub Actions secret（例如 MASTRA_API_TOKEN）。

3. 將 .mastra-project.json 提交至儲存庫（首次手動部署時產生）。

設定 MASTRA_API_TOKEN 後，CLI 會以無人值守模式執行，並略過所有互動式提示。

推送至 main 時部署伺服器

伺服器部署會從 .mastra-project.json 取得組織及項目，因此除了權杖外，不需要其他環境變數：

.github/workflows/deploy-server.yml

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 時部署 Studio

在無人值守模式中，即使已提供 --config，Studio 部署仍需要以環境變數傳入 MASTRA_ORG_ID 及 MASTRA_PROJECT_ID：

.github/workflows/deploy-studio.yml

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 更新至新伺服器或 Studio URL。查看 Studio 可觀察性控制台，確認 Trace 已出現在新平台。確認所有功能運作正常後，刪除舊 Mastra Cloud 項目。

相關內容

• Mastra 平台概覽
• 可觀察性概覽
• Studio 部署
• 伺服器部署
• CLI 參考