从 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

   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 平台不会为你托管数据库，因此需要将 Storage 指向外部托管实例。

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

如果使用 Cloud Store，请按照以下步骤导出数据，并将其加载到由你控制的新 libSQL 数据库中。

导出 Cloud Store 数据

可以通过两种方式导出 Cloud Store 数据：从控制面板下载，或使用 Turso CLI 手动创建 dump。

方案 A：从控制面板导出（推荐）

在 Mastra 控制面板中打开项目，前往 Runtime → Settings → Storage。点击 Export Database 按钮。控制面板会为 Cloud Store 生成完整的 .sql dump，并直接下载到 Downloads 文件夹。

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

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

   对于数 GB 的 dump，请添加 --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 Storage 参考。

验证迁移

停用 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 中。

更新 observability 配置

Mastra Cloud 使用基于 Logger 的 tracing。Mastra 平台使用带显式 exporter 的 Observability 类。

安装 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 将 observability 事件持久化到 Mastra Storage，供 Studio 使用。
• 设置 MASTRA_PLATFORM_ACCESS_TOKEN 后，MastraPlatformExporter 会向 Mastra 平台发送 observability 事件。
• SensitiveDataFilter 会在导出前遮盖 span 数据中的密码、令牌和 Key。

完整配置（包括将 DuckDB 组合用于 metric Storage）请参阅 observability 概述。

部署 Studio

部署托管的 Studio 实例：

mastra studio deploy

CLI 会先构建项目并上传构件，然后进行部署。首次部署时会创建 .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、环境变量和独立的部署历史。

部署 Server（可选）

如果需要生产 API 端点，请部署 Server：

mastra server deploy

这会创建独立部署，并提供稳定的 API URL、环境变量管理和自定义域名支持。完整演练请参阅 Server 部署指南。

备注

首次部署时会自动包含 .env、.env.local 和 .env.production 中的环境变量。之后，请通过 Web 控制面板管理环境变量。 首次部署前请检查并清理这些文件，避免上传仅供开发使用或个人的 Secret。

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

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

.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 observability 控制面板，确认 Trace 出现在新平台中。确认所有功能正常后，删除旧 Mastra Cloud 项目。

相关内容

• Mastra 平台概述
• Observability 概述
• Studio 部署
• Server 部署
• CLI 参考