render-deploy

部署到 Render

Render 支持基于 Git 的服务和预构建 Docker 镜像服务。

此技能涵盖基于 Git 的流程：

1. Blueprint 方法——生成 render.yaml，用于基础设施即代码部署
2. 直接创建——通过 MCP 工具即时创建服务

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

如果没有 Git 远程仓库，请停止并询问用户是否选择：

• 创建/推送 Git 远程仓库（如果只需要 Blueprint，可以是最精简的仓库），或
• 使用 Render Dashboard/API 部署预构建 Docker 镜像（MCP 无法创建基于镜像的服务）。

先决条件

• 如果沙盒阻止了部署网络调用，请使用 sandbox_permissions=require_escalated 重新运行。
• 部署可能需要几分钟。请使用合适的超时值。

何时使用此技能

当用户希望进行以下操作时，启用此技能：

• 将应用部署到 Render
• 创建 render.yaml Blueprint 文件
• 为其项目设置 Render 部署
• 在 Render 云平台上托管或发布其应用
• 创建数据库、Cron 作业或其他 Render 资源

快速开始（新用户）

在深入分析前，使用以下简短提问流程来减少阻碍：

1. 询问他们想从 Git 仓库部署，还是使用预构建 Docker 镜像。
2. 根据用户的描述，询问 Render 是否应配置应用所需的全部资源，还是只配置应用、由他们自行提供基础设施。如果依赖项不明确，请简短追问，确认他们是否需要数据库、工作进程、Cron 或其他服务。

然后使用下方相应的方法继续操作。

选择源路径

Git 仓库路径： Blueprint 和直接创建都必须使用此路径。仓库必须已推送到 GitHub、GitLab 或 Bitbucket。

预构建 Docker 镜像路径： Render 支持通过基于镜像的服务部署。MCP 不支持此方式；请使用 Dashboard/API。询问以下信息：

• 镜像 URL（注册表 + 标签）
• 注册表身份验证信息（如果是私有镜像）
• 服务类型（web/worker）和端口

如果用户选择 Docker 镜像，请引导他们使用 Render Dashboard 的镜像部署流程，或让他们添加 Git 远程仓库（这样你就可以使用包含 runtime: image 的 Blueprint）。

选择部署方法（Git 仓库）

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

方法	最适用场景	优点
Blueprint	多服务应用、IaC 工作流	受版本控制、可复现、支持复杂配置
直接创建	单个服务、快速部署	即时创建，无需 render.yaml 文件

方法选择启发规则

除非用户指定方法，否则默认使用以下决策规则。先分析代码库；只有在部署意图不明确时（例如数据库、工作进程、Cron）才提问。

满足以下所有条件时，使用直接创建（MCP）：

• 单个服务（一个 Web 应用或一个静态站点）
• 没有独立的工作进程/Cron 服务
• 没有附加数据库或 Key Value
• 仅使用简单的环境变量（没有共享环境变量组） 如果符合此路径且尚未配置 MCP，请停止并引导用户先设置 MCP。

满足以下任一条件时，使用 Blueprint：

• 多个服务（Web + 工作进程、API + 前端等）
• 需要数据库、Redis/Key Value 或其他数据存储
• Cron 作业、后台工作进程或私有服务
• 需要可复现的 IaC，或需要将 render.yaml 提交到仓库
• 需要一致配置的 Monorepo 或多环境设置

如果不确定，请快速提出澄清问题，但默认使用 Blueprint 以确保安全。对于单个服务，强烈建议通过 MCP 直接创建；如有需要，引导用户设置 MCP。

前置条件检查

开始部署时，请按顺序确认以下要求：

1. 确认源路径（Git 还是 Docker）

如果使用基于 Git 的方法（Blueprint 或直接创建），代码仓库必须已推送到 GitHub/GitLab/Bitbucket。引用预构建镜像的 Blueprint 仍需要包含 render.yaml 的 Git 仓库。

git remote -v

• 如果没有远程仓库，请停止操作，并让用户创建/推送远程仓库，或改用 Docker 镜像部署。

2. 检查 MCP 工具是否可用（单服务场景优先）

MCP 工具能提供最佳体验。尝试以下操作，检查其是否可用：

list_services()

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

3. 检查是否已安装 Render CLI（用于 Blueprint 验证）

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

逐步引导用户完成以下操作：

1. 获取 Render API 密钥：

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

2. 将以下内容添加到 ~/.cursor/mcp.json（替换 <YOUR_API_KEY>）：

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

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

Claude Code

逐步引导用户完成以下操作：

1. 获取 Render API 密钥：

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

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

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

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

Codex

逐步引导用户完成以下操作：

1. 获取 Render API 密钥：

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

2. 在其 shell 中设置密钥：

export RENDER_API_KEY="<YOUR_API_KEY>"

3. 使用 Codex CLI 添加 MCP 服务：

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

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

其他工具

如果用户使用其他 AI 应用，请引导他们查看 Render MCP 文档，了解该工具的设置步骤和安装方法。

工作区选择

配置好 MCP 后，请让用户设置当前 Render 工作区，可以使用类似以下的提示词：

Set my Render workspace to [WORKSPACE_NAME]

5. 检查身份验证（仅限 CLI 备用方案）

如果 MCP 不可用，请改用 CLI，并确认可以访问用户的账户：

# Check if user is logged in (use -o json for non-interactive mode)
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()

如果用户需要切换工作区，必须通过 Dashboard 或 CLI（render workspace set）操作。

满足前置条件后，继续部署工作流。

---

方法 1：Blueprint 部署（复杂应用推荐）

Blueprint 工作流

步骤 1：分析代码库

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

步骤 2：生成 render.yaml

按照 Blueprint 规范创建 render.yaml Blueprint 文件。

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

要点：

• 除非用户另有指定，否则始终使用 plan: free
• 包含应用所需的所有环境变量
• 使用 sync: false 标记机密（由用户在 Dashboard 中填写）
• 选择适当的服务类型：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  # User fills in Dashboard

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 可用，立即运行验证：

1. 身份验证（CLI）：运行 render whoami -o json（如果尚未登录，运行 render login 或设置 RENDER_API_KEY）
2. 验证（推荐）：运行 render blueprints validate
   • 如果尚未安装 CLI，询问用户是否要安装，并提供安装命令。
3. 提交并推送：git add render.yaml && git commit -m "Add Render deployment configuration" && git push origin main
4. 打开 Dashboard：使用 Blueprint 深层链接；如果出现提示，请完成 Git OAuth
5. 填写机密：设置标记为 sync: false 的环境变量
6. 部署：点击“Apply”并监控部署

步骤 3：验证配置

验证 render.yaml 文件，在部署前发现错误。如果已安装 CLI，直接运行命令；只有在 CLI 缺失时才提示用户：

render whoami -o json  # Ensure CLI is authenticated (won't always prompt)
render blueprints validate

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

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

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

步骤 4：提交并推送

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

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

git add render.yaml
git commit -m "Add Render deployment configuration"
git push origin main

如果尚无 Git 远程仓库，请在此处停止，并指导用户创建 GitHub/GitLab/Bitbucket 仓库，将其添加为 origin，然后推送，再继续操作。

原因： Dashboard 深层链接会从仓库中读取 render.yaml。如果文件尚未合并并推送，Render 将无法找到配置，部署也会失败。

继续下一步之前，请确认远程仓库中已包含该文件。

步骤 5：生成深层链接

获取 Git 仓库 URL：

git remote get-url origin

这会返回 Git 提供商提供的 URL。如果 URL 为 SSH 格式，请将其转换为 HTTPS：

SSH 格式	HTTPS 格式
[email protected]:user/repo.git	https://github.com/user/repo
[email protected]:user/repo.git	https://gitlab.com/user/repo
[email protected]:user/repo.git	https://bitbucket.org/user/repo

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

使用 HTTPS 仓库 URL 设置 Dashboard 深层链接的格式：

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 将无法读取 Blueprint 配置，部署也会失败。

向用户提供深层链接，并附上以下说明：

1. 确认 render.yaml 已合并 - 确认该文件存在于 GitHub/GitLab/Bitbucket 上的代码仓库中
2. 点击深层链接，打开 Render Dashboard
3. 如有提示，完成 Git 提供商 OAuth 授权
4. 为 Blueprint 命名（或使用 render.yaml 中的默认名称）
5. 填写机密环境变量（标记为 sync: false）
6. 检查服务和数据库配置
7. 点击“Apply”进行部署

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

步骤 7：验证部署

用户通过 Dashboard 部署后，验证所有内容是否正常运行。

通过 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：直接创建服务（快速部署单个服务）

对于不使用 Infrastructure-as-Code 的简单部署，可通过 MCP 工具直接创建服务。

适用场景

• 单个 Web 服务或静态站点
• 快速原型或演示
• 不需要在代码仓库中放置 render.yaml 文件
• 为现有项目添加数据库或 cron 作业

直接创建的先决条件

代码仓库必须已推送到 Git 提供商。 Render 会克隆你的代码仓库，以构建和部署服务。

git remote -v  # Verify remote exists
git push origin main  # Ensure code is pushed

支持的提供商：GitHub、GitLab、Bitbucket

如果不存在远程仓库，请停止操作，并要求用户创建并推送远程仓库，或改用 Docker 镜像部署。

注意： MCP 不支持创建基于镜像的服务。若要部署预构建的 Docker 镜像，请使用 Dashboard/API。

直接创建工作流

按照以下简明步骤操作；完整的 MCP 命令示例和后续配置请参阅 references/direct-creation.md。

步骤 1：分析代码库

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

步骤 2：通过 MCP 创建资源

创建服务（Web 或静态服务），以及所需的数据库或键值存储。请参阅 references/direct-creation.md。

如果 MCP 返回有关缺少 Git 凭据或无法访问代码仓库的错误，请停止操作，引导用户在 Render Dashboard 中连接其 Git 提供商，然后重试。

步骤 3：配置环境变量

创建服务后，通过 MCP 添加所需的环境变量。请参阅 references/direct-creation.md。

提醒用户：如果不想通过 MCP 传递机密信息，也可以在 Dashboard 中设置。

步骤 4：验证部署

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

---

有关服务发现、配置详情、快速命令和常见问题，请参阅 references/deployment-details.md。

---

部署后验证和基本问题排查（适用于所有方法）

保持流程简短且可重复。如果任何检查未通过，请先修复问题，再重新部署。

1. 确认最新部署状态为 live，且正在处理流量
2. 访问健康检查端点（或根路径），并确认返回 200 响应
3. 检查近期错误日志，查找明确的故障特征
4. 验证所需的环境变量和端口绑定（0.0.0.0:$PORT）

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

如果服务无法启动或健康检查超时，请参阅基本问题排查指南： references/troubleshooting-basics.md

故障排查

提升网络访问权限

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

向用户提供的示例指引：

The deploy needs escalated network access to deploy to Render. I can rerun the command with escalated permissions—want me to proceed?

可选：如果需要更深入的诊断（指标／DB 检查／错误目录），建议安装 render-debug 技能。这不是核心部署流程的必需项。