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 重新运行。
• 部署可能需要几分钟。请设置适当的超时时间。

API 密钥和密钥信息的安全要求

重要 - 必须保护用户凭据：

处理 Render API 密钥或任何密钥信息时：

1. 绝不要要求用户在聊天中直接粘贴 API 密钥 - 而应指导他们设置环境变量：

   export RENDER_API_KEY="rnd_xxxxx"
   

2. 绝不要在示例中包含实际 API 密钥 - 始终使用 <YOUR_API_KEY> 或 rnd_xxxxx 等占位符

3. 引导用户安全存储密钥 - 告知他们：

   • 为 CLI 身份验证设置环境变量
   • 使用 Render Dashboard 设置服务密钥（将环境变量标记为 sync: false）
   • 绝不要将密钥提交到 Git

4. 用户需要 API 密钥时，请提供以下指引：

   • “从此处获取 API 密钥：https://dashboard.render.com/u/*/settings#api-keys”
   • “将其设置为环境变量：export RENDER_API_KEY='your-key-here'”
   • “绝不要分享或提交此密钥”

5. 对于 MCP 配置，展示其结构，但强调：

   • 将 <YOUR_API_KEY> 替换为实际密钥
   • 不应将此文件提交到版本控制
   • 密钥应保密

6. 如果用户不慎在聊天中分享了密钥信息，请立即：

   • 警告他们该密钥可能已泄露
   • 指导他们在 Render Dashboard 中撤销该密钥
   • 指导他们创建新密钥

何时使用此技能

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

• 将应用部署到 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 或其他数据存储
• 定时任务、后台工作进程或私有服务
• 需要可复现的 IaC，或需要将 render.yaml 提交到仓库
• 需要统一配置的单体仓库或多环境设置

如果不确定，请快速询问用户以澄清；但为安全起见，默认使用 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()。

其他工具

如果用户使用其他 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：直接创建服务（快速部署单个服务）

对于不使用基础设施即代码的简单部署，可直接通过 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。

直接创建工作流

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

步骤 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?

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