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

# Mastra platform 上的 Server

Mastra platform 上的 Server 是正式環境部署目標，會將 Mastra 應用程式作為 API Server 執行。若要由 platform 建置、部署、託管及管理 Mastra Server，請使用此功能。

無需額外設定，即可取得穩定的 API 端點、環境變數管理、自訂網域支援及部署記錄。

> **備註:** `mastra server deploy` 是先前分開的部署流程。新專案應使用統一的 [`mastra deploy`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/deploy) 指令，其中加入了部署前驗證、環境及由 CLI 管理的資料庫。

> **備註:** Server 部署會自動佈建託管儲存空間。若使用 [LibSQLStore](https://mastra.zisheng.pro/zh-TW/reference/storage/libsql) 和檔案 URL 覆寫儲存空間，請改用遠端託管資料庫，因為 Mastra platform 使用暫時性檔案系統。

## 快速入門

1. 按照[入門指南](https://mastra.zisheng.pro/zh-TW/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`、上傳成品、建置 Docker 映像檔並部署。第一次部署時，CLI 會建立 `.mastra-project.json` 檔案，將本機專案連結至 platform。請提交此檔案，讓後續部署及 CI/CD 指向同一專案。

   > **備註:** `.env`、`.env.local` 和 `.env.production` 中的環境變數會自動納入。第一次部署時，如果尚未設定環境變數，這些檔案會植入專案。之後請透過網頁控制面板管理環境變數。 第一次部署前，請檢查並清理這些檔案，以免上傳僅供開發使用或個人的密鑰。

   如需完整旗標清單，請參閱 [CLI 參考](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)。

4. 使用 CLI 列出的 URL 驗證部署。附加 `/api/agents`，確認它會傳回 Agent 的 JSON 清單。

   > **警告:** 對外公開端點前，請先設定[驗證](https://mastra.zisheng.pro/zh-TW/docs/server/auth)。

## 部署生命週期

部署會依序經歷**已排入佇列 → 上傳中 → 建置中 → 部署中 → 執行中**（或**失敗**、**已取消**、**當機**、**已停止**）。每個專案一次只會執行一項建置。若有多項部署排入佇列，只有最新一項會繼續，其餘都會取消。建置執行超過 15 分鐘會自動判定失敗。第一次部署會佈建基礎架構，並從本機 `.env` 植入環境變數。Server URL 在各次部署之間維持不變。

## 閒置行為

Mastra platform 上的 Server 可在服務閒置一段時間後進入休眠，以節省資源。閒置狀態是以對外網路流量衡量。只有約 10 分鐘沒有對外封包時，服務才會視為閒置。任何週期性的對外流量都會重設計時器，讓服務保持喚醒。

永不休眠的 Server 通常有背景工作或長效連線，會依計時器傳送流量。請檢查以下常見原因。

### 持續性資料庫連線

持續開啟的資料庫用戶端即使在 Server 閒置時也會維持連線。許多驅動程式還會在背景定期執行健康狀態檢查並 ping 資料庫，這會計入對外流量。例如，從未關閉的 MongoDB 用戶端會保持監控 socket 開啟，約每 10 秒傳送一次活動訊號。

只靠清除閒置連線的連線集區設定並不足夠，因為驅動程式的監控連線會保持開啟並持續 ping。若要讓 Server 休眠，請在閒置一段時間後關閉用戶端，並在下次要求時重新連線。

> **備註:** 關閉用戶端會讓 Server 喚醒後的第一個要求多出短暫的重新連線延遲。若工作負載無法容忍此延遲，請保持連線開啟，不要依賴閒置休眠。

### 排程工作與計時器

發出網路呼叫的 `setInterval`、cron 工作或輪詢迴圈會讓 Server 保持喚醒。若需要排程工作，請將其作為獨立服務執行，或使用透過要求喚醒 Server 的外部排程器。

### 外部 ping 與 keep-alive 檢查

定期連線至 Server 的存活時間監控器、健康狀態檢查或 keep-alive ping 會重設閒置計時器。若希望 Server 休眠，請移除這些檢查，或將間隔增加到超過閒置時間範圍。

### 可觀測性匯出程式

將 Trace、記錄或指標串流至遠端端點的匯出程式會傳送對外流量。請確認匯出程式會批次處理資料，並在 Server 閒置時停止傳送，而非依固定間隔清空資料。

### 長效串流

開啟的 Server-Sent Events (SSE) 串流、WebSocket 或其他長效連線在關閉前會持續產生流量。在背景維持訂閱的串流回應會讓連線保持作用中。請確認串流會在用戶端中斷連線時關閉，且 Server 處於其他方面的閒置狀態時，不會有串流保持開啟。

### 聊天整合

有些聊天整合會維持持續性連線，並定期傳送活動訊號，讓 Server 保持喚醒。例如，Socket Mode 下的 Slack App 會開啟 WebSocket，約每 30 秒 ping 一次；Discord 機器人則會保持 Gateway WebSocket 開啟，並依計時器傳送活動訊號。開啟的 socket 與活動訊號都會阻止閒置。

如果希望 Server 休眠，且整合支援 HTTP webhook，請使用它接收事件，不要使用持續性連線。例如，Slack App 可以使用具有要求 URL 的 Events API，而不使用 Socket Mode。如果應用程式需要持續性連線，請透過下述 **Persistent Server 附加元件**讓服務持續執行。

### 檢查作用中連線

若要找出讓 Server 保持喚醒的原因，請在閒置期間檢查處理程序的作用中控制碼。所有要求完成後仍存在的控制碼，就是需要調查的原因。開啟的 socket 表示有需要關閉的持續性連線，而作用中的計時器則指向 `setInterval` 或自行重新排程的 `setTimeout`。

將以下輔助程式加入應用程式，然後在流量停止後查看記錄。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()
```

請對診斷間隔呼叫 `unref()`，讓輔助程式本身不會使 Server 保持喚醒。

### 讓服務持續執行

有些應用程式確實需要上述連線或工作，例如用來降低第一個要求延遲的持續性資料庫連線、背景排程器或長效串流。如果應用程式需要其中任何一項，請勿強制服務休眠；請改用 **Persistent Server 附加元件**，讓服務持續執行。

啟用 **Persistent Server 附加元件**後，即使沒有流量，服務仍會保持喚醒，因此持續性連線、排程工作和開放串流都能繼續運作，不會因閒置休眠而中斷。

## CI/CD

自動執行從 GitHub Actions、GitLab CI 或任何 CI Provider 的部署。完成第一次互動式部署後，CI/CD 需要兩項內容：API 權杖，以及已提交至儲存庫的 `.mastra-project.json` 檔案。

> **提示:** 如果程式碼位於 GitHub，[GitHub 整合](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/github)可讓你推送即部署，不必撰寫 Workflow 檔案。若需要 GitLab、其他 CI Provider，或部署前的自訂建置步驟，請使用下方以 CLI 為基礎的 CI/CD 流程。

### 建立 API 權杖

1. 在本機執行下列指令：

   ```bash
   mastra auth tokens create ci-deploy
   ```

   CLI 只會列出一次權杖。請立即複製，之後無法再次擷取。

2. 在 CI Provider 中將權杖新增為密鑰。在 GitHub Actions 中，前往**設定 → 密鑰與變數 → Actions**，建立名為 `MASTRA_API_TOKEN` 的密鑰。

3. 確認 `.mastra-project.json` 檔案已提交至儲存庫。CLI 會從此檔案讀取 `organizationId` 與 `projectId`，以便在 CI 部署期間指向正確的專案。

### `--yes` 旗標

傳入 `--yes`（或 `-y`）可略過所有確認提示。若未傳入，CLI 會等待互動式輸入，導致 CI 工作停滯。

```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
```

在**設定 → CI/CD → 變數**中，將 `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 完成後，請連線至健康狀態端點以驗證部署：

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

或者檢查 Agent 端點，它會傳回 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/zh-TW/reference/cli/mastra)
- [`mastra server pause`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)
- [`mastra server restart`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)
- [`mastra studio deploy`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)
- [`mastra auth tokens`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)