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

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

   ```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 手動建立 dump。

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

在 [Mastra 控制台](https://projects.mastra.ai)開啟項目，前往 **Runtime → Settings → Storage**，然後按一下 **Export Database** 按鈕。控制台會產生 Cloud Store 的完整 `.sql` dump，並直接下載至「下載項目」資料夾。

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

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

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

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

如果你偏好使用命令列，或需要以指令碼執行匯出，可直接使用 [Turso CLI](https://docs.turso.tech/cli) dump 資料庫。此方式需要資料庫 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** 複製兩個值，供下方的 dump 命令使用。

   > **備註:** 這些變數只會在使用 Cloud Store 佈建的項目中顯示。如果你在 Mastra Cloud 使用自備資料庫，便已擁有這些憑證，可以直接前往[將 Mastra 應用程式指向新資料庫](#point-your-mastra-app-at-the-new-database)。

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

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 dump。

   將支援人員提供的憑證（或之前已從控制台複製的值）設為環境變數，然後將資料庫 dump 至本機檔案。如果 URL 複製自控制台，請將 `libsql://` scheme 改為 `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`，然後只按資料庫名稱 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。

   ```bash
   turso auth login
   ```

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

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

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

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

完整設定（包括配合 DuckDB 儲存指標的複合儲存空間）請參閱[可觀察性概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)。

## 部署 Studio

部署託管的 Studio 執行個體：

```bash
mastra studio deploy
```

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

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

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

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

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

### 多個環境

單一 Mastra 平台項目可在多個[環境](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/environments)中執行相同程式碼庫，例如 `production` 及 `staging`。使用統一的 [`mastra deploy`](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/deploy) 命令部署至各個環境：

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

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

## 部署伺服器（可選）

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

```bash
mastra server deploy
```

這會建立獨立部署，提供穩定的 API URL、環境變數管理及自訂網域支援。完整步驟請參閱[伺服器部署指南](https://mastra.zisheng.pro/zh-HK/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 secret（例如 `MASTRA_API_TOKEN`）。

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

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

### 推送至 main 時部署伺服器

伺服器部署會從 `.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 的 client 更新至新伺服器或 Studio URL。查看 [Studio 可觀察性控制台](https://mastra.zisheng.pro/zh-HK/docs/studio/observability)，確認 Trace 已出現在新平台。確認所有功能運作正常後，刪除舊 Mastra Cloud 項目。

## 相關內容

- [Mastra 平台概覽](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/overview)
- [可觀察性概覽](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/observability)
- [Studio 部署](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/studio)
- [伺服器部署](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/server)
- [CLI 參考](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)