跳到主要内容

配置

部署到 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人类可读的项目名称，用作 dashboard 和 CLI 输出中的显示标签。
organizationId拥有项目的组织。所有部署、API Key 和资源都限定在此组织内。

环境变量
环境变量的直接链接

本地 env 文件是可选的。mastra deploy 从三个来源解析变量：

  • 托管变量：由托管数据库等 platform 资源注入。这些变量由 platform 定义，无法编辑。
  • 存储的变量：通过 dashboard 保存在项目或环境中。每次部署时直接使用，不需要本地文件。
  • 本地 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限定于组织的访问 token。CLI 在预配 Observability 时写入该值，并使用它进行 platform 身份验证。
MASTRA_PROJECT_IDPlatform 项目的 UUID。MastraPlatformExporter 使用它将 Observability 数据关联到 platform 项目。Studio 和 Server 部署从 .mastra-project.json 读取项目 ID。
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT可选的 Observability endpoint 覆盖值。仅在本地开发 platform 时自动设置。默认为 https://observability.mastra.ai。
MASTRA_ORG_ID覆盖 CLI 命令使用的活跃组织。支持的命令也可以通过 --org 标志进行设置。

MastraPlatformExporter 读取 MASTRA_PLATFORM_ACCESS_TOKEN，对 platform export 进行身份验证。

多个环境
多个环境的直接链接

单个项目可以在多个环境（例如 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