跳至主要內容

配置

部署至 Mastra platform 時，CLI 會產生 .mastra-project.json 配置檔案，並從平台以及你選擇使用的本機 .env 檔案解析環境變數。

本頁說明這兩種機制。

項目配置
項目配置 的直接連結

首次執行 mastra deploy 時，系統會自動產生 .mastra-project.json 檔案。它會將你的本機項目連結至平台項目。GitHub 整合亦會將同一檔案寫入已連結的程式碼儲存庫。

請將它提交至版本控制，確保之後的部署（包括從 CI 進行的部署）會以正確的項目為目標。

檔案內容大致如下：

.mastra-project.json
{
  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
  "projectName": "my-project",
  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}
欄位說明
projectId項目的 UUID，在建立項目時指派。
projectName方便閱讀的項目名稱，在控制台及 CLI 輸出中用作顯示標籤。
organizationId擁有項目的組織。所有部署、API 金鑰及資源的範圍均限定於此組織。

環境變數
環境變數 的直接連結

本機 env 檔案並非必要。mastra deploy 會從三個來源解析變數：

  • 受管理變數：由託管資料庫等平台資源注入。這些變數由平台定義，你無法編輯。
  • 已儲存變數：透過控制台儲存在項目或環境中。每次部署時均會直接使用，無需本機檔案。
  • 本機 env 檔案：部署會在上述變數之上套用明確指定的 --env-file，或目前環境中的 .env 和 .env.local 檔案。.env.local 的變數會覆蓋 .env 中的變數。

如要指定部署使用某個 env 檔案，而非依賴預設選擇，請傳入 --env-file：

mastra deploy --env-file .env.production --yes

部署前請檢查並清理本機 env 檔案，以免上載只供開發使用的資料或個人秘密資料。

Observability
Observability 的直接連結

以下環境變數用於配置 Mastra platform 上的 Observability 產品。

變數說明
MASTRA_PLATFORM_ACCESS_TOKEN範圍限定於組織的存取權杖。CLI 會在佈建 Observability 時寫入此值，並用它進行平台驗證。
MASTRA_PROJECT_ID平台項目的 UUID。MastraPlatformExporter 會用它將 Observability 資料連結至平台項目。Studio 和 Server 部署會從 .mastra-project.json 讀取項目 ID。
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT可選的 Observability 端點覆寫值。只有在本機進行平台開發時，系統才會自動設定此值。預設為 https://observability.mastra.ai。
MASTRA_ORG_ID覆寫 CLI 指令目前使用的組織。你亦可在支援的指令中使用 --org 旗標設定。

MastraPlatformExporter 會讀取 MASTRA_PLATFORM_ACCESS_TOKEN，以驗證向平台匯出資料的操作。

多個環境
多個環境 的直接連結

單一項目可在多個環境中執行同一程式碼庫，例如 production 和 staging。每個環境都有各自的 URL、已儲存變數和部署記錄。一個 .mastra-project.json 檔案已涵蓋所有環境：

mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes
備註

舊版平台要求每個環境使用一個項目。環境功能已取代此模式，因此請保留單一項目，並改為部署至不同環境。

On this page