Mastra Cloud 部署器（@mastra/deployer-cloud）完全指南：从打包到生产运行环境变量

Mastra Cloud 部署器（@mastra/deployer-cloud）完全指南：从打包到生产运行环境变量

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

Mastra Cloud 部署器是 Mastra 生态中专为云端运行时优化的部署组件，负责把本地 Mastra 应用打包成 Mastra Cloud 可直接运行的服务端产物。本文以deployers/cloud/README.md为骨架，结合源码与测试详细讲解CloudDeployer的安装、打包流程、生成的服务端入口行为、认证接入与全部运行时环境变量，帮助你理解一次deployer.bundle()调用背后发生了什么，以及如何在自托管或 CI 场景中正确配置它。

一、CloudDeployer 是什么：职责与定位

@mastra/deployer-cloud是一个面向 Mastra Cloud 的部署器包。它的核心类是CloudDeployer，继承自@mastra/deployer提供的Deployer抽象基类（对应源码 deployers/cloud/src/index.ts）。它不负责上传代码，而是负责在构建阶段生成"能被 Mastra Cloud 拉起来运行"的产物。其职责可归纳为六件事：

1. 发现 Mastra 入口文件：自动定位应用的src/mastra/index.ts（或index.js）；
2. 发现并暴露工具：通过getAllToolPaths收集应用声明的所有工具路径；
3. 生成生产级服务端入口：内联生成一段包含日志、存储、认证、可观测性的服务端引导代码；
4. 保持 npm 依赖外部化：云端部署器强制externals: true，所有依赖由 npm 安装进node_modules，而非打进 bundle；
5. 写入部署包 manifest：生成服务器package.json（含云端所需的额外依赖）；
6. 安装依赖：在输出目录中执行依赖安装。

二、安装与最小用法

安装命令（参见 deployers/cloud/README.md）：

npm install @mastra/deployer-cloud

该包作为 Mastra 构建流程的一环使用（README）：

import { CloudDeployer } from '@mastra/deployer-cloud'; const deployer = new CloudDeployer({ studio: false }); await deployer.bundle('./src/mastra', './.mastra/output');

bundle(mastraDir, outputDirectory)是入口方法（src/index.ts），它的执行顺序是：

1. 将进程工作目录切换为mastraDir（打包完成后恢复原 cwd，测试 src/index.test.ts 专门验证了 chdir 的成对调用）；
2. 通过getMastraEntryFile找到应用入口（src/utils/file.ts，在MASTRA_DIRECTORY下依次查找index.ts、index.js，找不到时抛出MASTRA_ENTRY_FILE_NOT_FOUND错误）；
3. 用getAllToolPaths收集src/mastra目录下的工具路径；
4. 调用prepare(outputDirectory)清理并重建输出目录（基类prepare会emptyDir后重建.build与output两个子目录，见 packages/deployer/src/bundler/index.ts）；
5. 调用基类_bundle将内联生成的服务端入口与发现的工具一起打包。

版本与环境前提：包要求Node >= 22.13.0，并以@mastra/core >= 1.50.0-0 < 2.0.0-0作为 peer dependency（见 package.json）。测试套件共 67 个用例、分布在 5 个测试文件中，覆盖从构建配置到服务端运行时初始化的完整链路（详见 TEST_DOCUMENTATION.md）。

关于studio选项

CloudDeployer构造函数接受一个可选参数studio，默认值为false（src/index.ts）：

new CloudDeployer(); // studio: false new CloudDeployer({ studio: false }); // 显式关闭 new CloudDeployer({ studio: true }); // 复制并托管 Studio 静态资源

• studio: true时，prepare阶段会把dist/studio目录拷贝到输出目录的output/studio下（src/index.ts），同时生成的服务端入口会以studio: true调用createNodeServer；
• 无论studio取值如何，生成的服务器始终关闭 Swagger UI（swaggerUI: false）。测试用例对此有明确断言（src/index.test.ts）。

三、打包行为：强制外部化依赖的底层原因

CloudDeployer覆写了getUserBundlerOptions，无条件将externals置为true（src/index.ts）。源码注释解释了这一设计的两点原因：

1. 云端会从 npm 安装全部依赖到node_modules，因此把依赖内联进 bundle 毫无意义；
2. 内联打包可能引发循环模块求值死锁：当动态导入（例如MemoryLibSQL.init()）引用的 chunk 又反向依赖入口模块时，会出现 "Detected unsettled top-level await" 警告。

除此之外，writePackageJson会从包内的versions.json读取云端运行时所需的固定版本依赖并注入依赖表（src/index.ts），随后调用基类写出服务器package.json。基类生成的 manifest 结构（packages/deployer/src/bundler/index.ts）为：

{ "name": "server", "version": "1.0.0", "private": true, "type": "module", "main": "index.mjs", "scripts": { "start": "node ./index.mjs" }, "dependencies": { } }

依赖安装使用npm install --legacy-peer-deps=false --force在<outputDirectory>/output目录中执行（src/index.ts）。其中--force是为了在输出目录安装外部 peer 依赖，--legacy-peer-deps=false则是为了覆盖仓库包管理器（如 pnpm）可能设置的相关 override（见 src/utils/deps.ts）。

deploy()与lint()两个方法当前均为空实现（no-op），测试中对此有明确覆盖（src/index.test.ts、[L174-L178]）。

四、生成的服务端入口：一份内联引导代码做了什么

getEntry()（src/index.ts）以字符串模板形式生成完整的服务端引导代码。它是理解整个部署器行为的关键，主要环节如下：

1. 就绪（READINESS）事件：启动时、启动完成后、Runner 初始化完成时分别输出三份 JSON 结构化日志，均包含type: "READINESS"、启动时间，以及teamId、projectId、buildId元数据。RUNNER_START_TIME环境变量用于计算启动耗时。

2. 日志传输：只有CI !== 'true'时才会注册远端日志传输；若同时设置了BUSINESS_API_RUNNER_LOGS_ENDPOINT，则以BUSINESS_JWT_TOKEN作为 Bearer Token 创建HttpTransport。最终通过MultiLogger把云端PinoLogger与应用自身 logger 合并后交给mastra.setLogger()。

3. 存储初始化：这是典型的"云优先、应用兜底"双分支逻辑（src/index.ts）：

• 当MASTRA_STORAGE_URL与MASTRA_STORAGE_AUTH_TOKEN同时存在时，创建LibSQLStore与LibSQLVector（同一个 URL 与 Token），init()后替换应用的 storage；
• 否则回退到应用自身配置的 storage，并在其未设置disableInit时调用init()。

4. 内部 trace 评分工作流：只要mastra.getStorage()存在，就注册内部工作流scoreTracesWorkflow（@mastra/core/evals/scoreTraces），这是 trace 评分的内部支撑机制。

5. 服务端启动：以studio选项、swaggerUI: false、tools: getToolExports(tools)调用createNodeServer(mastra, ...)。

对应地，src/server-runtime.test.ts（13 个用例）会验证生成的入口代码中包含全部必需 import、环境变量引用、PinoLogger配置、LibSQL 存储初始化、READINESS 日志以及缺失组件时的可选链容错。

云认证入口：Service Auth 与 Cloud User Auth

生成的代码还会注入认证入口（getAuthEntrypoint，src/utils/auth.ts），核心逻辑：

• Service Auth（服务间认证）：基于PLAYGROUND_JWT_TOKEN与BUSINESS_JWT_TOKEN构建SimpleAuth，允许 business-api/playground 内部调用，并放行/api路径；
• Cloud User Auth（终端用户 OAuth）：仅当设置了MASTRA_CLOUD_API_URL时启用，通过MastraCloudAuthProvider接入云账号体系，回调地址可用MASTRA_CLOUD_CALLBACK_URL覆盖（默认拼接${MASTRA_CLOUD_API_URL}/auth/callback）；
• 两者连同应用自定义认证共同组成CompositeAuth提供者链；
• 启用云用户认证但应用未配置 RBAC 时，自动注入MastraRBACCloud默认角色映射（owner/admin/api/member/viewer）。

五、运行时环境变量全表

以下环境变量由 README 声明，其具体消费位置可在 src/index.ts 与 src/utils/constants.ts 中逐一确认：

除上述之外，构建器自身还会消费一组可选变量：BUILD_URL、USER_IP_ADDRESS会随构建状态上报给监控服务（REPORTER_API_URL/REPORTER_API_URL_AUTH_TOKEN，见 src/utils/report.ts）；LOG_REDIS_URL用于构建期日志的 Redis 传输（默认redis://localhost:6379，src/utils/logger.ts）。CI=true会同时跳过构建状态上报，避免 CI 构建污染线上监控数据。

六、测试与质量保障

云端部署器的测试套件总计67 个用例 / 5 个文件，可从 deployers/cloud/src 查看源码，运行方式（TEST_DOCUMENTATION.md）：

pnpm test # 运行全部测试 pnpm test:watch # watch 模式 pnpm test src/index.test.ts # 只跑单个文件

各测试文件的关注点：

• src/index.test.ts（17 个）：构造器默认值、deploy/lintno-op、package.json云依赖注入、bundle的 chdir 与工具路径收集、生成入口代码的 import/环境变量/READINESS 日志断言、错误路径；
• src/server-runtime.test.ts（13 个）：运行时引导代码的环境变量处理、日志配置、存储初始化与钩子注册；
• src/utils/file.test.ts（4 个）：入口文件查找与错误抛出；
• src/utils/deps.test.ts（22 个）：包管理器检测（npm/pnpm/yarn/bun）、锁文件向上递归查找、检测结果缓存、.nvmrc/.node-version版本安装、依赖安装参数与各类MastraError错误码；
• src/integration.test.ts（11 个）：端到端打包工作流、instrumentation 文件、完整package.json生成与错误恢复。

七、小结：一次部署的背后

new CloudDeployer({ studio }).bundle(src, out)一次调用背后，实际发生的是：切换工作目录 → 定位 Mastra 入口 → 收集工具 → 生成带日志/存储/认证/就绪事件的服务端引导代码 → 强制外部化依赖打包 → 写入服务器 manifest 并注入云依赖 → npm 安装依赖。而生产环境中真正决定行为的，是MASTRA_STORAGE_*、BUSINESS_API_RUNNER_LOGS_ENDPOINT、BUSINESS_JWT_TOKEN、TEAM_ID/PROJECT_ID/BUILD_ID与CI这组运行时变量——它们共同保证了日志可达、存储可替换、就绪可观测、CI 不误报。理解这层契约后，无论是排查云端启动问题，还是定制自托管部署，你都能从环境变量与生成入口代码两个层面快速定位。

版本历史与发布说明可查阅包的 CHANGELOG，完整实现可继续阅读 deployers/cloud/src 与基类 packages/deployer/src/bundler/index.ts。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra