Mastra platform 上的 Studio

Mastra platform 上的 Studio 是一个托管的可视化工作区，用于测试 agents、运行 workflows 以及检查 traces。当你希望与团队共享 Studio 而不自行托管 Studio UI 时，请使用它。

你可以通过下方所示的 CLI 部署 Studio，或连接 GitHub 仓库实现推送即部署。仓库关联流程请参阅 GitHub 集成。

快速开始

1. 按照入门指南创建你的第一个 Mastra 项目。

2. 全局安装 mastra CLI：

   npm

   npm install -g mastra

   pnpm

   pnpm add -g mastra

   Yarn

   yarn global add mastra

   Bun

   bun add --global mastra

3. 使用单条命令部署 Studio：

   mastra deploy

   部署成功后，CLI 会输出已部署 Studio 实例的 URL。

首次部署时，CLI 会提示你创建新项目或选择现有项目。随后它会在项目目录中创建 .mastra-project.json 文件。此文件将本地项目关联到平台项目，包含 projectId、projectName 和 organizationId。请将此文件提交到仓库，以便 CI/CD 知道要部署到哪个项目。

部署如何工作

mastra deploy 命令会构建项目并将 src/mastra/ 编译到 .mastra/output。它将该输出打包为 artifact ZIP，然后上传并部署到云端 sandbox。

部署会经历 queued → uploading → starting → running 的状态转换，如果出现问题则变为 failed。如果项目已有运行中的 sandbox，平台会原地更新它，无需停机。否则，它会创建一个新的 sandbox。实例 URL 按项目 slug 分配，并在多次部署之间保持稳定。

完整的 flags 列表和 CI/CD 用法请参阅 mastra deploy CLI 参考。

身份验证

默认情况下，Mastra platform 上的每次 Studio 部署都受平台 auth 保护。平台组织的成员使用其平台账户登录，其他任何人都无法访问已部署的 Studio。你无需进行任何配置即可获得此行为。

平台 auth 仅适用于 Studio UI。服务器的 API 路由由你自己的 server.auth 配置管理，如果未设置则保持开放。

角色和权限

平台 auth 会将组织角色映射到 Studio 权限：

平台角色	Studio 权限
admin	完全访问（*）
member	读取和执行
viewer	只读

要自定义此映射，请在 Mastra 配置的 studio.rbac 上设置 roleMapping。设置后，你的映射会替换平台默认值。权限格式请参阅基于角色的访问控制。

使用你自己的 auth

要为已部署的 Studio 使用自己的 auth 提供器而不是平台 auth，请在项目上设置环境变量：

MASTRA_PLATFORM_STUDIO_AUTH=disabled

将其添加到部署时使用的 env 文件，或通过 dashboard 存储在项目上，然后重新部署。禁用平台 auth 后，部署不会触碰你的 auth 和 RBAC 配置。你自己的提供器会驱动 Studio 登录流程，与自托管部署完全一样。studio.auth 保护 Studio UI，而 server.auth 保护你的 API 路由。未设置 studio.auth 时，Studio 请求会回退到 server.auth。

注意

禁用平台 auth 会关闭平台账户登录。如果在未配置自己的 auth 提供器的情况下禁用它，已部署的 Studio 和所有 API 路由都将公开可访问。

如果你保持平台 auth 启用并同时配置自己的 studio.auth，两个提供器都会验证 token，但登录界面只提供平台登录流程。要通过自己的提供器登录，请禁用平台 auth。

环境文件

本地 env 文件是可选的。当项目目录中存在 .env 或 .env.* 文件时，部署会打包其环境变量。

当存在多个 env 文件时，CLI 会提示你选择一个。要以非交互方式选择，请传入 --env-file：

mastra deploy --env-file .env.production --yes

要在 production 和 staging 之间运行同一代码库，请使用 mastra deploy --env。完整模型请参阅环境。

以非交互方式创建新项目

首次运行时，mastra deploy 可以创建项目。当 --project <name> 与现有项目不匹配时，CLI 会将该值视为新项目名称，并在确认后创建它。添加 --yes 可使此流程完全可脚本化：

mastra deploy --project "my-new-project" --yes

在 CI 或 AI coding agents 中使用此方式，而不是仅支持交互的 mastra studio projects create。

自托管 Studio

要在自己的基础设施上部署 Studio，请参阅 Studio 部署。

相关内容

• mastra deploy