Mastra 云端部署完全指南Staging 与 Production 双环境下的 Studio / Server 部署与冒烟测试【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文基于 Mastra 开源仓库中 mastra-smoke-test 技能 的云端部署手册系统讲解如何将同一个 Mastra 项目分别部署到 staging 与 production 两个环境并完成从身份认证、Studio/Server 部署、健康检查、Agent API 调用、链路追踪Traces验证到自定义 API 路由测试的完整冒烟测试闭环。读完本文你将掌握 Mastra 平台多环境部署的完整命令体系、凭证管理与令牌刷新机制、基于 test-server.sh 的自动化验证方法以及一整套可落地的故障排查清单。一、多环境部署架构一个项目两个环境Mastra 支持从同一个项目同时面向 staging 和 production 部署核心手段是为每个环境维护一份独立的配置文件。两份配置各自记录独立的projectId因此两个环境的部署互不干扰。环境配置文件平台 API URL部署域名Production.mastra-project.jsonhttps://platform.mastra.aiproject.studio.mastra.cloud/project.server.mastra.cloudStaging.mastra-project-staging.jsonhttps://platform.staging.mastra.aiproject.studio.staging.mastra.cloud/project.server.staging.mastra.cloud从 CLI 源码可以看到部署命令在成功后会主动把项目元数据写入指定配置文件Saved ${opts.config || .mastra-project.json}见 packages/cli/src/commands/server/deploy.ts这就是多环境隔离的落地机制每个环境对应的配置文件中保存着各自独立的 projectId 与 organizationId。关联阅读本地环境与多环境配置说明 中详细描述了本地localhost:4111、staging、production 三环境的配置矩阵。环境变量切换部署前先通过MASTRA_PLATFORM_API_URL指定目标平台# 生产环境 export MASTRA_PLATFORM_API_URLhttps://platform.mastra.ai # 预发环境 export MASTRA_PLATFORM_API_URLhttps://platform.staging.mastra.ai注意生产环境是默认值即使不设置该变量也能正常工作见 environment-variables.md。LLM API Key 配置确保项目.env中配置了目标 LLM 提供商的密钥提供商环境变量openaiOPENAI_API_KEYanthropicANTHROPIC_API_KEYgroqGROQ_API_KEYgoogleGOOGLE_GENERATIVE_AI_API_KEY二、平台身份认证凭证检查、令牌刷新与登录1. 检查已有凭证在触发浏览器登录之前务必先检查本地是否已存在有效凭证避免无谓的浏览器弹窗# 检查凭证文件是否存在并查看账号与组织 cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId} # 验证 token 是否仍有效 TOKEN$(jq -r .token ~/.mastra/credentials.json) ORG_ID$(jq -r .currentOrgId // .organizationId ~/.mastra/credentials.json) curl -s $MASTRA_PLATFORM_API_URL/v1/auth/verify \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .user.email2. 令牌过期后的刷新优先于重新登录Mastra 平台使用 WorkOS 认证Access Token 有效期仅 5 分钟但可以通过 refresh token 无感续期无需重新走 OAuth 流程REFRESH_TOKEN$(jq -r .refreshToken ~/.mastra/credentials.json) curl -s $MASTRA_PLATFORM_API_URL/v1/auth/refresh-token \ -X POST \ -H Content-Type: application/json \ -d {\refreshToken\: \$REFRESH_TOKEN\}完整封装的get_valid_token辅助函数含“验证 → 尝试刷新 → 写回凭证文件”三段逻辑见 references/tests/traces.md可直接复制到 shell 脚本中使用。3. 登录仅在刷新失败时⚠️ 执行auth login前必须先提醒用户——该命令会打开浏览器跳转 OAuth 流程# 可选先登出以获得干净状态 pnpx mastralatest auth logout # 登录目标环境浏览器 OAuth 完成后自动写回凭证 pnpx mastralatest auth login4. 登录后务必核验组织浏览器可能默认登录到错误的账号/组织登录完成后必须核验cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}三、部署 StudioStudio 是 Mastra 的交互式 UIAgent 聊天、工具调试、工作流可视化、观测页面适用于交互测试与调试# 生产环境默认使用 .mastra-project.json pnpx mastralatest studio deploy -y # 预发环境显式指定配置文件 pnpx mastralatest studio deploy --config .mastra-project-staging.json -y等待部署完成从输出中记录 Studio URL生产https://project.studio.mastra.cloud预发https://project.studio.staging.mastra.cloud验证打开 URL → 登录 → 确认 Studio UI 正常加载、Agent 列表正确展示。首次部署可能耗时 25 分钟后续部署会更快Studio URL 在多次部署间保持稳定。可在projects.mastra.ai生产/projects.staging.mastra.ai预发仪表盘查看全部部署记录。更完整的 Studio 冒烟清单见 references/tests/studio.md。四、部署 ServerServer 是 Mastra 的 API 服务供程序化访问与生产使用。官方推荐的典型流程是先部署 Studio获得 UI再部署 Server获得 API二者可以只部署其一但只有同时部署才能验证 Server 产生的链路追踪是否回流到 Studio。# 生产环境 pnpx mastralatest server deploy -y # 预发环境 pnpx mastralatest server deploy --config .mastra-project-staging.json -y-y标志自动确认所有设置适合 CI/脚本场景。记录输出的 Server URL生产https://project.server.mastra.cloud预发https://project.server.staging.mastra.cloud健康检查# 预发 curl https://project.server.staging.mastra.cloud/health # 生产无环境子域名 curl https://project.server.mastra.cloud/health # 期望返回{success:true}部署时需要特别留意输出中的关键告警对应 references/tests/server.mdmastra-cloud-observability-exporter disabled可观测性导出器被禁用链路追踪将不可用通常是JWT_SECRET未在平台侧配置CLOUD_EXPORTER_FAILED_TO_BATCH_UPLOAD_LOGS追踪上报端点异常。五、调用 Server APItest-server.sh 一键冒烟仓库提供了现成的测试脚本 test-server.sh一条命令即可完成健康检查与 Agent 调用验证.claude/skills/mastra-smoke-test/scripts/test-server.sh server-url [agent-id] [message] # 示例默认 agentweather-agent与默认消息 .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.staging.mastra.cloud # 示例指定 agent 与消息 .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.mastra.cloud weather-agent Weather in Tokyo?脚本执行流程检查/health端点期望 HTTP 200以jq安全构造 JSON 请求体POST 调用 Agent 的/generate端点解析并展示响应文本任一检查失败即以非零码退出适合接入自动化流水线。底层对应的 Agent API 端点一览见 references/tests/server.md端点方法用途/healthGET健康检查/api/agents/id/generatePOSTAgent 生成/api/agents/id/streamPOST流式生成/custom-routeANY自定义 API 路由手动 curl 等价命令curl -X POST server-url/api/agents/agent-id/generate \ -H Content-Type: application/json \ -d {messages: [{role: user, content: Hello}]}冷启动提示Server 冷启动可能耗时 1030 秒部署后首次请求可能较慢超时可等待 30 秒重试。六、验证 Server 链路追踪Traces这是冒烟测试的关键步骤——它验证整条可观测性流水线OTel 采集 → 云 collector → Studio 展示是否打通发起一次 Server API 调用脚本或 curl 均可回到 Studio UI → Observability → Traces 页面刷新页面确认 Server API 调用产生的 trace 出现在列表中。区分 Trace 来源来源识别方式Studio traces由 Studio UI 交互聊天、工具调用产生Server traces由对已部署 Server 的直接 API 调用产生两者都应出现在 Studio 的 Traces 页面。如果只有 Studio traces 而没有 Server traces说明追踪管道存在问题。从 traces 响应结构看见 references/tests/traces.md可以通过以下字段区分来源与状态metadata.buildId部署 ID标识 Studio 或 Server 的部署requestContextStudio traces 为已认证用户对象Server traces 为 nullspanTypeagent_run、tool_call、workflow_run、scorer_run等statussuccess、error、running。直接查询 Trace 管道UI 不可用时当 UI 不显示 traces 但需要验证管道时可直连观测查询服务TOKEN$(jq -r .token ~/.mastra/credentials.json) PROJECT_ID$(jq -r .projectId .mastra-project.json) ORG_ID$(jq -r .organizationId .mastra-project.json) curl -s https://mobs-query-vgvrl5lbxq-uc.a.run.app/api/observability/traces?resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .traces | length生产/预发环境对应的查询地址分别为https://mobs-query-vgvrl5lbxq-uc.a.run.app与https://mobs-query-pvyw2kfhjq-uc.a.run.app。生产环境 traces 通常需要 30 秒内可见若持续缺失考虑重新部署。七、测试自定义 API 路由部署后Mastra 通过registerApiRoute注册自定义路由见 packages/core/src/server/index.ts注册选项包括method、handler/createHandler、middleware、cors、requiresAuth、requiresPermission、fga等其中method为必填handler与createHandler二选一。部署含自定义路由的 Server 后# 预发 curl https://project.server.staging.mastra.cloud/hello # 生产 curl https://project.server.mastra.cloud/hello # 期望返回{message:Hello from custom route!}路由定义与注册示例详见 references/tests/setup.md// src/mastra/routes/hello.ts import { registerApiRoute } from mastra/core/server; export const helloRoute registerApiRoute(/hello, { method: GET, requiresAuth: false, // 需要认证时设为 true handler: async c { return c.json({ message: Hello from custom route! }); }, });// src/mastra/index.ts export const mastra new Mastra({ // ... server: { apiRoutes: [helloRoute], // ⚠️ 必须是 apiRoutes不是 routes }, });高频坑误写成routes会导致路由静默失效且构建不报错。修改配置后务必运行pnpm tsc --noEmit做类型检查构建过程不会做类型校验。八、浏览器 Agent 的云端部署注意事项在部署环境中测试浏览器 Agent如基于 Stagehand时需注意将浏览器配置为headless: true浏览器运行在部署容器的服务端不依赖本地浏览器。另外为 Agent 绑定StagehandBrowser会自动挂载BrowserContextProcessor输入处理器它通过 Mastra memory 读写浏览器状态因此每次调用都必须同时提供 thread 与 resource ID否则会抛出computeStateSignal requires Mastra memory with an active resourceId and threadId详细示例见 references/tests/setup.md。九、快速命令速查表# 环境切换 export MASTRA_PLATFORM_API_URLhttps://platform.mastra.ai # 生产 export MASTRA_PLATFORM_API_URLhttps://platform.staging.mastra.ai # 预发 # 认证login 前务必提醒用户——会打开浏览器 pnpx mastralatest auth login pnpx mastralatest auth logout # 部署生产 pnpx mastralatest studio deploy -y pnpx mastralatest server deploy -y # 部署预发 pnpx mastralatest studio deploy --config .mastra-project-staging.json -y pnpx mastralatest server deploy --config .mastra-project-staging.json -y # 测试使用部署输出中的真实 URL curl https://project.server.mastra.cloud/health # 生产 curl https://project.server.staging.mastra.cloud/health # 预发 # Agent 调用 curl -X POST server-url/api/agents/agent-id/generate \ -H Content-Type: application/json \ -d {messages: [{role: user, content: Hello}]} # 直接检查 traces TOKEN$(jq -r .token ~/.mastra/credentials.json) PROJECT_ID$(jq -r .projectId .mastra-project.json) ORG_ID$(jq -r .organizationId .mastra-project.json) curl -s https://mobs-query-vgvrl5lbxq-uc.a.run.app/api/observability/traces?resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .traces | length十、故障排查手册1. 登录后组织不对浏览器可能默认登录到错误的账号/组织。登录后立即核验cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}2. Token 过期401 错误WorkOS token 有效期 5 分钟。遇到 401先检查 token 有效性并优先使用 refresh token 续期不要急着重新登录。可直接复用 references/tests/traces.md 中的get_valid_token辅助函数。3. Studio 中出现 Session expired已知的 cookie 域名不匹配问题Studio 需要周期性重新认证。4. 自定义路由不生效自定义路由必须使用server.apiRoutes而非routesserver: { apiRoutes: [helloRoute], // ✅ 正确 // routes: [helloRoute], // ❌ 错误——静默失败 }这是导致路由“无声无息不注册”的常见笔误。5. CORS 错误Server 部署通过SERVER_WRAPPER注入 CORS 配置。遇到 CORS 错误时检查部署上的MASTRA_CORS_ORIGIN环境变量是否设置正确确认来源域名与 Studio 域名模式匹配。6. Server traces 不出现按顺序排查检查mobs-collector日志GCP ConsolePOST 200 已收到 tracesPOST 401 JWT 认证失败POST 404 端点错误。若出现401 invalid signature是服务间JWT_SECRET不匹配。若部署日志出现mastra-cloud-observability-exporter disabledJWT_SECRET未在 platform-api 上配置Server 无法获取MASTRA_CLOUD_ACCESS_TOKEN。详细的 GCP 日志排查步骤含何时该查日志、需要哪些访问权限、联系谁见 gcp-debugging.md。7. 部署时认证失败pnpx mastralatest auth logout pnpx mastralatest auth login然后重试部署。附常用关联文档索引多环境项目搭建与验证清单Studio 部署冒烟清单Server 部署冒烟清单Traces 验证与令牌刷新辅助函数环境变量参考云端进阶测试BYOK 与存储后端Server 测试脚本【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考