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

# 从 Mastra Cloud 迁移到 Mastra 平台

Mastra 平台以独立的 Studio 和 Server 产品、CLI 驱动的部署以及新的 observability 系统取代 Mastra Cloud。本指南将带你完成每个迁移步骤。

## 变更内容

| 领域                | Mastra Cloud                 | Mastra 平台                                             |
| ----------------- | ---------------------------- | ----------------------------------------------------- |
| **产品**            | 单一项目                         | 独立的 Studio 和 Server                                   |
| **部署**            | 推送时自动部署                      | CLI 驱动（`mastra studio deploy`、`mastra server deploy`） |
| **创建项目**          | 从 GitHub 导入                  | CLI 在首次部署时创建项目                                        |
| **Storage**       | 托管 LibSQL（Cloud Store）或自带数据库 | 使用自行托管的数据库                                            |
| **Observability** | 基于 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 平台不会为你托管数据库，因此需要将 Storage 指向外部托管实例。

如果已经在使用自行托管的数据库，请保留现有数据库配置。请确保连接字符串在控制面板中设为环境变量，而不是硬编码。

如果使用 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，并直接下载到 Downloads 文件夹。

下载完成后，将 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 和数据：线程与消息历史、Workflow 快照、Trace 和 Evals 分数。继续前请将其存放在安全位置。

### 将 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 Server 运行位置的区域以尽量降低延迟。使用 `turso db locations` 列出可用区域；如果管理多个组，请传入 `--group <group-name>`。

   对于数 GB 的 dump，请添加 `--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 Storage 参考](https://mastra.zisheng.pro/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/docs/studio/observability) 中。

## 更新 observability 配置

Mastra Cloud 使用基于 Logger 的 tracing。Mastra 平台使用带显式 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 平台）：**

```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 事件持久化到 Mastra Storage，供 [Studio](https://mastra.zisheng.pro/docs/studio/observability) 使用。
- 设置 `MASTRA_PLATFORM_ACCESS_TOKEN` 后，`MastraPlatformExporter` 会向 Mastra 平台发送 observability 事件。
- `SensitiveDataFilter` 会在导出前遮盖 span 数据中的密码、令牌和 Key。

完整配置（包括将 DuckDB 组合用于 metric Storage）请参阅 [observability 概述](https://mastra.zisheng.pro/docs/observability/overview)。

## 部署 Studio

部署托管的 Studio 实例：

```bash
mastra studio deploy
```

CLI 会先构建项目并上传构件，然后进行部署。首次部署时会创建 `.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/docs/studio/deployment)。

### 多个环境

单个 Mastra 平台项目可以在多个[环境](https://mastra.zisheng.pro/docs/mastra-platform/environments)中运行同一代码库，例如 `production` 和 `staging`。请使用统一的 [`mastra deploy`](https://mastra.zisheng.pro/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/docs/mastra-platform/server)。

> **备注:** 首次部署时会自动包含 `.env`、`.env.local` 和 `.env.production` 中的环境变量。之后，请通过 [Web 控制面板](https://projects.mastra.ai)管理环境变量。 首次部署前请检查并清理这些文件，避免上传仅供开发使用或个人的 Secret。

## 设置 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 时部署 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

在无界面模式下，Studio 部署要求将 `MASTRA_ORG_ID` 和 `MASTRA_PROJECT_ID` 设为环境变量，即使已提供 `--config` 也是如此：

```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 observability 控制面板](https://mastra.zisheng.pro/docs/studio/observability)，确认 Trace 出现在新平台中。确认所有功能正常后，删除旧 Mastra Cloud 项目。

## 相关内容

- [Mastra 平台概述](https://mastra.zisheng.pro/docs/mastra-platform/overview)
- [Observability 概述](https://mastra.zisheng.pro/docs/mastra-platform/observability)
- [Studio 部署](https://mastra.zisheng.pro/docs/mastra-platform/studio)
- [Server 部署](https://mastra.zisheng.pro/docs/mastra-platform/server)
- [CLI 参考](https://mastra.zisheng.pro/reference/cli/mastra)