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

# Mastra platform 上的伺服器

Mastra platform 上的伺服器是一個生產環境部署目標，會將你的 Mastra 應用程式作為 API 伺服器運行。當你希望由平台建置、部署、託管及管理 Mastra 伺服器時，便可使用此功能。

你可直接獲得穩定的 API 端點、環境變數管理、自訂網域支援及部署記錄。

> **備註:** `mastra server deploy` 是較早期的分拆式部署方式。新項目應使用統一的 [`mastra deploy`](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/deploy) 指令，當中加入了部署前驗證、環境及由 CLI 管理的資料庫。

> **備註:** 伺服器部署會自動配置託管儲存空間。如果你以 [LibSQLStore](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql) 覆寫儲存空間並使用檔案 URL，請改用遙距託管的資料庫，因為 Mastra platform 使用暫時性檔案系統。

## 快速開始

1. 按照[入門指南](https://mastra.zisheng.pro/zh-HK/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` 檔案，把你的本機項目連結至平台。請提交此檔案，讓之後的部署及 CI/CD 都以同一個項目為目標。

   > **備註:** 系統會自動加入 `.env`、`.env.local` 及 `.env.production` 中的環境變數。首次部署時，如果項目尚未設定任何環境變數，這些檔案便會用作初始設定。此後，請透過網頁控制台管理環境變數。 首次部署前，請檢查並清理這些檔案，以免上載只供開發使用的資料或個人機密資料。

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

4. 在 CLI 顯示的 URL 驗證部署。於 URL 末端加上 `/api/agents`，確認它會傳回你的 Agent JSON 清單。

   > **注意:** 在公開你的端點前，請先設定[身份驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth)。

## 部署生命週期

部署會依次經歷 **queued → uploading → building → deploying → running**（或進入 **failed**、**cancelled**、**crashed** 或 **stopped** 狀態）。每個項目同一時間只會運行一個建置。如果多個部署排隊等候，只有最新的一個會繼續，其餘都會取消。運行超過 15 分鐘的建置會自動標記為失敗。首次部署會配置基礎設施，並以本機 `.env` 中的環境變數進行初始設定。伺服器 URL 在各次部署之間維持不變。

## 閒置行為

Mastra platform 上的伺服器可在服務閒置一段時間後讓其休眠，以節省資源。系統根據對外網絡流量量度閒置狀態。只有在約 10 分鐘內沒有任何對外封包時，服務才會視為閒置。任何週期性的對外流量都會重設計時器，令服務保持運行。

如果伺服器一直沒有休眠，通常是背景工作或長時間維持的連線按時傳送流量所致。請檢查以下常見原因。

### 持續的資料庫連線

即使伺服器閒置，保持開啟的資料庫用戶端仍會維持連線。許多驅動程式亦會在背景定時執行健康檢查，向資料庫發送 ping；這也會計作對外流量。例如，從未關閉的 MongoDB 用戶端會保持監察 socket 開啟，並大約每 10 秒傳送一次心跳訊號。

單靠清除閒置連線的連線池設定並不足夠，因為驅動程式的監察連線仍會保持開啟並持續發送 ping。若要讓伺服器休眠，請在閒置一段時間後關閉用戶端，並於下一個請求到達時重新連線。

> **備註:** 關閉用戶端會令伺服器喚醒後的第一個請求多出短暫的重新連線延遲。如果你的工作負載無法接受這種延遲，請保持連線開啟，並不要依賴閒置休眠。

### 排程工作及計時器

會發出網絡呼叫的 `setInterval`、cron 工作或輪詢迴圈，都會令伺服器保持運行。如果你需要執行排程工作，請將其作為獨立服務運行，或使用外部排程器透過請求喚醒伺服器。

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

定時存取伺服器的運作時間監察器、健康檢查或 keep-alive ping，都會重設閒置計時器。如果你希望伺服器進入休眠，請移除這些檢查，或將檢查間隔延長至超過閒置時限。

### 可觀察性匯出器

將 Trace、日誌或指標串流至遙距端點的匯出器會產生對外流量。請確認匯出器會分批傳送資料，並在伺服器閒置時停止傳送，而不是按固定間隔清空資料。

### 長時間維持的串流

開啟的伺服器傳送事件（SSE）串流、WebSocket 或其他長時間維持的連線，會持續產生流量直至連線關閉。在背景保持訂閱的串流回應會令連線維持活動。請確認串流會在用戶端中斷連線時關閉，而且伺服器在其他方面處於閒置狀態時，不會有任何串流保持開啟。

### 聊天整合

部分聊天整合會維持持續連線，並定期傳送心跳訊號，令伺服器保持運行。例如，以 Socket Mode 運行的 Slack 應用程式會開啟 WebSocket，並大約每 30 秒發送一次 ping；Discord bot 則會保持其閘道 WebSocket 開啟，並透過計時器傳送心跳訊號。開啟的 socket 和心跳訊號都會阻止服務進入閒置狀態。

如果你希望伺服器休眠，而相關整合亦支援此方式，請透過 HTTP webhook 接收事件，而不要使用持續連線。例如，Slack 應用程式可使用設有請求 URL 的 Events API，而不使用 Socket Mode。如果你的應用程式需要持續連線，請使用下述的 **Persistent Server add-on** 讓服務保持運行。

### 檢查活動連線

若要找出令伺服器保持運行的原因，請在閒置期間檢查程序中的活動 handle。所有請求完成後仍然存在的 handle，就是需要調查的原因。開啟的 socket 表示有需要關閉的持續連線，而活動計時器則表示存在 `setInterval` 或自行重新排程的 `setTimeout`。

將以下輔助程式加入你的應用程式，然後在流量停止後查看日誌。伺服器進入閒置狀態後仍然列出的任何項目，都會令伺服器保持運行：

```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()`，以免輔助程式本身令伺服器保持運行。

### 讓服務持續運行

部分應用程式確實需要上述連線或工作，例如用於縮短首次請求延遲的持續資料庫連線、背景排程器或長時間維持的串流。如果你的應用程式需要其中任何一項，請不要強制服務休眠。請改用 **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/zh-HK/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 中將 token 加為秘密資料。在 GitHub Actions 中，前往 **Settings → Secrets and variables → 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
```

在 **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 完成後，請存取健康狀態端點以驗證部署：

```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 預設會讀取 `organizationId` 及 `projectId`，資料來自 `.mastra-project.json`。如要覆寫這些值（例如從同一個儲存庫部署至另一個項目），請設定以下環境變數：

| 變數                  | 說明                                 |
| ------------------- | ---------------------------------- |
| `MASTRA_ORG_ID`     | 覆寫 `.mastra-project.json` 中的組織 ID。 |
| `MASTRA_PROJECT_ID` | 覆寫 `.mastra-project.json` 中的項目 ID。 |

## 相關內容

- [`mastra server deploy`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)
- [`mastra server pause`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)
- [`mastra server restart`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)
- [`mastra studio deploy`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)
- [`mastra auth tokens`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)