> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# 從 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**:

   ```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 平台不會為你託管資料庫，因此必須將儲存空間指向外部託管的執行個體。

如果原本已使用託管資料庫（「自備資料庫」），請保留現有資料庫設定。請確認連線字串是設定為儀表板中的環境變數，而非硬式編碼。

如果原本使用 Cloud Store，請依照下列步驟匯出資料，再將資料載入由你控制的新 libSQL 資料庫。

### 匯出 Cloud Store 資料

你可以用兩種方式匯出 Cloud Store 資料：從儀表板下載，或使用 Turso CLI 手動建立傾印。

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

在 [Mastra 儀表板](https://projects.mastra.ai)中開啟專案，前往 **Runtime → Settings → Storage**。按一下 **Export Database** 按鈕。儀表板會產生完整的 Cloud Store `.sql` 傾印，並直接下載至你的「下載」資料夾。

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

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

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

#### 選項 B：透過 Turso CLI 匯出

如果偏好使用命令列，或需要將匯出作業編寫成指令碼，可以使用 [Turso CLI](https://docs.turso.tech/cli) 直接傾印資料庫。此方式需要資料庫 URL 與驗證權杖，兩者都會顯示在儀表板中。

1. 從儀表板取得 Cloud Store 認證。

   在 [Mastra 儀表板](https://projects.mastra.ai)中開啟專案，前往 **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 應用程式指向新資料庫](#point-your-mastra-app-at-the-new-database)。

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

2. 安裝 Turso CLI。

   ```bash
   brew install tursodatabase/tap/turso
   ```

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

   如需 Windows 與無介面安裝選項，請參閱 [Turso CLI 簡介](https://docs.turso.tech/cli/introduction)。

3. 將資料庫匯出至 SQL 傾印。

   將支援團隊提供的認證（或先前已複製的儀表板值）設定為環境變數，再將資料庫傾印至本機檔案。如果從儀表板複製 URL，請將 `libsql://` 通訊協定前綴改成 `https://`；透過驗證權杖傳入 URL 時，Turso CLI 要求使用 HTTPS 格式。

   ```bash
   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。

   ```bash
   turso auth login
   ```

   如果沒有 Turso 帳戶，CLI 會提示你建立帳戶。方案詳情請參閱 [Turso 定價](https://turso.tech/pricing)。

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

   ```bash
   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. 產生新資料庫的連線認證。

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

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

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

將新認證設定為環境變數，可設定在本機 `.env` 或 Mastra 平台儀表板中：

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

設定 `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 儲存空間參考文件](https://mastra.zisheng.pro/zh-TW/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 應用程式，並確認現有討論串或 Workflow run 能如預期載入 [Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/observability)。

## 更新可觀測性設定

Mastra Cloud 使用以 logger 為基礎的 Tracing。Mastra 平台使用具有明確 exporter 的 `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 平台）：**

```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](https://mastra.zisheng.pro/zh-TW/docs/studio/observability) 使用。
- 設定 `MASTRA_PLATFORM_ACCESS_TOKEN` 後，`MastraPlatformExporter` 會將可觀測性事件傳送至 Mastra 平台。
- `SensitiveDataFilter` 會在匯出前遮蔽 span 資料中的密碼、權杖與金鑰。

如需完整設定，包括搭配 DuckDB 儲存指標的複合儲存空間，請參閱[可觀測性總覽](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)。

## 部署 Studio

部署託管的 Studio 執行個體：

```bash
mastra studio deploy
```

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

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

若要以單一非互動式步驟建立新平台專案（而非個別執行 `mastra studio projects create`），請使用 `--project` 傳入名稱，並使用 `--yes` 接受預設值：

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

詳情請參閱 [Studio 部署](https://mastra.zisheng.pro/zh-TW/docs/studio/deployment)。

### 多個環境

單一 Mastra 平台專案可在多個[環境](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/environments)中執行相同程式碼庫，例如 `production` 與 `staging`。使用統一的 [`mastra deploy`](https://mastra.zisheng.pro/zh-TW/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/zh-TW/docs/mastra-platform/server)。

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

## 設定 CI（選填）

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

### 先決條件

1. 建立 API 權杖：

   ```bash
   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` 取得組織與專案，因此除了權杖外，不需要其他環境變數：

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

在無介面模式中，即使提供 `--config`，Studio 部署仍需要以環境變數提供 `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 的使用者端更新為新的 Server 或 Studio URL。檢查 [Studio 可觀測性儀表板](https://mastra.zisheng.pro/zh-TW/docs/studio/observability)，確認 Trace 顯示在新平台中。確認一切正常運作後，即可刪除舊 Mastra Cloud 專案。

## 相關內容

- [Mastra 平台總覽](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/overview)
- [可觀測性總覽](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/observability)
- [Studio 部署](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/studio)
- [Server 部署](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/server)
- [CLI 參考文件](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)