Mastra Cloud 部署器mastra/deployer-cloud完全指南从打包到生产运行环境变量【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 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 拉起来运行的产物。其职责可归纳为六件事发现 Mastra 入口文件自动定位应用的src/mastra/index.ts或index.js发现并暴露工具通过getAllToolPaths收集应用声明的所有工具路径生成生产级服务端入口内联生成一段包含日志、存储、认证、可观测性的服务端引导代码保持 npm 依赖外部化云端部署器强制externals: true所有依赖由 npm 安装进node_modules而非打进 bundle写入部署包 manifest生成服务器package.json含云端所需的额外依赖安装依赖在输出目录中执行依赖安装。二、安装与最小用法安装命令参见 deployers/cloud/README.mdnpm install mastra/deployer-cloud该包作为 Mastra 构建流程的一环使用READMEimport { CloudDeployer } from mastra/deployer-cloud; const deployer new CloudDeployer({ studio: false }); await deployer.bundle(./src/mastra, ./.mastra/output);bundle(mastraDir, outputDirectory)是入口方法src/index.ts它的执行顺序是将进程工作目录切换为mastraDir打包完成后恢复原 cwd测试 src/index.test.ts 专门验证了 chdir 的成对调用通过getMastraEntryFile找到应用入口src/utils/file.ts在MASTRA_DIRECTORY下依次查找index.ts、index.js找不到时抛出MASTRA_ENTRY_FILE_NOT_FOUND错误用getAllToolPaths收集src/mastra目录下的工具路径调用prepare(outputDirectory)清理并重建输出目录基类prepare会emptyDir后重建.build与output两个子目录见 packages/deployer/src/bundler/index.ts调用基类_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默认值为falsesrc/index.tsnew 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 UIswaggerUI: false。测试用例对此有明确断言src/index.test.ts。三、打包行为强制外部化依赖的底层原因CloudDeployer覆写了getUserBundlerOptions无条件将externals置为truesrc/index.ts。源码注释解释了这一设计的两点原因云端会从 npm 安装全部依赖到node_modules因此把依赖内联进 bundle 毫无意义内联打包可能引发循环模块求值死锁当动态导入例如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-depsfalse --force在outputDirectory/output目录中执行src/index.ts。其中--force是为了在输出目录安装外部 peer 依赖--legacy-peer-depsfalse则是为了覆盖仓库包管理器如 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 与 Tokeninit()后替换应用的 storage否则回退到应用自身配置的 storage并在其未设置disableInit时调用init()。4. 内部 trace 评分工作流只要mastra.getStorage()存在就注册内部工作流scoreTracesWorkflowmastra/core/evals/scoreTraces这是 trace 评分的内部支撑机制。5. 服务端启动以studio选项、swaggerUI: false、tools: getToolExports(tools)调用createNodeServer(mastra, ...)。对应地src/server-runtime.test.ts13 个用例会验证生成的入口代码中包含全部必需 import、环境变量引用、PinoLogger配置、LibSQL 存储初始化、READINESS 日志以及缺失组件时的可选链容错。云认证入口Service Auth 与 Cloud User Auth生成的代码还会注入认证入口getAuthEntrypointsrc/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 中逐一确认环境变量用途消费位置MASTRA_STORAGE_URL托管存储的 LibSQL URL与MASTRA_STORAGE_AUTH_TOKEN成对出现才生效src/index.tsMASTRA_STORAGE_AUTH_TOKEN托管存储的认证 Token同上BUSINESS_API_RUNNER_LOGS_ENDPOINT云端日志传输的 HTTP 端点src/index.tsBUSINESS_JWT_TOKEN日志传输的 Bearer Token同时用于 Service Auth同上及 src/utils/auth.tsPLAYGROUND_JWT_TOKENPlayground 内部调用的 Service Tokensrc/utils/auth.tsRUNNER_START_TIMERunner 启动时间用于计算就绪耗时src/index.tsTEAM_ID/PROJECT_ID/BUILD_IDREADINESS 事件中的部署元数据src/utils/constants.tsCItrue关闭远端日志传输与构建状态上报CI 构建场景src/index.ts、src/utils/report.tsMASTRA_CLOUD_API_URL启用云用户 OAuth 认证的开关src/utils/auth.tsMASTRA_CLOUD_CALLBACK_URL云用户认证回调地址覆盖同上MASTRA_DIRECTORY覆盖默认的src/mastra应用目录src/utils/constants.ts除上述之外构建器自身还会消费一组可选变量BUILD_URL、USER_IP_ADDRESS会随构建状态上报给监控服务REPORTER_API_URL/REPORTER_API_URL_AUTH_TOKEN见 src/utils/report.tsLOG_REDIS_URL用于构建期日志的 Redis 传输默认redis://localhost:6379src/utils/logger.ts。CItrue会同时跳过构建状态上报避免 CI 构建污染线上监控数据。六、测试与质量保障云端部署器的测试套件总计67 个用例 / 5 个文件可从 deployers/cloud/src 查看源码运行方式TEST_DOCUMENTATION.mdpnpm test # 运行全部测试 pnpm test:watch # watch 模式 pnpm test src/index.test.ts # 只跑单个文件各测试文件的关注点src/index.test.ts17 个构造器默认值、deploy/lintno-op、package.json云依赖注入、bundle的 chdir 与工具路径收集、生成入口代码的 import/环境变量/READINESS 日志断言、错误路径src/server-runtime.test.ts13 个运行时引导代码的环境变量处理、日志配置、存储初始化与钩子注册src/utils/file.test.ts4 个入口文件查找与错误抛出src/utils/deps.test.ts22 个包管理器检测npm/pnpm/yarn/bun、锁文件向上递归查找、检测结果缓存、.nvmrc/.node-version版本安装、依赖安装参数与各类MastraError错误码src/integration.test.ts11 个端到端打包工作流、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/mastraMastra 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 拉起来运行的产物。其职责可归纳为六件事发现 Mastra 入口文件自动定位应用的src/mastra/index.ts或index.js发现并暴露工具通过getAllToolPaths收集应用声明的所有工具路径生成生产级服务端入口内联生成一段包含日志、存储、认证、可观测性的服务端引导代码保持 npm 依赖外部化云端部署器强制externals: true所有依赖由 npm 安装进node_modules而非打进 bundle写入部署包 manifest生成服务器package.json含云端所需的额外依赖安装依赖在输出目录中执行依赖安装。二、安装与最小用法安装命令参见 deployers/cloud/README.mdnpm install mastra/deployer-cloud该包作为 Mastra 构建流程的一环使用READMEimport { CloudDeployer } from mastra/deployer-cloud; const deployer new CloudDeployer({ studio: false }); await deployer.bundle(./src/mastra, ./.mastra/output);bundle(mastraDir, outputDirectory)是入口方法src/index.ts它的执行顺序是将进程工作目录切换为mastraDir打包完成后恢复原 cwd测试 src/index.test.ts 专门验证了 chdir 的成对调用通过getMastraEntryFile找到应用入口src/utils/file.ts在MASTRA_DIRECTORY下依次查找index.ts、index.js找不到时抛出MASTRA_ENTRY_FILE_NOT_FOUND错误用getAllToolPaths收集src/mastra目录下的工具路径调用prepare(outputDirectory)清理并重建输出目录基类prepare会emptyDir后重建.build与output两个子目录见 packages/deployer/src/bundler/index.ts调用基类_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默认值为falsesrc/index.tsnew 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 UIswaggerUI: false。测试用例对此有明确断言src/index.test.ts。三、打包行为强制外部化依赖的底层原因CloudDeployer覆写了getUserBundlerOptions无条件将externals置为truesrc/index.ts。源码注释解释了这一设计的两点原因云端会从 npm 安装全部依赖到node_modules因此把依赖内联进 bundle 毫无意义内联打包可能引发循环模块求值死锁当动态导入例如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-depsfalse --force在outputDirectory/output目录中执行src/index.ts。其中--force是为了在输出目录安装外部 peer 依赖--legacy-peer-depsfalse则是为了覆盖仓库包管理器如 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 与 Tokeninit()后替换应用的 storage否则回退到应用自身配置的 storage并在其未设置disableInit时调用init()。4. 内部 trace 评分工作流只要mastra.getStorage()存在就注册内部工作流scoreTracesWorkflowmastra/core/evals/scoreTraces这是 trace 评分的内部支撑机制。5. 服务端启动以studio选项、swaggerUI: false、tools: getToolExports(tools)调用createNodeServer(mastra, ...)。对应地src/server-runtime.test.ts13 个用例会验证生成的入口代码中包含全部必需 import、环境变量引用、PinoLogger配置、LibSQL 存储初始化、READINESS 日志以及缺失组件时的可选链容错。云认证入口Service Auth 与 Cloud User Auth生成的代码还会注入认证入口getAuthEntrypointsrc/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 中逐一确认环境变量用途消费位置MASTRA_STORAGE_URL托管存储的 LibSQL URL与MASTRA_STORAGE_AUTH_TOKEN成对出现才生效src/index.tsMASTRA_STORAGE_AUTH_TOKEN托管存储的认证 Token同上BUSINESS_API_RUNNER_LOGS_ENDPOINT云端日志传输的 HTTP 端点src/index.tsBUSINESS_JWT_TOKEN日志传输的 Bearer Token同时用于 Service Auth同上及 src/utils/auth.tsPLAYGROUND_JWT_TOKENPlayground 内部调用的 Service Tokensrc/utils/auth.tsRUNNER_START_TIMERunner 启动时间用于计算就绪耗时src/index.tsTEAM_ID/PROJECT_ID/BUILD_IDREADINESS 事件中的部署元数据src/utils/constants.tsCItrue关闭远端日志传输与构建状态上报CI 构建场景src/index.ts、src/utils/report.tsMASTRA_CLOUD_API_URL启用云用户 OAuth 认证的开关src/utils/auth.tsMASTRA_CLOUD_CALLBACK_URL云用户认证回调地址覆盖同上MASTRA_DIRECTORY覆盖默认的src/mastra应用目录src/utils/constants.ts除上述之外构建器自身还会消费一组可选变量BUILD_URL、USER_IP_ADDRESS会随构建状态上报给监控服务REPORTER_API_URL/REPORTER_API_URL_AUTH_TOKEN见 src/utils/report.tsLOG_REDIS_URL用于构建期日志的 Redis 传输默认redis://localhost:6379src/utils/logger.ts。CItrue会同时跳过构建状态上报避免 CI 构建污染线上监控数据。六、测试与质量保障云端部署器的测试套件总计67 个用例 / 5 个文件可从 deployers/cloud/src 查看源码运行方式TEST_DOCUMENTATION.mdpnpm test # 运行全部测试 pnpm test:watch # watch 模式 pnpm test src/index.test.ts # 只跑单个文件各测试文件的关注点src/index.test.ts17 个构造器默认值、deploy/lintno-op、package.json云依赖注入、bundle的 chdir 与工具路径收集、生成入口代码的 import/环境变量/READINESS 日志断言、错误路径src/server-runtime.test.ts13 个运行时引导代码的环境变量处理、日志配置、存储初始化与钩子注册src/utils/file.test.ts4 个入口文件查找与错误抛出src/utils/deps.test.ts22 个包管理器检测npm/pnpm/yarn/bun、锁文件向上递归查找、检测结果缓存、.nvmrc/.node-version版本安装、依赖安装参数与各类MastraError错误码src/integration.test.ts11 个端到端打包工作流、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考