Mastra Cloud 部署 GCP 调试指南从云日志定位 Trace 丢失、静默失败与认证会话问题【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra适用场景当 Mastra 项目部署到 Cloudstaging/production后出现 Server 端 Trace 不显示、部署静默失败、认证与会话异常等难以在应用层定位的问题时需要进入 GCP Console 查看基础设施日志进行排查。本文以仓库内mastra-smoke-testskill 的 gcp-debugging.md 为骨架结合同目录下的 cloud-deploy.md、common-errors.md、architecture.md 与 tests/traces.md 展开给出可直接落地的排查路径。内部文档声明本文涉及的 GCP 调试需要 GCP Console 访问权限。如果你没有对应项目staging 或 production的基础设施访问权限请联系拥有基础设施访问权限的平台团队成员协助排查。什么时候需要检查 GCP 日志GCP 日志Cloud Logging是 Mastra Cloud 部署排障的最后一层证据。当应用层手段重启 dev server、重新部署、重新登录、查看 Studio 页面报错都无法解释问题时就应当下沉到基础设施层看日志。根据原文档的 Quick Reference以下三类典型症状应优先进入 GCP 排查症状典型表现说明Server 端 Trace 不在 Studio 显示Studio 自身的 Trace 正常但通过 Server API 发起的调用产生的 Trace 缺失通常是 trace 管道collector/exporter/认证问题而非 Studio 前端问题部署静默失败mastra server deploy/studio deploy无报错或报错不明确但服务不可用、URL 打不开需要核对部署产物、容器启动日志与平台侧状态认证 / 会话问题Studio 反复出现 Session expired、登录后立即失效、401 响应涉及 JWT 签名密钥、token 刷新与 cookie domain 配置对照 cloud-deploy.md 的排查清单Server traces not appearing是唯一一个明确要求查看 GCP Console 中mobs-collector日志的场景这也是本文最核心的实战入口。调试前需要准备什么GCP Console 访问权限需要能访问对应环境staging 或 production的 GCP 项目。原文档明确指出这是内部能力权限不足时应联系平台团队。识别要查哪个服务根据症状定位到具体的 Cloud Run 服务 / 日志流而不是盲目浏览整个项目。Mastra Cloud 部署涉及的核心服务如下表依据 architecture.md 与 cloud-deploy.md 整理服务 / 组件在 trace 管道中的职责部署后的 Studio / ServerCloud Run 服务运行你的 Mastra 应用Server 以 JWT 签名身份上报 tracemobs-collector接收并校验各部署实例上报的 trace重点排查对象mobs-query存储层之上的查询服务Studio Observability 页读取 trace 的后端Cloud Run URL 见下文platform-api签发 JWT、下发MASTRA_CLOUD_ACCESS_TOKEN负责认证与授权关于查哪个服务如果症状是Server trace 不上报第一优先查看mobs-collector的日志如果症状是Studio 页面读不到 trace则要顺带确认mobs-query是否可访问、token 是否有效。理解 GCP 调试在整体架构中的位置在进入日志细节之前先建立整体心智模型。根据 architecture.md 的 High-Level Summary一次成功的 Mastra Cloud 部署 trace 流水线是DeployCLIpnpx mastralatest studio deploy/server deploy将项目上传到平台服务Token平台为本次部署签发 JWTMASTRA_CLOUD_ACCESS_TOKEN部署实例持此身份上报数据Traces部署实例Studio 与 Server 均会把 trace 发送到云侧 collector即mobs-collectorStoragetrace 落库后Studio Observability 页可查询展示。因此GCP 日志排查的本质是逐段验证这条链路Server 是否成功获得 token → Server 是否真的发出了 trace → collector 是否接收成功HTTP 状态码→ 查询服务是否返回数据。核心实战通过 mobs-collector 日志定位 Trace 管道问题这是本文最重要的一节。依据 cloud-deploy.md当 Server trace 不出现时按如下步骤操作在 GCP Console 打开mobs-collector服务的日志发起一次 Server API 调用例如curl -X POST https://project.server.mastra.cloud/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:Weather in Paris?}]}观察 collector 日志中对应的 POST 请求状态码并按状态码分流collector 日志状态码含义下一步POST 200trace 已接收管道正常问题不在 collector去查mobs-query/ Studio 查询侧POST 401JWT 认证失败检查签名密钥是否一致见下一节POST 404上报端点错误检查 exporter 配置的 endpoint 是否正确注意这一步的验证对象是独立于 Studio UI 的。依据 cloud-deploy.md 的 Server Trace Verification 小节Studio Trace来自 UI 交互与 Server Trace来自对部署后 Server 的直接 API 调用是两个独立来源若只有 Studio trace 出现而 Server trace 缺失基本可以断定是 Server 侧的 token 或 exporter 问题这正是 GCP 日志排查的典型目标。JWT_SECRET 与 MASTRA_CLOUD_ACCESS_TOKEN认证链路的两个关键变量在 collector 日志中看到401 invalid signature或部署日志出现mastra-cloud-observability-exporter disabled时问题几乎都出在认证链路。依据 cloud-deploy.md401 invalid signature说明JWT_SECRET在相关服务如 platform-api 与 collector之间不一致导致签名校验失败。JWT 是服务间互信凭证密钥错配会让所有上报请求被拒。mastra-cloud-observability-exporter disabled部署日志中出现说明JWT_SECRET未在 platform-api 上配置导致 Server 无法获取MASTRA_CLOUD_ACCESS_TOKEN。没有 tokenServer 的观测 exporter 干脆不启动——这就是Server trace 一条都没有的根因。排查动作需 GCP 访问权限在相应服务的环境变量/Secret 配置中核对确认 platform-api 与 collector 的JWT_SECRET取值一致确认 Server 部署环境能正常获取MASTRA_CLOUD_ACCESS_TOKEN修正后重新部署 Serverpnpx mastralatest server deploy -y-y自动确认配置来自 cloud-deploy.md回到 collector 日志确认 POST 状态码从401变为200。补充本地与云上的 trace 机制不同见 tests/traces.md 的 Local vs Cloud 小节。本地 trace 存在内存中MastraStorageExporterdev server 重启即消失云上 trace 发送到 collector 并持久化。因此 JWT 类问题只出现在云部署场景本地排障不需要进入 GCP。绕过 UI 直接验证观测数据mobs-query 端点当 Studio 页面读不到 trace但你想先确认数据到底有没有进来时可以直接调用云侧查询服务mobs-query把 UI 层排除在外。依据 tests/traces.md 的 Direct Trace API (Cloud Only) 小节环境mobs-query 端点Productionhttps://mobs-query-vgvrl5lbxq-uc.a.run.appStaginghttps://mobs-query-pvyw2kfhjq-uc.a.run.app查询需要有效的访问 token。登录后凭据保存在~/.mastra/credentials.json其中token有效期仅5 分钟WorkOS 签发refreshToken长期有效。推荐使用文档中的get_valid_token辅助函数自动完成验证 → 刷新 → 回写凭据get_valid_token() { local PLATFORM_URL${1:-https://platform.mastra.ai} local TOKEN$(jq -r .token ~/.mastra/credentials.json) local ORG_ID$(jq -r .currentOrgId // .organizationId ~/.mastra/credentials.json) # Try current token local VERIFY$(curl -s $PLATFORM_URL/v1/auth/verify \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID) if echo $VERIFY | jq -e .user /dev/null 21; then echo $TOKEN return 0 fi # Token expired — try refresh local REFRESH_TOKEN$(jq -r .refreshToken ~/.mastra/credentials.json) if [ -z $REFRESH_TOKEN ] || [ $REFRESH_TOKEN null ]; then echo No refresh token. Re-login required. 2 return 1 fi local REFRESH_RESULT$(curl -s $PLATFORM_URL/v1/auth/refresh-token \ -X POST \ -H Content-Type: application/json \ -d {\refreshToken\: \$REFRESH_TOKEN\}) if echo $REFRESH_RESULT | jq -e .accessToken /dev/null 21; then local NEW_TOKEN$(echo $REFRESH_RESULT | jq -r .accessToken) local NEW_REFRESH$(echo $REFRESH_RESULT | jq -r .refreshToken) # Update credentials file jq --arg t $NEW_TOKEN --arg r $NEW_REFRESH \ .token $t | .refreshToken $r \ ~/.mastra/credentials.json ~/.mastra/credentials.json.tmp \ mv ~/.mastra/credentials.json.tmp ~/.mastra/credentials.json echo $NEW_TOKEN return 0 fi echo Refresh failed. Re-login required. 2 return 1 }然后按环境查询projectId / organizationId 从.mastra-project.json或.mastra-project-staging.json读取PROJECT_ID$(jq -r .projectId .mastra-project.json) ORG_ID$(jq -r .organizationId .mastra-project.json) TOKEN$(get_valid_token https://platform.mastra.ai) # Production 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 . # Staging TOKEN$(get_valid_token https://platform.staging.mastra.ai) curl -s https://mobs-query-pvyw2kfhjq-uc.a.run.app/api/observability/traces?page0perPage10resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .查询结果的字段含义tests/traces.md字段说明metadata.buildId部署 ID可区分 trace 来自 Studio 还是 ServerrequestContextStudio trace 为认证用户上下文Server trace 通常为 nullspanTypeagent_run、tool_call、workflow_run等statussuccess、error、running技巧通过metadata.buildId与requestContext即可在接口层面直接区分Server trace 有没有进来。若接口返回 Server 的 trace 而 Studio 页面不显示问题在 Studio 查询/渲染侧若接口也没有 Server trace则问题在采集侧回到 collector 日志排查。认证与会话问题的 GCP 侧排查原文档将认证/会话问题列为需要查 GCP 日志的第三类症状。结合 cloud-deploy.md 的 Troubleshooting 与 common-errors.md这类问题需要区分几个层面Token 过期401WorkOS token 5 分钟过期这属于预期行为不应视为故障。处理顺序是先用 refresh token 刷新见上文get_valid_token刷新失败才重新登录pnpx mastralatest auth logout # 清理状态可选 pnpx mastralatest auth login # ⚠️ 会打开浏览器走 OAuth先告知用户登录后务必核对组织是否正确浏览器可能默认到别的账号/组织cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}Studio 反复 Session expired已知的 cookie domain 不匹配问题Studio 可能需要周期性重新认证。这类问题在业务日志中往往表现为认证中间件拒绝会话可在对应部署服务的日志流中确认 401 出现频率与触发路径。401 invalid signature服务间与用户登录无关属于上文 JWT_SECRET 错配问题需在 GCP 侧核对服务密钥配置。部署静默失败的排查要点部署失败但无明确报错是第二类需要查 GCP 的症状。结合 common-errors.md 的 Deploy Issues 小节症状可能原因快速修复部署挂起/超时网络或平台侧问题到平台 Dashboard 确认部署是否实际成功然后重试Cannot determine project name项目根目录缺少 package.json在包含有效 package.json 的项目根目录执行部署对于部署挂起GCP 侧重点看 Cloud Run 服务的启动日志容器是否成功启动、健康检查/health是否通过、环境变量如MASTRA_CORS_ORIGIN、JWT_SECRET是否注入正确。部署成功的 Server 应能通过健康检查# Staging curl https://project.server.staging.mastra.cloud/health # Production无环境子域名 curl https://project.server.mastra.cloud/health # 预期返回: {success:true}另外注意 cloud-deploy.md 中一个静默失败的经典坑自定义路由必须写在server.apiRoutes而不是server.routes后者不会报错但路由不会注册——这类问题用/health无法发现需要直接请求自定义路由验证例如curl https://project.server.mastra.cloud/hello若返回 404 则属于配置问题而非基础设施问题。何时升级给平台团队GCP 调试属于内部基础设施能力原文档明确给出了升级边界。以下情况应停止自行排查联系平台团队common-errors.md 的 When to Escalate重新部署后 trace 问题依旧存在部署日志中持续出现401或404问题在多个项目间复现说明不是单项目配置问题而是平台侧问题你没有 GCP 访问权限但症状明确指向基础设施层。快速参考症状 → 行动对照症状首先查什么依据Server trace 缺失、Studio trace 正常重新部署 Server仍无效则查 GCPmobs-collector日志cloud-deploy.md一条 trace 都没有部署日志是否有MASTRA_CLOUD_ACCESS_TOKEN相关告警common-errors.mdcollector 日志401 invalid signature核对JWT_SECRET一致性cloud-deploy.md部署日志出现 exporter disabled检查 platform-api 是否配置JWT_SECRETcloud-deploy.mdStudio 反复 session expired重新认证cookie domain 已知问题common-errors.md部署挂起/超时平台 Dashboard 确认 GCP 侧容器启动日志common-errors.md相关仓库资料主文档gcp-debugging.md云部署全流程含 mobs-collector 排查步骤cloud-deploy.md常见错误与修复common-errors.md架构概览deploy → token → traces → storagearchitecture.mdTrace 测试与 mobs-query 直查tests/traces.mdSmoke 测试总入口含测试清单与参数说明SKILL.md部署后 Server API 测试脚本scripts/test-server.sh【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考