Mastra platform 上的 Server

Mastra platform 上的 Server 是生产部署目标，会将 Mastra 应用作为 API Server 运行。如果希望由 platform 构建、部署、托管和管理 Mastra Server，请使用它。

无需额外设置，即可获得稳定的 API endpoint、环境变量管理、自定义域名支持和部署历史记录。

备注

mastra server deploy 是早期拆分的部署路径。新项目应使用统一的 mastra deploy 命令，该命令增加了部署前验证、环境和由 CLI 管理的数据库。

备注

Server 部署会自动预配托管 Storage。如果使用 LibSQLStore 和文件 URL 覆盖 Storage，请改用远程托管数据库，因为 Mastra platform 使用临时文件系统。

快速入门

1. 按照入门指南创建第一个 Mastra 项目。

2. 全局安装 mastra CLI：

   npm

   npm install -g mastra

   pnpm

   pnpm add -g mastra

   Yarn

   yarn global add mastra

   Bun

   bun add --global mastra

3. 部署项目：

   mastra server deploy

   如果尚未通过身份验证，CLI 会提示登录。它会将凭据存储在本地，后续 CLI 命令都会使用这些凭据。

   该命令会运行 mastra build、上传 artifact、构建 Docker image 并完成部署。首次部署时，CLI 会创建 .mastra-project.json 文件，将本地项目链接到 platform。请提交该文件，使后续部署和 CI/CD 指向同一项目。

   备注

   系统会自动包含 .env、.env.local 和 .env.production 中的环境变量。首次部署时，如果尚未设置任何 env 变量，会使用这些文件初始化项目。之后请通过 Web dashboard 管理 env 变量。 首次部署前请检查并清理这些文件，避免上传仅用于开发的密钥或个人密钥。

   有关完整标志列表，请参阅 CLI Reference。

4. 使用 CLI 输出的 URL 验证部署。在末尾添加 /api/agents，确认它返回 Agent 的 JSON 列表。

   注意

   公开暴露 endpoint 前，请设置身份验证。

部署生命周期

部署会依次经过 queued → uploading → building → deploying → running（也可能进入 failed、cancelled、crashed 或 stopped）。每个项目一次只运行一个构建。如果有多个部署排队，只有最新部署会继续，其余部署都会取消。运行超过 15 分钟的构建会自动失败。首次部署会预配基础设施，并从本地 .env 初始化环境变量。Server URL 会在不同部署间保持稳定。

空闲行为

Mastra platform 上的 Server 可以在一段时间没有活动后使服务进入休眠，以节省资源。系统通过出站网络流量衡量是否活跃。只有大约 10 分钟没有任何出站数据包，服务才会被视为空闲。任何周期性出站流量都会重置计时器，使服务保持唤醒。

始终无法休眠的 Server 通常存在按时发送流量的后台任务或长期连接。请检查以下常见原因。

持久数据库连接

持续打开的数据库客户端会在 Server 空闲时保持连接。许多 driver 还会在后台定期运行 health check，对数据库执行 ping，这也算作出站流量。例如，从未关闭的 MongoDB 客户端会保持监控 socket 打开，并大约每 10 秒发送一次 heartbeat。

仅依靠排空空闲连接的连接池设置还不够，因为 driver 的监控连接会保持打开并持续发送 ping。若要允许 Server 休眠，请在一段时间没有活动后关闭客户端，并在下一个请求到来时重新连接。

备注

关闭客户端会让 Server 唤醒后的首个请求增加短暂的重新连接延迟。如果工作负载无法接受该延迟，请保持连接打开，不要依赖空闲休眠。

定时任务和 timer

进行网络调用的 setInterval、cron 任务或轮询循环会使 Server 保持唤醒。如果需要定时工作，请将其作为单独服务运行，或使用外部 Scheduler 通过请求唤醒 Server。

外部 ping 和 keep-alive 检查

定期访问 Server 的 uptime monitor、health check 或 keep-alive ping 会重置空闲计时器。如果希望 Server 休眠，请移除这些检查，或将检查间隔增大到超过空闲窗口。

Observability Exporter

将 Trace、日志或指标流式发送到远程 endpoint 的 Exporter 会产生出站流量。请确认 Exporter 会进行批处理，并在 Server 空闲时停止发送，而不是按固定时间间隔 flush。

长期存在的流

打开的 Server-Sent Events（SSE）流、WebSocket 或其他长期连接在关闭前会保持流量。持续在后台订阅的流式响应会保持连接活跃。请确认客户端断开连接时流会关闭，并且在 Server 其他方面均为空闲时没有流继续打开。

对话集成

部分对话集成会保持持久连接并定期发送 heartbeat，使 Server 保持唤醒。例如，Socket Mode 下的 Slack App 会打开 WebSocket，大约每 30 秒发送一次 ping；Discord bot 会保持 Gateway WebSocket 打开，并通过 timer 发送 heartbeat。打开的 socket 和 heartbeat 都会阻止休眠。

如果希望 Server 休眠，并且集成支持，请通过 HTTP webhook 接收事件，而不是使用持久连接。例如，Slack App 可以使用带请求 URL 的 Events API，而不是 Socket Mode。如果应用需要持久连接，请使用下文所述的 Persistent Server add-on 保持服务运行。

检查活跃连接

若要找出使 Server 保持唤醒的内容，请在空闲期间检查进程的活跃 handle。所有请求结束后仍然存在的 handle 就是需要调查的原因。打开的 socket 指向需要关闭的持久连接，活跃 timer 则指向 setInterval 或自行重新安排的 setTimeout。

将以下 helper 放入应用，然后在流量停止后观察日志。Server 空闲后仍列出的任何内容都会使其保持唤醒：

src/mastra/diagnose-idle.ts

export function logActiveHandles() {
  // process._getActiveHandles is undocumented but useful for diagnosis.
  const handles = (process as any)._getActiveHandles() as Array<any>

  const summary = handles.map(handle => {
    const type = handle?.constructor?.name ?? typeof handle
    if (type === 'Socket') {
      return `Socket -> ${handle.remoteAddress}:${handle.remotePort}`
    }
    return type
  })

  console.log(`[idle] ${handles.length} active handles:`, summary)
}

// Log every 30 seconds so you can see what persists while the server is idle.
setInterval(logActiveHandles, 30_000).unref()

对诊断 interval 调用 unref()，避免 helper 本身使 Server 保持唤醒。

保持服务运行

部分应用确实需要上述连接或任务，例如为了降低首个请求延迟而使用持久数据库连接、使用后台 Scheduler，或使用长期流。如果应用需要其中任何一项，请不要强制服务休眠。改用 Persistent Server add-on，使服务持续运行。

启用 Persistent Server add-on 后，即使没有流量，服务也会保持唤醒，因此持久连接、定时任务和打开的流都能继续工作，不会被空闲休眠打断。

CI/CD

可以通过 GitHub Actions、GitLab CI 或任何 CI Provider 自动部署。首次交互式部署后，CI/CD 需要两项内容：API token，以及已提交到仓库的 .mastra-project.json 文件。

提示

如果代码位于 GitHub，GitHub 集成无需编写 Workflow 文件即可实现推送时部署。当需要使用 GitLab、其他 CI Provider，或在部署前执行自定义构建步骤时，请使用下述基于 CLI 的 CI/CD 流程。

创建 API token

1. 在本地运行以下命令：

   mastra auth tokens create ci-deploy

   CLI 只会显示一次 token。请立即复制，之后无法再次获取。

2. 在 CI Provider 中将令牌添加为密钥。在 GitHub Actions 中，转到 Settings → Secrets and variables → Actions，创建名为 MASTRA_API_TOKEN 的密钥。

3. 确保已将 .mastra-project.json 文件提交到仓库。CI 部署期间，CLI 会从该文件读取 organizationId 和 projectId，指向正确的项目。

--yes 标志

传入 --yes（或 -y）跳过所有确认提示。如果省略，CLI 会等待交互式输入，使 CI job 一直挂起。

mastra server deploy --yes

GitHub Actions

以下 Workflow 会在每次推送到 main 时部署：

.github/workflows/deploy-mastra.yml

name: Deploy to Mastra platform

on:
  push:
    branches: [main]
    paths: ['src/mastra/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Deploy to Mastra platform
        run: npx mastra server deploy --yes
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}

如果 Mastra 项目位于子目录（例如 monorepo），请调整 paths 筛选器和 working-directory。

备注

对于 Studio 部署，请将 mastra server deploy 替换为 mastra studio deploy。标志和环境变量相同。

GitLab CI

以下 pipeline 会在推送到 main 时部署：

.gitlab-ci.yml

deploy:
  image: node:22
  stage: deploy
  only:
    - main
  before_script:
    - npm install
  script:
    - npx mastra server deploy --yes

在 Settings → CI/CD → Variables 中将 MASTRA_API_TOKEN 添加为 CI/CD 变量。

其他 CI Provider

任何能运行 Node.js 和 shell 命令的 CI 系统都可以使用 Mastra：

1. 安装依赖。
2. 将 MASTRA_API_TOKEN 设置为环境变量。
3. 运行 mastra server deploy --yes（或 mastra studio deploy --yes）。

验证部署

Workflow 完成后，通过 health endpoint 验证部署：

curl -f https://<your-project>.server.mastra.cloud/health

也可以检查 Agent endpoint，它会返回 Agent 的 JSON 列表：

curl -f https://<your-project>.server.mastra.cloud/api/agents

以下示例向 GitHub Actions Workflow 添加验证步骤：

- name: Verify deployment
  run: |
    sleep 30
    curl -f https://<your-project>.server.mastra.cloud/health

使用环境变量覆盖项目配置

CLI 默认从 .mastra-project.json 读取 organizationId 和 projectId。若要覆盖这些值（例如从同一仓库部署到其他项目），请设置以下环境变量：

变量	说明
MASTRA_ORG_ID	覆盖 .mastra-project.json 中的组织 ID。
MASTRA_PROJECT_ID	覆盖 .mastra-project.json 中的项目 ID。

相关内容

• mastra server deploy
• mastra server pause
• mastra server restart
• mastra studio deploy
• mastra auth tokens