Mastra platform 上的 Server

Mastra platform 上的 Server 是一个生产部署目标，将你的 Mastra 应用作为 API 服务器运行。当你希望平台来构建、部署、托管和管理 Mastra 服务器时，请使用它。

你可以获得稳定的 API 端点、环境变量管理和自定义域名支持，以及开箱即用的部署历史。

备注

Server 部署会自动创建托管存储。如果你使用 LibSQLStore 和文件 URL 覆盖存储，请改用远程托管的数据库，因为 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 deploy

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

   该命令会运行 mastra build 并上传其 artifact，然后构建并部署 Docker 镜像。首次部署时，CLI 会创建 .mastra-project.json 文件，将本地项目关联到平台。请提交此文件，以便后续部署和 CI/CD 指向同一项目。

   备注

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

   完整的 flags 列表请参阅 CLI 参考。

4. 在 CLI 打印的 URL 处验证部署。追加 /api/agents 以确认它返回 agents 的 JSON 列表。

   注意

   在公开暴露端点之前，请先设置身份验证。

部署生命周期

每个项目一次只运行一个构建，部署会经历 queued → uploading → building → deploying → running（或 failed、cancelled、crashed 或 stopped）的状态转换。当多个部署排队时，最新的会继续，其余会被取消。运行超过 15 分钟的构建会自动失败。首次部署会创建基础设施并从本地 .env 填充环境变量。服务器 URL 在多次部署之间保持稳定。

空闲行为

Mastra platform 上的 Server 可以在一段时间无活动后休眠服务以节省资源。不活动由出站网络流量衡量。只有在约 10 分钟没有出站数据包后，服务才被视为空闲。任何周期性出站流量都会重置此计时器并保持服务唤醒。

从不休眠的服务器通常有后台任务或长连接在定时发送流量。请检查以下常见原因。

持久数据库连接

保持打开的数据库客户端即使在服务器空闲时也会让连接存活。许多驱动还会运行后台健康检查，定期 ping 数据库，这会被计为出站流量。例如，从未关闭的 MongoDB 客户端会保持监控 socket 打开，并大约每 10 秒发送一次心跳。

仅靠排空空闲连接的连接池设置还不够，因为驱动的监控连接会保持打开并持续 ping。要让服务器休眠，请在一段时间无活动后关闭客户端，并在下一次请求时重新连接。

备注

关闭客户端会给服务器唤醒后的第一个请求增加短暂的重连延迟。如果你的工作负载无法容忍该延迟，请保持连接打开，不要依赖空闲休眠。

定时任务和计时器

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

外部 ping 和 keep-alive 检查

定期命中服务器的 uptime 监控、健康检查或 keep-alive ping 会重置空闲计时器。如果你希望服务器休眠，请移除这些检查，或将其间隔增加到空闲窗口之外。

可观测性 exporters

将 traces、logs 或 metrics 流式发送到远程端点的 exporter 会产生出站流量。请确认 exporter 会批量发送并在服务器空闲时停止发送，而不是按固定间隔刷新。

长连接流

打开的 server-sent events（SSE）流、WebSocket 或其他长连接会在关闭前保持流量打开。在后台保持订阅的流式响应会让连接保持活跃。请确认流在客户端断开时关闭，并且服务器在其他方面空闲时没有流保持打开。

聊天集成

某些聊天集成会保持持久连接并发送定期心跳，从而让服务器保持唤醒。例如，Socket Mode 中的 Slack app 会打开 WebSocket 并大约每 30 秒 ping 一次，Discord bot 会保持 gateway WebSocket 打开并定时发送心跳。打开的 socket 和心跳都会阻止空闲。

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

检查活跃连接

要找出是什么让服务器保持唤醒，请在空闲期间检查进程的 active handles。所有请求完成后仍然存在的 handle 就是需要调查的原因。打开的 sockets 指向需要关闭的持久连接，活跃的 timers 指向 setInterval 或自我重新调度的 setTimeout。

将以下辅助函数放入应用，然后在流量停止后观察日志。服务器空闲后仍列出的任何内容都会让它保持唤醒：

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()，以免辅助函数本身让服务器保持唤醒。

保持服务运行

某些应用确实需要上述连接或任务，例如用于降低首次请求延迟的持久数据库连接、后台调度器或长连接流。如果你的应用需要其中任何一项，请不要强制服务休眠。请改用 Persistent Server add-on 让服务持续运行。

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

CI/CD

从 GitHub Actions、GitLab CI 或任何 CI 提供器自动化部署。首次交互式部署后，CI/CD 需要两样东西：API token 和提交到仓库的 .mastra-project.json 文件。

提示

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

创建 API token

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

   mastra auth tokens create ci-deploy

   CLI 只会打印一次 token。请立即复制，因为它无法再次获取。

2. 将 token 作为 secret 添加到 CI 提供器。在 GitHub Actions 中，进入 Settings → Secrets and variables → Actions 并创建 MASTRA_API_TOKEN secret。

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

--yes flag

传入 --yes（或 -y）以跳过所有确认提示。没有它，CLI 会等待交互输入，你的 CI 任务会挂起。

mastra 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 deploy --yes
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}

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

GitLab CI

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

.gitlab-ci.yml

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

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

其他 CI 提供器

任何运行 Node.js 和 shell 命令的 CI 系统都可以与 Mastra 配合：

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

验证部署

workflow 完成后，通过访问健康端点验证部署：

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

或检查 agents 端点，它返回 agents 的 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 deploy
• mastra server pause
• mastra server restart
• mastra auth tokens