跳至主要內容

設定

部署至 Mastra platform 時，CLI 會產生 .mastra-project.json 設定檔，並從 platform 以及選用的本機 .env 檔案解析環境變數。

本頁說明這兩種機制。

專案設定
「專案設定」的直接連結

第一次執行 mastra deploy 時，系統會自動產生 .mastra-project.json。它會將本機專案連結至 platform 專案。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 會從三種來源解析變數：

  • 受管理變數：由託管資料庫等 platform 資源注入。這些變數由 platform 定義，無法編輯。
  • 已儲存變數：透過控制面板儲存在專案或環境中。每次部署都會直接使用，不需要本機檔案。
  • 本機 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 時寫入，並用於 platform 驗證。
MASTRA_PROJECT_IDPlatform 專案的 UUID。MastraPlatformExporter 用它將 Observability 資料連結至 platform 專案。Studio 與 Server 部署會從 .mastra-project.json 讀取專案 ID。
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT選用的 Observability 端點覆寫值。只有在本機開發 platform 時才會自動設定。預設為 https://observability.mastra.ai。
MASTRA_ORG_ID覆寫 CLI 指令目前使用的組織。支援的指令也可透過 --org 旗標設定。

MastraPlatformExporter 會讀取 MASTRA_PLATFORM_ACCESS_TOKEN，以驗證 platform 匯出作業。

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

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

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

舊版 platform 要求每個環境各自使用一個專案。現在 Environments 已取代該模式，因此請保留單一專案並部署至不同環境。

On this page