name: render-deploy description: 将应用程序部署到Render，通过分析代码库、生成render.yaml蓝图并提供仪表板深度链接。当用户想要在Render的云平台上部署、托管、发布或设置其应用程序时使用。 author: openai

部署到Render

Render支持Git备份服务和预构建Docker镜像服务。

此技能涵盖Git备份流程：

蓝图方法 - 生成render.yaml用于基础设施即代码部署
直接创建 - 通过MCP工具即时创建服务

蓝图也可以通过使用runtime: image来运行预构建Docker镜像，但render.yaml仍必须存在于Git仓库中。

如果没有Git远程，停止并询问用户要么：

创建/推送Git远程（如果只需要蓝图，可以最小化），或
使用Render仪表板/API部署预构建Docker镜像（MCP无法创建镜像备份服务）。

先决条件

当沙箱阻止部署网络调用时，使用sandbox_permissions=require_escalated重新运行。
部署可能需要几分钟。使用适当的超时值。

何时使用此技能

当用户想要时激活此技能：

将应用程序部署到Render
创建render.yaml蓝图文件
为项目设置Render部署
在Render的云平台上托管或发布应用程序
创建数据库、定时任务或其他Render资源

快乐路径（新用户）

使用此短提示序列以减少摩擦：

询问他们是否想从Git仓库或预构建Docker镜像部署。
询问Render是否应提供应用程序所需的一切（基于用户描述中可能的情况）或仅提供应用程序，同时他们自带基础设施。如果依赖关系不明确，询问简短的后续问题以确认是否需要数据库、工作器、定时任务或其他服务。

然后继续下面的适当方法。

选择您的源路径

Git仓库路径： 蓝图和直接创建都需要。仓库必须推送到GitHub、GitLab或Bitbucket。

预构建Docker镜像路径： Render通过镜像备份服务支持。这不受MCP支持；使用仪表板/API。询问：

镜像URL（注册表 + 标签）
注册表认证（如果是私有的）
服务类型（web/工作器）和端口

如果用户选择Docker镜像，引导他们到Render仪表板镜像部署流程或要求他们添加Git远程（以便您可以使用带有runtime: image的蓝图）。

选择您的部署方法（Git仓库）

两种方法都需要推送到GitHub、GitLab或Bitbucket的Git仓库。（如果使用runtime: image，仓库可以最小化，只包含render.yaml。）

方法	最适合	优点
蓝图	多服务应用、IaC工作流	版本控制、可复制、支持复杂设置
直接创建	单服务、快速部署	即时创建、无需render.yaml文件

方法选择启发式

默认使用此决策规则，除非用户请求特定方法。首先分析代码库；仅当部署意图不明确时询问（例如，DB、工作器、定时任务）。

使用直接创建（MCP）当所有条件都满足：

单服务（一个Web应用或一个静态站点）
无单独的工作器/定时任务服务
无附加数据库或键值存储
仅简单环境变量（无共享环境组）如果此路径适合且MCP尚未配置，停止并引导MCP设置后再继续。

使用蓝图当任何条件为真：

多服务（Web + 工作器、API + 前端等）
需要数据库、Redis/键值存储或其他数据存储
定时任务、后台工作器或私有服务
您想要可复制的IaC或提交到仓库的render.yaml
单仓库或多环境设置需要一致配置

如果不确定，询问快速澄清问题，但为安全起见默认使用蓝图。对于单服务，强烈建议通过MCP直接创建，并在需要时引导MCP设置。

先决条件检查

开始部署时，按顺序验证这些要求：

1. 确认源路径（Git vs Docker）

如果使用Git基础方法（蓝图或直接创建），仓库必须推送到GitHub/GitLab/Bitbucket。引用预构建镜像的蓝图仍需要带有render.yaml的Git仓库。

git remote -v

如果不存在远程，停止并询问用户创建/推送远程或切换到Docker镜像部署。

2. 检查MCP工具可用性（单服务首选）

MCP工具提供最佳体验。通过尝试检查是否可用：

list_services()

如果MCP工具可用，您可以跳过CLI安装以进行大多数操作。

3. 检查Render CLI安装（用于蓝图验证）

render --version

如果未安装，提供安装：

macOS: brew install render
Linux/macOS: curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh

4. MCP设置（如果MCP未配置）

如果list_services()因MCP未配置而失败，询问他们是否想设置MCP（首选）或继续使用CLI备用。如果他们选择MCP，询问他们使用哪个AI工具，然后提供以下匹配说明。始终使用他们的API密钥。

Cursor

引导用户完成这些步骤：

获取Render API密钥：

https://dashboard.render.com/u/*/settings#api-keys

添加到~/.cursor/mcp.json（替换<YOUR_API_KEY>）：

{
  "mcpServers": {
    "render": {
      "url": "https://mcp.render.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

重启Cursor，然后重试list_services()。

Claude Code

引导用户完成这些步骤：

获取Render API密钥：

https://dashboard.render.com/u/*/settings#api-keys

使用Claude Code添加MCP服务器（替换<YOUR_API_KEY>）：

claude mcp add --transport http render https://mcp.render.com/mcp --header "Authorization: Bearer <YOUR_API_KEY>"

重启Claude Code，然后重试list_services()。

Codex

引导用户完成这些步骤：

获取Render API密钥：

https://dashboard.render.com/u/*/settings#api-keys

在shell中设置：

export RENDER_API_KEY="<YOUR_API_KEY>"

使用Codex CLI添加MCP服务器：

codex mcp add render --url https://mcp.render.com/mcp --bearer-token-env-var RENDER_API_KEY

重启Codex，然后重试list_services()。

其他工具

如果用户使用其他AI应用，引导他们到Render MCP文档以获取该工具的设置步骤和安装方法。

工作空间选择

MCP配置后，让用户设置活动Render工作空间，如：

设置我的Render工作空间为[WORKSPACE_NAME]

5. 检查认证（仅CLI备用）

如果MCP不可用，使用CLI并验证您可以访问您的账户：

# 检查用户是否登录（使用-o json进行非交互模式）
render whoami -o json

如果render whoami失败或返回空数据，CLI未认证。CLI不会总是自动提示，因此明确提示用户认证：

如果两者都未配置，询问用户偏好哪种方法：

API密钥（CLI）: export RENDER_API_KEY="rnd_xxxxx"（从https://dashboard.render.com/u/*/settings#api-keys获取）
登录: render login（打开浏览器进行OAuth）

**6. 检查工作空间上下文

验证活动工作空间：

get_selected_workspace()

或通过CLI：

render workspace current -o json

列出可用工作空间：

list_workspaces()

如果用户需要切换工作空间，他们必须通过仪表板或CLI（render workspace set）进行。

一旦先决条件满足，继续部署工作流。

方法1：蓝图部署（推荐用于复杂应用）

蓝图工作流

步骤1：分析代码库

分析代码库以确定框架/运行时、构建和启动命令、所需环境变量、数据存储和端口绑定。使用references/codebase-analysis.md中的详细清单。

步骤2：生成render.yaml

创建render.yaml蓝图文件，遵循蓝图规范。

完整规范：references/blueprint-spec.md

关键点：

除非用户指定，否则始终使用plan: free
包括应用程序需要的所有环境变量
使用sync: false标记秘密（用户在仪表板中填写）
使用适当的服务类型：web、worker、cron、static或pserv
使用适当的运行时：references/runtimes.md

基本结构：

services:
  - type: web
    name: my-app
    runtime: node
    plan: free
    buildCommand: npm ci
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: postgres
          property: connectionString
      - key: JWT_SECRET
        sync: false  # 用户在仪表板中填写

databases:
  - name: postgres
    databaseName: myapp_db
    plan: free

服务类型：

web: HTTP服务、API、Web应用（公开可访问）
worker: 后台作业处理器（不公开可访问）
cron: 按cron计划运行的定时任务
static: 静态站点（通过CDN提供的HTML/CSS/JS）
pserv: 私有服务（仅内部，同一账户内）

服务类型详情：references/service-types.md 运行时选项：references/runtimes.md 模板示例：assets/

步骤2.5：立即下一步（始终提供）

创建render.yaml后，始终给用户一个简短、明确的清单，并在CLI可用时立即运行验证：

认证（CLI）: 运行render whoami -o json（如果未登录，运行render login或设置RENDER_API_KEY）
验证（推荐）: 运行render blueprints validate
- 如果CLI未安装，提供安装命令。
提交 + 推送: git add render.yaml && git commit -m "添加Render部署配置" && git push origin main
打开仪表板: 使用蓝图深度链接并完成Git OAuth如果提示
填写秘密: 设置标记为sync: false的环境变量
部署: 点击“应用”并监控部署

步骤3：验证配置

验证render.yaml文件以在部署前捕获错误。如果CLI已安装，直接运行命令；仅当CLI缺失时提示用户：

render whoami -o json  # 确保CLI已认证（不会总是提示）
render blueprints validate

修复任何验证错误后再继续。常见问题：

缺少必需字段（name、type、runtime）
无效的运行时值
错误的YAML语法
无效的环境变量引用

配置指南：references/configuration-guide.md

步骤4：提交和推送

重要： 在部署之前，必须将render.yaml文件合并到您的仓库中。

确保render.yaml文件已提交并推送到您的Git远程：

git add render.yaml
git commit -m "添加Render部署配置"
git push origin main

如果尚不存在Git远程，停止此处并引导用户创建GitHub/GitLab/Bitbucket仓库，添加为origin，并在继续前推送。

为什么重要： 仪表板深度链接将从您的仓库读取render.yaml。如果文件未合并和推送，Render将找不到配置，部署将失败。

在继续下一步之前，验证文件在您的远程仓库中。

步骤5：生成深度链接

获取Git仓库URL：

git remote get-url origin

这将返回来自您的Git提供商的URL。如果URL是SSH格式，转换为HTTPS：

SSH格式	HTTPS格式
`git@github.com:user/repo.git`	`https://github.com/user/repo`
`git@gitlab.com:user/repo.git`	`https://gitlab.com/user/repo`
`git@bitbucket.org:user/repo.git`	`https://bitbucket.org/user/repo`

转换模式： 用https://<host>/替换git@<host>:并移除.git后缀。

使用HTTPS仓库URL格式化仪表板深度链接：

https://dashboard.render.com/blueprint/new?repo=<REPOSITORY_URL>

示例：

https://dashboard.render.com/blueprint/new?repo=https://github.com/username/repo-name

步骤6：引导用户

关键： 确保用户在点击深度链接之前已将render.yaml文件合并并推送到他们的仓库。如果文件不在仓库中，Render无法读取蓝图配置，部署将失败。

向用户提供深度链接及以下说明：

验证render.yaml已合并 - 确认文件存在于GitHub/GitLab/Bitbucket上的仓库中
点击深度链接以打开Render仪表板
如果提示，完成Git提供商OAuth
命名蓝图（或使用render.yaml中的默认值）
填写秘密环境变量（标记为sync: false）
审查服务和数据库配置
点击“应用”以部署

部署将自动开始。用户可以在Render仪表板中监控进度。

步骤7：验证部署

用户通过仪表板部署后，验证一切正常。

通过MCP检查部署状态：

list_deploys(serviceId: "<service-id>", limit: 1)

查找status: "live"以确认成功部署。

检查运行时错误（部署后等待2-3分钟）：

list_logs(resource: ["<service-id>"], level: ["error"], limit: 20)

检查服务健康指标：

get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_request_count", "cpu_usage", "memory_usage"]
)

如果发现错误，继续到下面的部署后验证和基本故障排除部分。

方法2：直接服务创建（快速单服务部署）

对于没有基础设施即代码的简单部署，直接通过MCP工具创建服务。

何时使用直接创建

单Web服务或静态站点
快速原型或演示
当您不需要仓库中的render.yaml文件时
向现有项目添加数据库或定时任务

直接创建的先决条件

仓库必须推送到Git提供商。 Render克隆您的仓库以构建和部署服务。

git remote -v  # 验证远程存在
git push origin main  # 确保代码已推送

支持提供商：GitHub、GitLab、Bitbucket

如果不存在远程，停止并询问用户创建/推送远程或切换到Docker镜像部署。

注意： MCP不支持创建镜像备份服务。使用仪表板/API进行预构建Docker镜像部署。

直接创建工作流

使用以下简洁步骤，并参考references/direct-creation.md获取完整MCP命令示例和后续配置。

步骤1：分析代码库

使用references/codebase-analysis.md确定运行时、构建/启动命令、环境变量和数据存储。

步骤2：通过MCP创建资源

创建服务（Web或静态）和任何所需的数据库或键值存储。见references/direct-creation.md。

如果MCP返回有关缺少Git凭据或仓库访问的错误，停止并引导用户在Render仪表板中连接他们的Git提供商，然后重试。

步骤3：配置环境变量

创建后通过MCP添加所需环境变量。见references/direct-creation.md。

提醒用户，如果他们不想通过MCP传递秘密，可以在仪表板中设置秘密。

步骤4：验证部署

检查部署状态、日志和指标。见references/direct-creation.md。

对于服务发现、配置详情、快速命令和常见问题，见references/deployment-details.md。

部署后验证和基本故障排除（所有方法）

保持简短且可重复。如果任何检查失败，在重新部署前修复它。

确认最新部署是live并正在服务流量
访问健康端点（或根）并验证200响应
扫描最近错误日志以寻找清晰的失败签名
验证所需环境变量和端口绑定（0.0.0.0:$PORT）

详细清单和命令：references/post-deploy-checks.md

如果服务无法启动或健康检查超时，使用基本故障排除指南： references/troubleshooting-basics.md

故障排除

升级网络访问

如果部署因网络问题失败（超时、DNS错误、连接重置），使用升级权限重新运行部署（使用sandbox_permissions=require_escalated）。当沙箱网络阻止出站请求时，部署需要升级网络访问。

向用户的示例指导：

部署需要升级网络访问以部署到Render。我可以使用升级权限重新运行命令—想要我继续吗？

可选：如果您需要深入诊断（指标/数据库检查/错误目录），建议安装render-debug技能。对于核心部署流程不是必需的。