Mastra platform 上的 Server

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

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

備註

mastra server deploy 是先前分開的部署流程。新專案應使用統一的 mastra deploy 指令，其中加入了部署前驗證、環境及由 CLI 管理的資料庫。

備註

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 server deploy

   如果尚未驗證身分，CLI 會提示你登入。它會將憑證儲存在本機，後續 CLI 指令都會使用這些憑證。

   此指令會執行 mastra build、上傳成品、建置 Docker 映像檔並部署。第一次部署時，CLI 會建立 .mastra-project.json 檔案，將本機專案連結至 platform。請提交此檔案，讓後續部署及 CI/CD 指向同一專案。

   備註

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

   如需完整旗標清單，請參閱 CLI 參考。

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

   警告

   對外公開端點前，請先設定驗證。

部署生命週期

部署會依序經歷已排入佇列 → 上傳中 → 建置中 → 部署中 → 執行中（或失敗、已取消、當機、已停止）。每個專案一次只會執行一項建置。若有多項部署排入佇列，只有最新一項會繼續，其餘都會取消。建置執行超過 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 閒置後仍列出的任何項目，都會讓它保持喚醒：

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()

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

讓服務持續執行

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

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

CI/CD

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

提示

如果程式碼位於 GitHub，GitHub 整合可讓你推送即部署，不必撰寫 Workflow 檔案。若需要 GitLab、其他 CI Provider，或部署前的自訂建置步驟，請使用下方以 CLI 為基礎的 CI/CD 流程。

建立 API 權杖

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

   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 工作停滯。

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

在設定 → 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 完成後，請連線至健康狀態端點以驗證部署：

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

或者檢查 Agent 端點，它會傳回 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