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 无法创建基于镜像的服务）。

何时使用此技能

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

• 将应用部署到 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 应用或一个静态站点）
• 没有独立的 worker／cron 服务
• 没有附加数据库或 Key Value
• 仅有简单的环境变量（没有共享环境变量组） 如果适合此路径，但尚未配置 MCP，请停止并先引导用户设置 MCP。

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

• 多个服务（web + worker、API + 前端等）
• 需要数据库、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. 确认 Render 访问权限

在读取或更改 Render 资源之前，请按照 references/render-access.md 选择访问方式、完成身份验证、确认目标工作区，并确认所需权限。即使 MCP 可用，验证 Blueprint 仍需要 Render CLI。

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

触发、监控、重启或回滚部署之前，请阅读 references/deployments.md，了解当前生命周期、运行状况检查和验证工作流。

当资源通过 Render 的私有网络通信时，请在选择区域或配置地址和端口之前阅读 references/private-networking.md。

选择或更改服务类型之前，请阅读 references/service-types.md。

---

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

Blueprint 工作流

步骤 1：分析代码库

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

步骤 2：生成 render.yaml

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

编写或更改该文件之前，请阅读 references/blueprints.md，并遵循其中当前的规范获取、验证、代码库同步和安全工作流。

对于变量、密钥、密钥文件或环境组，也请阅读 references/environment-variables.md。

要点：

• 为资源和工作负载选择合适的计算方案。请参阅 references/compute-plans.md，了解当前的 Plan ID、默认值、可用性和定价指南，不要依赖此技能中的示例。
• 除非用户指定区域，否则请将新资源放置在与其相关现有服务相同的区域，以保持私有网络连接。
• 包含应用所需的所有环境变量，并使用 references/environment-variables.md 中指定的事实来源和密钥机制
• 使用合适的服务类型：web、worker、cron、keyvalue 或 pserv（静态站点使用 type: web 和 runtime: static）
• 使用合适的运行时：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 计划运行的定时任务
• pserv：私有服务（仅限内部使用，且必须位于同一账户和区域）
• keyvalue：兼容 Redis 的键值存储

type: web 且 runtime: static 的服务是通过全球 CDN 提供服务的静态站点。静态站点没有 plan。

Postgres 数据库定义在 databases 键下，而不是 services 键下。它们没有 type。

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

步骤 2.5：立即执行后续步骤（始终提供）

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

1. 确认访问权限：按照 references/render-access.md 操作
2. 验证：运行 render blueprints validate render.yaml
   • 如果尚未安装 CLI，提出安装建议并提供命令。
3. 提交并推送：git add render.yaml && git commit -m "Add Render deployment configuration" && git push origin main
4. 打开 Dashboard：使用 Blueprint 深层链接，并在出现提示时完成 Git OAuth
5. 完成密钥配置：提供所选环境变量工作流所需的任何值
6. 部署：点击“Apply”并监控部署

步骤 3：验证配置

按照 references/blueprints.md 中的验证工作流操作。如果已安装 CLI，直接运行命令；仅在缺少 CLI 时提示用户：

render blueprints validate render.yaml

如果相对于当前目录，Blueprint 文件不在 render.yaml，请传入实际文件路径。

继续之前，请修复所有验证错误。常见问题：

• 缺少必填字段（name、type、runtime）
• 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. 完成所有必需的密钥配置，但不要泄露密钥值
6. 检查服务和数据库配置
7. 点击“Apply”进行部署

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

步骤 7：验证部署

用户通过 Dashboard 部署后，按照 references/deployments.md 中的说明，通过终端状态监控特定部署并验证生成的工作负载。

如果发现错误，请继续查看下方的 部署后验证和基本排查 部分。

---

方法 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 不支持创建基于镜像的服务。请使用 Dashboard/API 部署预构建的 Docker 镜像。

直接创建工作流

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

步骤 1：分析代码库

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

步骤 2：通过 MCP 创建资源

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

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

步骤 3：配置环境变量

更改服务配置前，请阅读 references/environment-variables.md。创建服务后，按照 references/direct-creation.md 中的说明通过 MCP 添加所需的环境变量。

提醒用户，如果不想通过 MCP 传递密钥，可以在 Dashboard 中设置。

步骤 4：验证部署

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

---

如需了解服务发现、配置详情、快捷命令和常见问题，请参阅 references/deployment-details.md。

---

部署后验证与基本排查（所有方式）

按照 references/deployments.md 解读部署状态并在服务上线后进行验证。如果任何检查失败，请先修复，再重新部署。

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

如果服务无法启动或运行状况检查超时，请使用基本排查指南： references/troubleshooting-basics.md

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

获取最新文档

每当此 skill 指示你查阅最新的 Render 文档时：

1. 使用可用的 URL 获取工具或 HTTP 客户端（如 curl）直接获取链接的 Markdown 文档。不要用网页搜索摘要代替文档。
2. 确认获取成功且返回了预期文档，然后阅读其内容。仅保存文件或输出文件路径并不足够。
3. 如果请求失败，或你的工具无法读取 Markdown 响应，请打开并阅读链接的 HTML 版本。
4. 如果两个版本都无法获取，请说明当前无法获取该参考文档，并遵循此 skill 中针对该主题的回退方案。仅对稳定约束使用随附指南，不要猜测可能变化的平台细节。

当任务需要多个参考文档时，请对每份文档分别执行此流程，并区分已验证的文档与仍无法获取的文档。