Studio 部署

Studio 是一个基于 React 的单页应用（SPA），在浏览器中运行，并连接到正在运行的 Mastra 服务器。

你可以通过两种主要方式部署 Studio：

• Mastra platform 为你提供托管的 Studio，并允许你通过链接与团队共享访问权限
• 在你自己的基础设施上自托管 Studio，既可以与 Mastra 服务器一起部署，也可以作为独立的 SPA 单独部署

本页介绍如何在你自己的基础设施上部署 Studio。由于部署的具体细节会因你的需求和环境而有很大差异，我们将涵盖一般原则和可用选项。

快速开始

运行 Studio 最简单的方式是 mastra studio 命令。

mastra dev 会同时运行 Studio 和一个用于开发的 API，而 mastra studio 的用途是提供一个独立的静态 UI，连接到一个已经运行的 Mastra 服务器。你可以将 Studio 与 Mastra 服务器分开部署。

打开终端并全局安装 mastra CLI：

npm

npm install -g mastra

pnpm

pnpm add -g mastra

Yarn

yarn global add mastra

Bun

bun add --global mastra

运行 mastra studio 命令：

mastra studio

在浏览器中打开 localhost:3000 查看 Studio UI。默认情况下，它会连接到 http://localhost:4111 上的 Mastra 服务器；当没有可用服务器时，UI 会显示一个表单，用于输入你的 Mastra 实例 URL 和 API 前缀。

该命令使用 Node 内置的 http 模块和 serve-handler 来提供静态文件。

备注

如果你将 Studio 托管在子路径下（例如位于 Nginx 后面的 /agents），请在启动 Studio 之前设置 MASTRA_STUDIO_BASE_PATH：

MASTRA_STUDIO_BASE_PATH=/agents mastra studio

这会更新 HTML base URL 和静态资源路由，使独立 Studio 在该子路径下正常工作。

Mastra platform

关于 Mastra platform 上的托管 Studio，参见 Mastra platform 上的 Studio。

运行服务器

将 mastra studio 作为长时间运行的进程运行，与运行任何其他 Node.js 服务没有区别。相同的部署实践和工具在这里同样适用。使用 PM2 或 Docker 之类的进程管理器。支持 Node.js 应用的云服务也是另一个选项。与任何 Web 服务一样，请正确配置 CORS 并监控错误。

注意

一旦 Studio 连接到你的 Mastra 服务器，它就拥有对你的 agents、workflows 和 tools 的完全访问权限。请务必在生产环境中妥善保护它（例如置于认证、VPN 等之后），以防止未授权访问。

访问认证文档了解更多信息。

与 API 一起部署

或者，你可以将 Studio 与 Mastra 服务器一起提供。这样你只需要部署和管理一个服务。

为此，使用 --studio 标志运行 mastra build：

mastra build --studio

它会创建一个包含构建后 Studio 资源的 .mastra/output/studio 文件夹。通过定义 MASTRA_STUDIO_PATH 环境变量，Mastra 服务器也可以提供 Studio UI 的访问：

MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs

使用 CDN

自动方式

一些云提供方提供了将 Studio 与你的无服务器函数一起部署的选项。目前支持以下提供方：

• VercelDeployer

手动方式

你不能直接将构建后的 Studio 资源部署到 CDN，因为 UI 依赖一些运行时配置。通过一些额外设置，你可以从构建后的资源创建一个独立的 SPA，并将其部署到任何静态托管服务。

按照下面的示例使用 Vite 创建一个 SPA。

1. 创建一个新文件夹并初始化一个新的 Node.js 项目：

   npm

   mkdir studio-spa
   cd studio-spa
   npm init

   pnpm

   mkdir studio-spa
   cd studio-spa
   pnpm init

   Yarn

   mkdir studio-spa
   cd studio-spa
   yarn init

   Bun

   mkdir studio-spa
   cd studio-spa
   bun init

2. 安装 vite 和 mastra 作为依赖：

   npm

   npm install vite mastra

   pnpm

   pnpm add vite mastra

   Yarn

   yarn add vite mastra

   Bun

   bun add vite mastra

3. 在 package.json 中添加一个构建脚本：

   package.json

   {
     "scripts": {
       "build": "vite build"
     }
   }

4. 创建一个占位的 index.html 文件：

   index.html

   <!doctype html>
   <html>
     <head></head>
     <body></body>
   </html>

5. 创建一个 vite.config.js 文件。它会将构建后的 Studio 资源复制到 dist 文件夹，并用环境变量值替换 HTML 中的任何 %%PLACEHOLDER%% 值。

   vite.config.js

   import { defineConfig, loadEnv } from 'vite'
   import { readFileSync, cpSync, writeFileSync } from 'node:fs'
   import { resolve, join } from 'node:path'
   
   const studioDir = resolve(import.meta.dirname, 'node_modules/mastra/dist/studio')
   
   export default defineConfig(({ mode }) => {
     const env = loadEnv(mode, process.cwd(), 'MASTRA_')
   
     return {
       plugins: [
         {
           name: 'mastra-studio',
           closeBundle() {
             const outDir = resolve(import.meta.dirname, 'dist')
             cpSync(studioDir, outDir, { recursive: true })
   
             const indexPath = join(outDir, 'index.html')
             const html = readFileSync(indexPath, 'utf-8')
             writeFileSync(
               indexPath,
               html.replaceAll(/%%(\w+)%%/g, (_, key) => env[key] ?? ''),
             )
           },
         },
       ],
       build: {
         emptyOutDir: true,
       },
     }
   })

6. 创建一个包含必要环境变量的 .env 文件。

   .env

   MASTRA_SERVER_HOST=localhost
   MASTRA_SERVER_PORT=4111
   MASTRA_SERVER_PROTOCOL=http
   MASTRA_API_PREFIX=/api
   MASTRA_HIDE_CLOUD_CTA=false
   MASTRA_CLOUD_API_ENDPOINT=
   MASTRA_EXPERIMENTAL_FEATURES=false
   MASTRA_TEMPLATES=false
   MASTRA_TELEMETRY_DISABLED=true
   MASTRA_REQUEST_CONTEXT_PRESETS=
   MASTRA_THEME_TOGGLE=false
   MASTRA_EXPERIMENTAL_UI=false
   MASTRA_STUDIO_BASE_PATH=

7. 运行构建脚本以在 dist 文件夹中生成静态文件：

   npm

   npm run build

   pnpm

   pnpm run build

   Yarn

   yarn build

   Bun

   bun run build

8. 将你的托管提供方指向 dist 文件夹并部署！