Mastra Server 部署验证测试指南--test server从部署到 API 冒烟验证【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南是 Mastra 项目冒烟测试体系中server专项对应--test serverCloud Only的完整实战手册。它面向需要在 Mastra 平台 staging/production 环境验证 Server 部署的开发者与 QA核心目标是确认服务器部署成功、/health健康检查通过、Agent API 可正常响应并验证可观测性链路Traces是否贯通。读完本文你将掌握 Server 部署前的环境与认证准备、部署命令与关键输出解读、健康检查与 Agent API 的 curl 验证方法、现成测试脚本的使用以及常见部署故障的定位与修复思路。为什么需要 Server 部署验证在 Mastra 平台中studio部署提供可视化界面Playground、观测面板而server部署则提供可直接调用的 HTTP API——Agent 的generate/stream接口以及自定义 API 路由。两者是不同形态的产物Studio 面向人Server 面向程序。因此冒烟测试体系将其拆分为两个独立专项SKILL.md 中的测试清单第 11、12 项而--test server只针对服务器部署这一条链路。该测试仅适用于云端环境--env staging或--env production本地环境--env local下不存在远程 Server 部署运行--test server会被判定为不适用并跳过。前置条件在执行 Server 部署验证前需要确认以下条件齐备Mastra 平台账号具有部署权限对应 cloud-deploy.md 中提到的 platform account with deploy access项目至少包含一个 Agent后续 Agent API 测试需要一个真实的 agent ID如默认模板中的weather-agent已完成mastra auth login认证部署与观测查询都依赖有效凭据推荐先完成 Studio 部署因为第 7 步需要在 Studio 的/observability页面确认 Server API 调用产生的 Traces 是否出现Studio 先行部署可以避免排查链路时无从下手。测试流程七个步骤步骤 1设置目标环境Mastra CLI 通过环境变量MASTRA_PLATFORM_API_URL决定请求哪个平台 API。staging 与 production 是两个独立的平台端点# 切到 staging 环境 export MASTRA_PLATFORM_API_URLhttps://platform.staging.mastra.ai # 切回 productionCLI 默认值无需显式导出 unset MASTRA_PLATFORM_API_URL需要说明的是CLI 的默认平台地址即 productionhttps://platform.mastra.ai因此不设置就等于生产环境。同一项目可通过独立的配置文件.mastra-project.json与.mastra-project-staging.json分别关联两个环境两个环境各自拥有独立的 project ID互不干扰。步骤 2认证如尚未登录pnpx mastralatest auth login该命令会触发浏览器 OAuth 流程。注意登录会打开浏览器在执行前应提醒用户。登录后凭据保存在~/.mastra/credentials.json其中包含user.email、organizationId、token与refreshToken。由于 WorkOS token 约 5 分钟即过期cloud-deploy.md 提供了先验凭据、再刷新、最后才重新登录的降级策略# 检查现有凭据 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 过期时用 refreshToken 刷新无需重新登录 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\}登录后务必核对组织归属因为浏览器可能默认切到另一个账号/组织cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}步骤 3部署 Server# production默认使用 .mastra-project.json pnpx mastralatest server deploy -y # staging显式指定配置文件 pnpx mastralatest server deploy --config .mastra-project-staging.json -y-y标志表示自动确认所有交互式设置auto-accept适合 CI 或无人值守场景。部署过程中要观察的关键节点ChecklistBuild 是否开始Build 是否完成记录任何 warningDeploy 是否开始从输出中抓取 Server URL需要重点记录的关键警告mastra-cloud-observability-exporter disabled—— 可观测性导出器被禁用说明 Traces 链路不可用通常是平台侧JWT_SECRET未配置、Server 无法获取MASTRA_CLOUD_ACCESS_TOKEN所致CLOUD_EXPORTER_FAILED_TO_BATCH_UPLOAD_LOGS—— 日志批量上传失败指向 trace endpoint 存在问题。这两个警告直接决定了第 7 步 Traces 验证能否通过务必记录在报告中。从源码看server deploy的实际执行流程packages/cli/src/commands/server/deploy.ts依次为认证getToken()读取本地凭据失败则提示先执行mastra auth login加载项目配置通过loadProjectConfig(targetDir, opts.config)读取.mastra-project.json或--config指定的文件解析组织优先级为MASTRA_ORG_ID环境变量 →--org标志 → 项目配置中的organizationId→ 当前凭据组织 → 交互选择。在 headless 模式设置了MASTRA_API_TOKEN下若 org/project 缺失会直接报错解析项目支持MASTRA_PROJECT_ID环境变量、--project标志、项目配置关联、按包名匹配已有项目或新建确认部署设置非-y时弹出确认并将 project/org 关联信息写回.mastra-project.json构建 打包 上传 轮询先通过checkBuildStaleness判断源码 hash 是否变化决定是否重建构建产物须存在.mastra/output/index.mjs随后将.mastra/output与package.json打成 zip 上传最后轮询部署状态直到完成。环境变量方面deploy 命令会从项目目录的.env*文件中读取环境变量并随部署上传若存在多个 env 文件-y模式下会要求显式用--env-file指定否则默认优先.env.production。上传前还会执行 preflight 校验preflightBuildOutput用本地 env 合并平台存储 env的视角预检构建产物提前拦截用户侧可归因的错误preflight 被 block 时会中止部署。步骤 4健康检查部署完成后先验证服务是否存活curl server-url/healthChecklist记录返回的 HTTP 状态码记录响应体内容正常响应形如{success:true}。生产与 staging 的 URL 模式不同见下文部署 URL一节。步骤 5Agent API 测试健康检查通过后直接调用 Agent 的生成接口验证推理链路curl -X POST server-url/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:Weather in Tokyo?}]}Checklist记录返回的 HTTP 状态码记录响应内容注意请求体遵循 OpenAI 风格的messages数组结构。若返回 404多半是 agent ID 写错如项目里没有weather-agent403 则通常意味着部署尚未就绪。步骤 6使用现成测试脚本仓库提供了自动化脚本 scripts/test-server.sh一条命令完成健康检查与 Agent 调用.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?该脚本的执行逻辑与第 4、5 步的 curl 等价但更健壮前置依赖检查要求curl与jq均已安装否则直接报错退出自动去除 URL 末尾的/健康检查curl --connect-timeout 10 --max-time 30请求server-url/health通过末尾追加的%{http_code}提取状态码非 200 直接以退出码 1 结束Agent 测试用jq -n --arg msg构造 JSON 请求体正确处理消息中的特殊字符--max-time 60POST 到/api/agents/agent-id/generate结果解析200 时用jq -r .text // .content // .提取响应文本非 200 时打印原始 body 并退出 1。脚本还会在终端输出每个步骤的 ✅/❌ 标记方便直接粘贴到冒烟报告中。Checklist记录健康检查结果记录 Agent 调用结果记录脚本退出码0 全部通过1 任一步失败步骤 7在 Studio 中检查 TracesServer 部署验证的关键一步是确认可观测性链路完整调用产生 Traces而不仅是 API 返回 200。打开 Studio 的/observability页面刷新页面观察来自 Server API 调用的 Trace 是否出现记录 Trace 出现所需时长如果出现。判断口径见 cloud-deploy.md 的 Server Trace VerificationStudio Traces由 Studio UI 交互产生Server Traces由对已部署 Server 的直接 API 调用产生。两者都应在 Studio 的 Traces 页面出现。如果只有 Studio Traces 而没有 Server Traces说明 Trace 管道存在问题——这正是第 3 步记录的两个关键警告的用武之地。观察与报告要点检查项需记录内容Deploy完成状态任何错误或警告URL部署返回的 Server URLHealth/health的 HTTP 状态与响应Agent APIHTTP 状态与响应内容TracesTraces 是否出现、出现时机这些字段应汇总进冒烟测试报告Smoke Test Results表格的server行并在 Issues/Warnings 中单独列出部署期警告。部署 URL 模式环境URL 模式Staginghttps://project.server.staging.mastra.cloudProductionhttps://project.server.mastra.cloud注意 production 没有staging中间段。对应地Studio 部署 URL 为project.studio.mastra.cloudprod与project.studio.staging.mastra.cloudstaging。每次部署的准确 URL 以命令输出为准不要凭模式猜测。Server API 端点一览端点方法用途/healthGET健康检查/api/agents/id/generatePOSTAgent 生成非流式/api/agents/id/streamPOSTAgent 流式生成/custom-routeANY自定义 API 路由自定义路由在部署时有一个高频坑必须在 server 配置中使用apiRoutes而非routes注册否则路由会静默失效server: { apiRoutes: [helloRoute], // ✅ 正确 // routes: [helloRoute], // ❌ 错误 - 静默失败 }部署后可用如下方式验证自定义路由cloud-deploy.mdcurl https://project.server.staging.mastra.cloud/hello # 预期: {message:Hello from custom route!}常见问题排查问题原因解决办法health 返回 403尚未部署完成等待或重新部署Agent 返回 404Agent ID 错误核对项目中的 agent IDsTraces 缺失Token 问题检查部署警告重新部署请求超时冷启动30 秒后重试针对 Traces 缺失这一最高频问题cloud-deploy.md 给出了更细的排查链查看mobs-collector日志GCP ConsolePOST 200 Traces 已接收POST 401 JWT 认证失败POST 404 端点错误401 invalid signature服务间JWT_SECRET不一致部署日志出现 mastra-cloud-observability-exporter disabled平台 API 未配置JWT_SECRETServer 拿不到MASTRA_CLOUD_ACCESS_TOKEN直接查 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 observability-query-endpoint/api/observability/traces?resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .traces | length部署报认证错误时的兜底手段pnpx mastralatest auth logout pnpx mastralatest auth login然后再重试部署。若 Server 出现 CORS 报错检查部署环境变量MASTRA_CORS_ORIGIN是否设置正确并确认 origin 域名与 Studio 域名模式匹配Server 部署通过SERVER_WRAPPER注入 CORS 配置。注意事项与预期行为Server 冷启动可能需要 10–30 秒刚部署完或闲置回收后的首次请求会较慢属于正常现象部署后首次请求可能较慢与冷启动同源脚本的--max-time 60已为此留出余量Traces 最长可能延迟 30 秒才出现验证时不要刷新一两次就下结论Traces 持续缺失时应重新部署如果多次验证都看不到 Server Trace按上文 Token 链路排查后重部署。与整体冒烟测试体系的关系--test server是冒烟测试的 12 个专项之一见 SKILL.md 的 Mandatory Test Checklist。在完整冒烟中Server Deploy 位于 Studio Deploy 之后、属于云端收尾验证环节使用--test server做定向测试时系统会先执行 Setup步骤 1再仅运行 server 专项例如smoke test --env production --existing-project ~/my-app --test studio,server,tracesserver 与 traces 专项的联动价值在于server 专项验证API 可用traces 专项验证调用可观测两者合起来才构成对云端 Server 部署质量的完整判定。将本指南与 cloud-deploy.md部署细节、setup.md环境配置配套阅读即可在 staging 与 production 两个环境上稳定复现这套 Server 部署验证流程。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考