從 Mastra Cloud 遷移至 Mastra 平台

Mastra 平台以個別的 Studio 與 Server 產品、CLI 驅動的部署方式，以及新的可觀測性系統取代 Mastra Cloud。本指南會帶你完成每個步驟。

變更內容

領域	Mastra Cloud	Mastra 平台
產品	單一專案	個別的 Studio 與 Server
部署	推送時自動部署	由 CLI 驅動（mastra studio deploy、mastra server deploy）
建立專案	從 GitHub 匯入	CLI 在第一次部署時建立專案
儲存空間	受管理的 LibSQL（Cloud Store）或自備資料庫	自備託管資料庫
可觀測性	以 logger 為基礎	具有 exporter 的 Observability 類別
環境變數	設定專案時設定	第一次部署時從 .env 植入，之後在儀表板管理
URL	單一 URL	個別的 Studio 與 Server 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 手動建立傾印。

選項 A：從儀表板匯出（建議）

在 Mastra 儀表板中開啟專案，前往 Runtime → Settings → Storage。按一下 Export Database 按鈕。儀表板會產生完整的 Cloud Store .sql 傾印，並直接下載至你的「下載」資料夾。

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

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

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

選項 B：透過 Turso CLI 匯出

如果偏好使用命令列，或需要將匯出作業編寫成指令碼，可以使用 Turso CLI 直接傾印資料庫。此方式需要資料庫 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 取得這兩個值，供下方傾印命令使用。

   備註

   這些變數只會顯示於已佈建 Cloud Store 的專案。如果在 Mastra Cloud 中使用自備資料庫，你已經有這些認證，可直接跳至將 Mastra 應用程式指向新資料庫。

   資訊

   如果找不到變數、無法解密值，或 Turso CLI 拒絕權杖，請使用與 Mastra Cloud 帳戶關聯的電子郵件地址寄信至 support@mastra.ai，要求提供要匯出之專案的 libSQL URL 與驗證權杖。信中請附上專案名稱／ID。如果你的網路禁止 CLI 存取，支援團隊也可以代為執行傾印。

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 傾印。

   將支援團隊提供的認證（或先前已複製的儀表板值）設定為環境變數，再將資料庫傾印至本機檔案。如果從儀表板複製 URL，請將 libsql:// 通訊協定前綴改成 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，再僅以資料庫名稱傾印：turso db shell <database-name> ".dump" > mastra-cloud-dump.sql。該流程要求資料庫位於你擁有的 Turso 帳戶中，而 Cloud Store 並非如此，因此上方提供環境變數範例，作為此次單次匯出的替代方式。如果希望完全避免權杖插值，請要求支援團隊代為執行傾印，再將產生的 SQL 檔案寄給你。

   產生的 mastra-cloud-dump.sql 包含完整結構描述與資料：討論串及訊息歷程、Workflow 快照、Trace 與 Evals 分數。繼續之前，請將它儲存在安全的位置。

將傾印載入新的 libSQL 資料庫

此傾印是標準 SQL 檔案，可載入任何與 libSQL 相容的資料庫。下方範例使用新的 Turso 託管資料庫，讓遷移前後保持相同，並避免轉換結構描述。

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

   turso auth login

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

2. 一次完成建立新資料庫及載入傾印。

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

   --from-dump 會在建立時還原本機 SQLite／libSQL 傾印，比事後透過 turso db shell 管線傳入陳述式更快也更安全。請選擇靠近 Mastra Server 執行位置的區域，以縮短延遲；使用 turso db locations 列出可用區域，如果管理多個群組，請傳入 --group <group-name>。

   對於數 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 應用程式，並確認現有討論串或 Workflow run 能如預期載入 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 儲存空間，供 Studio 使用。
• 設定 MASTRA_PLATFORM_ACCESS_TOKEN 後，MastraPlatformExporter 會將可觀測性事件傳送至 Mastra 平台。
• SensitiveDataFilter 會在匯出前遮蔽 span 資料中的密碼、權杖與金鑰。

如需完整設定，包括搭配 DuckDB 儲存指標的複合儲存空間，請參閱可觀測性總覽。

部署 Studio

部署託管的 Studio 執行個體：

mastra studio deploy

CLI 會先建置專案並上傳成品，再進行部署。第一次部署時，會建立 .mastra-project.json 檔案，將本機專案連結至平台。請將此檔案提交至儲存庫。

本機環境檔案並非必要。如果專案目錄中存在 .env 或 .env.* 檔案，部署作業會將其中的環境變數納入 bundle。

若要以單一非互動式步驟建立新平台專案（而非個別執行 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 與環境變數，並各自保有部署歷程。

部署 Server（選填）

如果需要正式環境 API 端點，請部署 Server：

mastra server deploy

這會建立個別部署，並提供穩定的 API URL、環境變數管理與自訂網域支援。完整操作說明請參閱 Server 部署指南。

備註

第一次部署時，會自動納入 .env、.env.local 與 .env.production 中的環境變數。之後請透過網頁儀表板管理環境變數。 第一次部署前，請檢查並清理這些檔案，避免上傳只供開發使用或屬於個人的密碼。

設定 CI（選填）

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

先決條件

1. 建立 API 權杖：

   mastra auth tokens create ci-deploy

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

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

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

推送至 main 時部署 Server

Server 部署會從 .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 的使用者端更新為新的 Server 或 Studio URL。檢查 Studio 可觀測性儀表板，確認 Trace 顯示在新平台中。確認一切正常運作後，即可刪除舊 Mastra Cloud 專案。

相關內容

• Mastra 平台總覽
• 可觀測性總覽
• Studio 部署
• Server 部署
• CLI 參考文件