Mastra 云端部署与可观测性架构解析Deploy → Token → Traces → Storage 全链路实战【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读当你在 Mastra 平台上部署一个 Studio 或 Server 时背后运行着一条完整的数据流水线CLI 将项目推送到平台服务、平台为本次部署签发 JWT、运行中的部署携带该令牌持续上报 traces、最终这些可观测数据被持久化并在 Studio 的 Observability 界面中实时可查。本文以仓库内 架构说明文档 为主体结合 云端部署参考、traces 测试参考 以及deployers/cloud与observability/mastra的源码实现带你完整掌握这四步流水线的原理、部署命令、令牌刷新策略与 trace 验证方法能够独立完成一次从本地代码到云端部署再到观测数据落库的端到端验证。一、四步架构总览部署一个实例后发生了什么根据 architecture.md 的 High-Level Summary当你把 Studio 或 Server 部署到 Mastra 平台时系统依次完成四件事Deploy部署CLI 把你的项目代码发送到平台服务由平台侧构建、打包并生成运行实例。Token签发令牌平台为本次部署签名一个 JWT作为该部署的身份凭证。Traces上报追踪你的部署运行时使用这个 token 向可观测性服务持续上报 tracesspan、日志、指标、评分、反馈。Storage持久化存储traces 被存储下来并能在 Studio UI 中查询、筛选与查看详情。这四步是一个闭环没有部署就没有令牌没有令牌就没有 trace 上报没有上报就没有可观测数据。因此对测试人员而言架构说明给出的关键测试要点是Studio 和 Server 两种部署都会产生 tracestraces 应出现在 Studio 的 Observability可观测性标签页中如果 traces 没有出现应优先检查部署日志中的警告信息。从源码角度看这四步流水线并非抽象概念。在 deployers/cloud/src/index.ts 中CloudDeployer的getEntry()方法生成的运行时入口会读取TEAM_ID、PROJECT_ID、BUILD_ID等构建元数据并打印 READINESS 日志而 observability/mastra/src/exporters/mastra-platform.ts 中的MastraPlatformExporter正是 trace 上报链路的实现核心——它通过MASTRA_CLOUD_ACCESS_TOKEN或MASTRA_PLATFORM_ACCESS_TOKEN环境变量获取 access token向 traces/logs/metrics/scores/feedback 五个信号端点批量 POST 数据。这就解释了为什么token 缺失会直接导致 trace 流水线失效。二、令牌Token在链路中的角色认证与上报的基础2.1 平台签发的 JWT部署完成后平台会为你的部署签名一个 JWT。这个令牌在运行时被注入到容器的环境变量中最核心的两个是环境变量作用MASTRA_CLOUD_ACCESS_TOKENJWT用于 trace 上报时的身份认证MASTRA_CLOUD_TRACES_ENDPOINTtraces 上报的目标端点这两个变量由平台在部署时自动注入开发者无需手动设置。在 environment-variables.md 中它们被明确列为Variables Set Automatically。从 mastra-platform.ts 的构造函数可以看到令牌与端点的解析顺序const accessToken config.accessToken || process.env.MASTRA_PLATFORM_ACCESS_TOKEN || process.env.MASTRA_CLOUD_ACCESS_TOKEN; // ... const tracesEndpointOverride config.tracesEndpoint ?? (process.env.MASTRA_CLOUD_TRACES_ENDPOINT || process.env.MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT || undefined);也就是说MASTRA_CLOUD_TRACES_ENDPOINT是旧版命名MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT是文档化的新版覆盖变量若两者都为空则回退到默认基础端点https://observability.mastra.ai。如果 access token 缺失导出器会直接进入 disabled 状态源码见 mastra-platform.ts并记录MASTRA_PLATFORM_ACCESS_TOKEN environment variable not set.的调试日志——这正是部署日志中 mastra-cloud-observability-exporter disabled 警告的由来。2.2 本地上报端点的形态MastraPlatformExporter会根据是否携带projectId构建不同的发布路径见 mastra-platform.ts无 projectId/ai/{signal}/publish如/ai/spans/publish有 projectId/projects/{projectId}/ai/{signal}/publish五个信号traces/logs/metrics/scores/feedback的端点后缀分别对应/spans/publish、/logs/publish、/metrics/publish、/scores/publish、/feedback/publish。批次上传具备三个可调参数maxBatchSize默认 1000 条、maxBatchWaitMs默认 5000ms、maxRetries默认 3 次。当满足缓冲区达到 1000 条或距首个事件超过 5 秒任一条件时即触发 flush见 shouldFlush。三、部署DeployStudio 与 Server 的云端发布3.1 多环境配置架构说明强调Studio 和 Server 两种部署都会产生 traces。实操中同一个项目可以通过两个独立的配置文件分别部署到 staging 与 production两者拥有各自的 project ID互不干扰环境配置文件平台 API 地址Studio 部署地址Server 部署地址Production.mastra-project.jsonhttps://platform.mastra.aiproject.studio.mastra.cloudproject.server.mastra.cloudStaging.mastra-project-staging.jsonhttps://platform.staging.mastra.aiproject.studio.staging.mastra.cloudproject.server.staging.mastra.cloud部署前需根据目标环境设置平台地址# 生产环境 export MASTRA_PLATFORM_API_URLhttps://platform.mastra.ai # 预发布环境 export MASTRA_PLATFORM_API_URLhttps://platform.staging.mastra.ai同时确保.env中存在对应的 LLM API KeyOpenAI 用OPENAI_API_KEYAnthropic 用ANTHROPIC_API_KEYGroq 用GROQ_API_KEYGoogle 用GOOGLE_GENERATIVE_AI_API_KEY。3.2 部署命令# 部署 Studio生产环境默认使用 .mastra-project.json pnpx mastralatest studio deploy -y # 部署 Studiostaging指定配置文件 pnpx mastralatest studio deploy --config .mastra-project-staging.json -y # 部署 Server生产环境 pnpx mastralatest server deploy -y # 部署 Serverstaging pnpx mastralatest server deploy --config .mastra-project-staging.json -y-y标志表示自动确认设置。部署完成后从输出中记录实际 URL并依次做健康检查# Staging curl https://project.server.staging.mastra.cloud/health # Production无环境子域名 curl https://project.server.mastra.cloud/health # 预期返回{success:true}从源码看Studio 与 Server 在构建期就有明确分工CloudDeployer构造函数接收{ studio?: boolean }参数见 deployers/cloud/src/index.ts当studio: true时会在prepare()阶段把dist/studio静态资源复制进产物目录而在生成运行时入口时createNodeServer(mastra, { studio: ... })决定了是否挂载 Studio 前端。另外云端部署强制externals: true见 deployers/cloud/src/index.ts即依赖全部从 npm 安装到 node_modules避免内联打包引发循环模块求值死锁。3.3 使用脚本快速验证 Server API仓库提供了现成的验证脚本 .claude/skills/mastra-smoke-test/scripts/test-server.sh它会依次完成依赖检查curl/jq→/health健康检查 → 调用/api/agents/agent-id/generate→ 解析并展示响应 → 失败时以非零码退出。.claude/skills/mastra-smoke-test/scripts/test-server.sh server-url [agent-id] [message] # 示例 .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.staging.mastra.cloud .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.mastra.cloud weather-agent Weather in Tokyo?脚本内部使用jq安全构造 JSON 请求体调用POST /api/agents/weather-agent/generate请求体形如{messages:[{role:user,content:What is the weather in Paris?}]}3.4 平台认证登录、校验与刷新云端部署的前提是已登录平台。凭据保存在~/.mastra/credentials.json中结构如下{ token: eyJhbG..., refreshToken: eyJhbG..., user: { id: ..., email: ... }, organizationId: org_01KN..., currentOrgId: org_01KN... }重要WorkOS 签发的 access token 有效期只有5 分钟但可以借助 refresh token 免重新登录直接刷新# 检查现有凭据 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.email # token 过期时刷新无需重新登录 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\}只有刷新也失败时才需要重新走浏览器 OAuth 登录pnpx mastralatest auth logout # 可选清理状态 pnpx mastralatest auth login # ⚠️ 会打开浏览器执行前务必先告知用户登录后必须再次校验组织身份cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}因为浏览器默认登录的可能是另一个账号或组织。四、Traces如何验证全链路是否打通4.1 判定 trace 来源架构文档指出Studio 和 Server 部署都会产生 traces而验证的关键在于能区分两者来源产生方式识别特征Studio tracesStudio UI 交互聊天、工具调用、工作流运行来自 Studio 域名带requestContext已认证用户信息Server traces直接调用已部署 Server 的 API来自 Server 域名requestContext为 null判断标准很简单两者都应出现在 Studio 的 Traces 页面。如果只有 Studio traces 而没有 Server traces说明 trace 流水线存在问题。4.2 生成并验证 Server trace先通过 curl 触发一次 Server 调用curl -X POST server-url/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:Weather in Paris?}]}然后回到 Studio UI →Observability → Traces刷新页面确认刚才的 Server API 调用是否生成了一条新 trace。4.3 本地与云端的 trace 存储差异本地--env localtraces 存储在内存中MastraStorageExporter只在 dev server 运行期间有效重启即丢失因此 trace 测试必须在同一 dev server 会话内与 agent/tool/workflow 测试一起进行。云端staging/productiontraces 发送到云端 collector跨会话持久化。本地可通过无鉴权的/api/observability/traces端点直接查询# 列出最近 spans响应结构{ pagination, spans } curl -s http://localhost:4111/api/observability/traces?page0perPage20 | jq . # 按 traceId 查询单条 trace curl -s http://localhost:4111/api/observability/traces/traceId | jq . # 快速通过标准分页统计 span 类型聚合 curl -s http://localhost:4111/api/observability/traces?page0perPage100 | \ jq {total: .pagination.total, byType: ([.spans[].spanType] | group_by(.) | map({t: .[0], n: length}))}注意响应形状GET /api/observability/traces返回的是{ pagination: { total, page, perPage, hasMore }, spans: [...] }既不是裸数组也没有traces键。每条 span 包含spanType取值如agent_run、tool_call、workflow_run、scorer_run、traceId、时间戳和 payload。本地通过标准是运行过 agent/tool/workflow 测试后pagination.total 0且spans中出现预期的agent_run、workflow_run、scorer_run若 agent 调用了工具还应出现tool_call。4.4 云端直连 trace API如果 Studio UI 中看不到 trace可以绕过 UI 直接验证流水线。查询端点为环境Mobs-Query URLProductionhttps://mobs-query-vgvrl5lbxq-uc.a.run.appStaginghttps://mobs-query-pvyw2kfhjq-uc.a.run.app鉴于 5 分钟 token 有效期仓库文档提供了一个完整的get_valid_token自动刷新辅助函数见 references/tests/traces.md先尝试当前 token 调用/v1/auth/verify失败则用 refresh token 调用/v1/auth/refresh-token成功后原子更新~/.mastra/credentials.json。TOKEN$(get_valid_token https://platform.mastra.ai) || exit 1 PROJECT_ID$(jq -r .projectId .mastra-project.json) # 或 .mastra-project-staging.json ORG_ID$(jq -r .organizationId .mastra-project.json) curl -s https://mobs-query-vgvrl5lbxq-uc.a.run.app/api/observability/traces?page0perPage10resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .云端 trace 响应结构示例{ pagination: { total: 10, page: 0, perPage: 10, hasMore: false }, traces: [ { traceId: 37f0d68d760887e994135c984ebd7b89, name: agent run: weather-agent, spanType: agent_run, startedAt: 2026-04-08T15:29:27.123Z, endedAt: 2026-04-08T15:29:30.456Z, metadata: { buildId: ..., runId: ... }, requestContext: { user: { id: ..., email: ... } }, status: success } ] }关键字段说明字段说明metadata.buildId部署 ID区分来自 Studio 还是 ServerrequestContextStudio traces 有值已认证Server traces 为 nullspanTypeagent_run、tool_call、workflow_run等statussuccess、error、running支持按时间范围、resourceId项目、runId三种维度过滤# 按时间范围URL 编码的 JSON curl -s ...?startedAt%7B%22start%22%3A%222026-04-08T15%3A00%3A00.000Z%22%7D ... # 按资源 ID项目 curl -s ...?resourceId$PROJECT_ID ... # 按运行 ID curl -s ...?runId$RUN_ID ...4.5 浏览器侧验证清单Navigate to: /observability Wait: For traces to load Verify: At least one trace visible Click: On a trace row Verify: Details panel shows input/output # Cloud only: Execute: curl command to server Navigate to: /observability Click: Refresh or wait Verify: New server trace appears五、常见故障与排障路径5.1 部署日志中的关键警告排障的首要动作是查看部署日志。从 deployers/cloud/src/index.ts 可以看到运行时启动阶段会以 READINESS 类型打印Server starting随后在createNodeServer与初始化完成后分别打印Server started与Runner Initialized均携带teamId、projectId、buildId元数据——这些是定位部署/构建问题的时间线依据。5.2 分类故障表症状可能原因处理方式完全没有 tracesOTel 未配置检查 mastra 配置中的telemetry设置只有 Studio tracesServer token 问题重新部署 ServerStudio 中 Something went wrong认证/会话问题在 Studio 中重新认证部署日志出现CLOUD_EXPORTER警告缺少 token基础设施问题记录即可Server traces 不出现collector 或 JWT 问题见下方 mobs-collector 排查401 invalid signature服务间JWT_SECRET不一致核对各服务 JWT_SECRET 配置mastra-cloud-observability-exporter disabled平台 API 未配置JWT_SECRETServer 拿不到MASTRA_CLOUD_ACCESS_TOKEN在平台 API 侧配置 JWT_SECRET 后重新部署5.3 mobs-collector 日志解读在 GCP Console 中检查mobs-collector日志通过 POST 状态码快速定位POST 200 traces 已成功接收POST 401 JWT 认证失败token 无效或过期POST 404 端点错误路径不对5.4 其他高频问题登录后组织不对浏览器可能默认登录了另一个账号/组织登录后务必用cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}验证。token 过期401WorkOS token 5 分钟过期先检查有效性优先用 refresh token 刷新而非重新登录。Studio Session expired已知的 cookie 域名不匹配问题Studio 可能需要周期性重新认证。自定义路由不生效Server 配置中自定义路由必须用apiRoutes而不是routes后者会静默失败server: { apiRoutes: [helloRoute], // ✅ 正确 // routes: [helloRoute], // ❌ 错误写法路由不会注册 }CORS 错误Server 部署通过SERVER_WRAPPER注入 CORS 配置。检查部署上的MASTRA_CORS_ORIGIN环境变量是否设置正确以及来源域名是否匹配 Studio 域名模式。部署时认证失败执行pnpx mastralatest auth logout后重新auth login再重试部署。六、完整命令速查# 环境 export MASTRA_PLATFORM_API_URLhttps://platform.mastra.ai # production export MASTRA_PLATFORM_API_URLhttps://platform.staging.mastra.ai # staging # 认证login 会打开浏览器执行前务必告知用户 pnpx mastralatest auth login pnpx mastralatest auth logout # 部署production pnpx mastralatest studio deploy -y pnpx mastralatest server deploy -y # 部署staging 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 # production curl https://project.server.staging.mastra.cloud/health # staging # Agent 调用 curl -X POST server-url/api/agents/agent-id/generate \ -H Content-Type: application/json \ -d {messages: [{role: user, content: Hello}]} # 直接查询云端 traces TOKEN$(get_valid_token) # 见 references/tests/traces.md 中的辅助函数 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结语Mastra 云端架构的Deploy → Token → Traces → Storage四步流水线本质是一套以 JWT 为身份凭证、以 OpenTelemetry 风格信号为数据载体、以云端 collector 为存储后端的可观测性闭环。理解它你就能在 smoke test 中精准定位问题边界部署日志负责确认前两步构建与令牌注入/observability页面与 mobs-query API 负责验证后两步上报与存储。需要深入云端基础设施级排障时可进一步阅读 gcp-debugging.md 与 cloud-advanced.md并对照 observability/mastra 源码目录 理解导出器的批次、重试与配额暂停机制。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考