> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Mastra platform 上的 Server

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

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

> **备注:** `mastra server deploy` 是早期拆分的部署路径。新项目应使用统一的 [`mastra deploy`](https://mastra.zisheng.pro/docs/mastra-platform/deploy) 命令，该命令增加了部署前验证、环境和由 CLI 管理的数据库。

> **备注:** Server 部署会自动预配托管 Storage。如果使用 [LibSQLStore](https://mastra.zisheng.pro/reference/storage/libsql) 和文件 URL 覆盖 Storage，请改用远程托管数据库，因为 Mastra platform 使用临时文件系统。

## 快速入门

1. 按照[入门指南](https://mastra.zisheng.pro/docs)创建第一个 Mastra 项目。

2. 全局安装 `mastra` CLI：

   **npm**:

   ```bash
   npm install -g mastra
   ```

   **pnpm**:

   ```bash
   pnpm add -g mastra
   ```

   **Yarn**:

   ```bash
   yarn global add mastra
   ```

   **Bun**:

   ```bash
   bun add --global mastra
   ```

3. 部署项目：

   ```bash
   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](https://mastra.zisheng.pro/reference/cli/mastra)。

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

   > **注意:** 公开暴露 endpoint 前，请设置[身份验证](https://mastra.zisheng.pro/docs/server/auth)。

## 部署生命周期

部署会依次经过 **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 空闲后仍列出的任何内容都会使其保持唤醒：

```typescript
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 集成](https://mastra.zisheng.pro/docs/mastra-platform/github)无需编写 Workflow 文件即可实现推送时部署。当需要使用 GitLab、其他 CI Provider，或在部署前执行自定义构建步骤时，请使用下述基于 CLI 的 CI/CD 流程。

### 创建 API token

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

   ```bash
   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 一直挂起。

```bash
mastra server deploy --yes
```

### GitHub Actions

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

```yaml
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` 时部署：

```yaml
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 验证部署：

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

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

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

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

```yaml
- 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`](https://mastra.zisheng.pro/reference/cli/mastra)
- [`mastra server pause`](https://mastra.zisheng.pro/reference/cli/mastra)
- [`mastra server restart`](https://mastra.zisheng.pro/reference/cli/mastra)
- [`mastra studio deploy`](https://mastra.zisheng.pro/reference/cli/mastra)
- [`mastra auth tokens`](https://mastra.zisheng.pro/reference/cli/mastra)