render-migrate-from-heroku

将 Heroku 迁移到 Render

使用用户提供的清单或本地项目文件，将 Heroku 迁移到 Render；之后可选择通过 MCP 获取实时 Heroku 数据，补充缺失的详情。

前置条件检查

开始前，确认以下内容是否可用：

1. 应用清单（必需）——使用用户提供的完整详情，或检查本地项目文件，例如 Procfile、app.json、package.json、requirements.txt、Gemfile 或 go.mod
2. Render MCP（推荐）——检查是否有 list_services 工具。MCP 直接创建（步骤 3B）和自动验证（步骤 6）需要此工具。Blueprint 路径不需要此工具——Render CLI 和 Dashboard 会负责生成、验证和部署。
3. Heroku MCP（可选）——检查是否有 list_apps 工具

如果用户已提供足够的信息来制定所需的计划、Blueprint 或迁移说明，则无需要求提供本地文件或 MCP。如果缺少 Render MCP，且用户确实需要访问实时 Render 数据，请使用 references/render-access.md 中的 Render 访问工作流；MCP 设置指南还包含 Heroku 专属设置。如果缺少 Heroku MCP，请使用用户提供的值，或仅询问缺失的配置变量名称和附加组件详情。

迁移工作流

要进行端到端迁移，请按顺序执行适用的步骤。向用户展示调查结果，并在创建任何资源前取得确认。

将 Heroku 进程类型映射到 Render 服务类型前，请先阅读 references/service-types.md。

选择精简工作流

• **完整清单 + Blueprint 请求：**阅读 references/service-mapping.md、references/blueprint-example.md 和 references/blueprints.md；直接生成完整的 Blueprint。不要仅为重新获取用户已提供的值而调用实时工具。
• **单服务迁移：**收集缺失的清单信息，向用户展示计划；仅在用户要求创建服务并确认计划后，才使用 MCP 直接创建。
• **数据迁移问题：**阅读 references/service-mapping.md 和 references/data-migration.md；提供适用的操作步骤，除非用户要求，否则不要执行实时操作。

使用 references/service-mapping.md 中的确切 Heroku 计划行，包括映射的 Render 计划和磁盘分配。这些迁移映射会在适当情况下有意使用旧版 Render 计划名称；不要替换为凭记忆得出的当前 Plan ID。

步骤 1：盘点 Heroku 应用

先从本地文件收集应用详情，然后在可用时通过 Heroku MCP 补充。

1a. 读取本地项目文件（始终执行）

读取仓库中的这些文件，以确定运行时、命令和依赖项：

文件	说明
Procfile	进程类型和启动命令（web、worker、clock、release）
package.json	Node.js 运行时、构建脚本、框架依赖项（Next.js、React 等）
requirements.txt / Pipfile / pyproject.toml	Python 运行时、依赖项（Django、Flask 等）
Gemfile	Ruby 运行时、依赖项（Rails、Sidekiq 等）
go.mod	Go 运行时
Cargo.toml	Rust 运行时
app.json	声明的附加组件、环境变量说明、构建包
runtime.txt	固定的运行时版本
static.json	静态站点标记
yarn.lock / pnpm-lock.yaml	包管理器（会影响构建命令）

根据这些文件确定：

• 运行时 — 从依赖项文件确定（参见构建包映射）
• 运行时版本 — 从 runtime.txt、.node-version 或 package.json 中的 engines 确定。如果已固定，则将其作为环境变量传递（例如 PYTHON_VERSION、NODE_VERSION）。如果未固定，则不要指定版本——绝不要假设或声明 Render 的默认版本。
• 构建命令 — 根据包管理器和框架确定（参见构建包映射）
• 启动命令 — 来自 Procfile 条目
• 进程类型 — 来自 Procfile（web、worker、clock、release）
• 所需附加组件 — 根据 app.json 的 addons 字段确定，或从依赖项文件推断（例如，package.json 中的 pg 表示可能需要 Postgres，redis 表示可能需要 Key Value）
• 是否为静态站点？ — 根据 static.json、SPA 框架依赖项或 app.json 中的静态构建包确定

1b. 使用 Heroku MCP 补充信息（如果可用）

如果已连接 Heroku MCP 服务，请调用以下工具，补充仓库中没有的信息。dyno 规格和附加组件计划 slug至关重要——它们决定要使用哪些 Render 计划。

1. list_apps — 让用户选择要迁移的应用（确认应用名称）
2. get_app_info — 获取：区域、堆栈、构建包、配置变量名称
3. list_addons — 获取准确的附加组件计划 slug（例如，heroku-postgresql:essential-2、heroku-redis:premium-0）。冒号后的部分对应服务映射中的特定 Render 计划。
4. ps_list — 获取每种进程类型的准确 dyno 规格（例如，Standard-2X、Performance-M）。每种 dyno 规格都对应服务映射中的特定 Render 计划。
5. pg_info（如果存在 Postgres）— 获取数据大小（实际用量）和计划的磁盘分配量。计划的磁盘大小决定 Blueprint 中的 diskSizeGB 值（参见服务映射）。

如果 Heroku MCP不可用，请让用户提供：

• Dyno 规格（或运行 heroku ps:type -a <app> 并粘贴输出）
• 附加组件计划（或运行 heroku addons -a <app> 并粘贴输出）
• 数据库信息（或运行 heroku pg:info -a <app> 并粘贴输出——可获取计划名称、数据大小和磁盘分配量）
• 应用区域（us 或 eu）
• 配置变量名称（或运行 heroku config -a <app> --shell 并粘贴输出）

如果用户无法提供 dyno 规格或附加组件计划，请使用服务映射中的备用默认值：计算使用 starter，Postgres 使用 basic-1gb，Key Value 使用 starter。

展示摘要

App: [name] | Region: [region] | Runtime: [node/python/ruby/etc]
Source: [local files | local files + Heroku MCP]
Build command: [inferred from buildpack/deps]
Processes:
  web: [command from Procfile] → Render web service ([mapped-plan])
  worker: [command] → Render background worker ([mapped-plan], Blueprint only)
  clock: [command] → Render cron job ([mapped-plan])
  release: [command] → Append to build command
Add-ons:
  Heroku Postgres ([plan-slug], [disk-size]) → Render Postgres ([mapped-plan], diskSizeGB: [size])
  Heroku Key-Value Store ([plan-slug]) → Render Key Value ([mapped-plan])
Config vars: 14 total (list names, not values)

步骤 2：迁移前检查

创建任何资源之前，请按照迁移前检查清单核验迁移计划。重点检查：

• 是否支持运行时（或是否需要 Dockerfile）
• Worker dyno、发布阶段、静态站点检测
• 没有 Render 对应服务的第三方附加组件
• Git 远程仓库是否存在且使用 HTTPS 格式
• 数据库大小（大型数据库需要辅助迁移）

在服务映射中查找每种 Heroku dyno 规格和附加组件计划，以确定正确的 Render 计划。展示迁移前检查清单中的迁移计划表，标明会产生费用的资源，引导用户查看 Render 定价了解当前详情，并在创建任何资源之前等待用户确认。

确定创建方式

用户批准迁移前计划后，请应用以下决策规则。默认使用 Blueprint——只有在满足以下所有条件时，才使用 MCP 直接创建。

在以下任一条件成立时使用 Blueprint（默认方式）：

• 有多种进程类型（web + worker、web + cron 等）
• 需要数据库或 Key Value 存储
• Procfile 中包含后台 Worker
• 用户偏好使用基础设施即代码配置

仅在以下所有条件都成立时，才退回使用 MCP 直接创建：

• 只有一个 web 服务或静态站点服务（一种进程类型）
• 没有后台 Worker 或 cron 作业
• 不需要数据库或 Key Value 存储

如果不确定，请使用 Blueprint。大多数 Heroku 应用至少有一个数据库，因此绝大多数迁移都适用 Blueprint。

步骤 3A：生成 Blueprint（多服务）

此路径分为三个阶段。始终完成编写；在操作范围内时，执行本地验证并提供应用流程。

3A-i. 编写 render.yaml

生成完整的 render.yaml。在用户的仓库中操作时，将文件写入仓库根目录；否则，在回复中提供完整文件。编写前，阅读 references/blueprints.md 中当前的规范获取、验证、仓库同步和安全工作流。然后使用 Blueprint 示例 中针对迁移的结构。

重要：始终使用 projects/environments 模式。 YAML 必须以 projects: 键开头，绝不能使用顶层的 services: 或 databases: 键。这样可以将所有迁移的资源归入同一个 Render 项目。

根据 服务映射，为每个服务和数据库设置 plan: 字段，使用映射后的 Render 套餐。 查询 Heroku dyno 规格（通过 ps_list）和附加组件套餐 slug（通过 list_addons），以确定对应的 Render 套餐。如果 Heroku 套餐未知，则使用备用默认值：计算资源使用 starter，Postgres 使用 basic-1gb，Key Value 使用 starter。

按照 Blueprint 示例中的完整模板、规则和模式生成 YAML。关键规则：

• 始终使用 projects:/environments: 模式，绝不能使用顶层的 services:
• 根据 服务映射设置每个 plan: 字段
• 根据 Heroku 磁盘分配为数据库设置 diskSizeGB
• DATABASE_URL 使用 fromDatabase，REDIS_URL 使用 fromService，绝不能对连接字符串进行硬编码
• 使用 sync: false 标记密钥

3A-ii. 验证 Blueprint

本地写入 render.yaml 文件后，在将其标记为可部署前进行验证。首先，检查是否已安装 Render CLI：

render --version

如果尚未安装，且当前任务需要在本地验证部署就绪情况，则提供安装方式：

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

CLI 可用后，运行验证命令并向用户展示输出：

render blueprints validate render.yaml

如果验证失败，修正 YAML 中的错误并重新验证。重复此过程，直到验证通过。如果用户只需要示例，或本地不存在文件，则提供验证命令，但不要尝试安装或声称已运行验证。

3A-iii. 提供部署 URL

用户希望应用 Blueprint 时，在验证通过后：

1. 指示用户提交并推送：git add render.yaml && git commit -m "Add Render migration Blueprint" && git push
2. 运行 git remote get-url origin 获取仓库 URL。如果 URL 为 SSH 格式（例如 [email protected]:user/repo.git），将其转换为 HTTPS（https://github.com/user/repo）。然后构建深层链接：https://dashboard.render.com/blueprint/new?repo=<HTTPS_REPO_URL>
3. 向用户提供实际可用的深层链接，绝不能展示占位 URL。引导用户打开链接，填写 sync: false 密钥，然后点击 Apply

不要省略部署 URL。 用户需要此链接才能在 Render 上应用 Blueprint。

步骤 3B：通过 MCP 直接创建（单服务）

通过 MCP 工具创建资源之前，请遵循 references/render-access.md，并确认当前工作区是用户指定的工作区。

对于不涉及数据库的单服务迁移，请通过 MCP 工具创建：

1. Web 服务 — 使用 create_web_service，并设置：
   • runtime：根据 buildpack 映射填写
   • buildCommand：根据 buildpack 映射填写
   • startCommand：取自 Procfile 中的 web: 条目
   • repo：用户提供的 GitHub/GitLab URL
   • region：根据 Heroku 区域映射
   • plan：根据 服务映射，按 Heroku dyno 规格映射（回退值：starter）
2. 静态站点 — 如果检测到静态站点，则使用 create_static_site（而非 Web 服务）

创建完成后，向用户展示创建结果（服务 URL、ID）。

步骤 4：迁移环境变量

检查或应用配置之前，请先阅读 references/environment-variables.md，并保留以下迁移专用筛选和确认步骤。

收集配置变量

使用第一个可用来源：

1. Heroku MCP（首选）— 从 get_app_info 结果中获取配置变量（步骤 1b）
2. 用户提供 — 请用户粘贴 heroku config -a <app> --shell 的输出
3. app.json — 变量名和说明（不含值，但对 sync: false 条目很有帮助）

筛选并分类

移除自动生成的变量和 Heroku 专用变量（完整筛选列表见 服务映射）：

• DATABASE_URL、REDIS_URL、REDIS_TLS_URL（Render 会生成这些变量）
• HEROKU_* 变量（例如 HEROKU_APP_NAME、HEROKU_SLUG_COMMIT）
• 附加组件连接字符串（PAPERTRAIL_*、SENDGRID_* 等）

向用户展示筛选后的列表 — 未经确认，不得写入变量。

应用变量

Blueprint 路径（步骤 3A）： 环境变量已嵌入每项服务的 render.yaml 中（非机密值内联填写，机密值标记为 sync: false，由用户在应用 Blueprint 时填写）。无需单独调用 MCP — 跳至步骤 5。

MCP 路径（步骤 3B）： 检查当前的 update_environment_variables 操作，确认它是修补还是替换整个集合，然后仅应用已确认的变量，同时保留无关键。

步骤 5：数据迁移

请遵循 数据迁移指南，迁移 Postgres 和 Key Value 数据。指南详细介绍了步骤 5a 至 5e。流程概要：

1. 迁移前检查 — 通过 list_postgres_instances() 和 list_key_value() 确认 Render 资源已配置，检查源数据库大小，确认已安装 Render CLI（render --version）、pg_dump 和 pg_restore
2. 收集连接字符串 — 通过 pg_credentials（MCP）获取 Heroku Postgres 连接字符串，或请用户粘贴 CLI 输出。对于 Key Value，根据 ID 构建 Dashboard 深层链接。
3. Postgres 迁移 — 根据数据大小选择两种方式：小于 2 GB 时使用 render psql（无需 Render 连接字符串）；2-50 GB 时使用 pg_dump -Fc + pg_restore，并通过 Dashboard 获取外部连接字符串（速度更快、经过压缩且支持并行还原）。
4. Key Value — 通常跳过（临时缓存）。如果有持久数据，请使用 redis-cli，并通过 Dashboard 提供的 Render URL 进行转储和还原。
5. 数据验证 — 通过 query_render_postgres 验证架构和行数；如果 MCP 可用，请与 Heroku 源数据进行比较。

步骤 6：验证迁移

用户确认数据库迁移完成后，按顺序逐项检查。首次失败时停止，修复问题并重新部署，然后再继续。

1. 确认部署状态

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

预期状态为 status: "live"。如果状态为 failed，请立即检查构建日志和运行时日志。

2. 验证服务健康状况

访问健康检查端点（或 /），并确认响应状态码为 200。如果没有健康检查端点，请确认应用绑定到 0.0.0.0:$PORT（而不是 localhost）。

3. 扫描错误日志

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

查找明显的故障特征：缺少环境变量、连接被拒绝、找不到模块、端口绑定错误。

4. 验证环境变量和端口绑定

确认已设置所有必需的环境变量，尤其是 Blueprint 应用期间标记为 sync: false 的密钥。确保应用绑定到 0.0.0.0:$PORT。

5. 检查资源指标

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

确认 CPU 和内存使用量在所选套餐的预期范围内。

6. 确认数据库连接

query_render_postgres(postgresId: "<postgres-id>", sql: "SELECT count(*) FROM <key_table>")

对关键表运行只读查询，确认数据已正确恢复。如果可能，将行数与 Heroku 源数据库进行比较。

所有检查通过后，提供健康状况摘要。

步骤 7：切换 DNS（手动）

指示用户：

1. 添加 CNAME，将域名指向 [service-name].onrender.com
2. 移除或更新旧的 Heroku DNS 条目
3. 等待 DNS 传播

回滚计划

如果迁移在任何阶段失败：

• 服务已创建但无法正常工作：可以从 Render 控制面板删除服务（MCP 服务有意不支持删除）。启用维护模式之前，Heroku 应用不会受到影响。
• 环境变量有误：按照 references/environment-variables.md 操作，检查当前更新操作的补丁式或替换式行为，并只修正目标键。
• 数据库迁移失败：可以删除并重新创建 Render Postgres。在转储期间，Heroku 数据库为只读（不会丢失数据）。如果在 Heroku 上调用 maintenance_off，原应用即可完全恢复运行。
• DNS 已更改：将 CNAME 改回 Heroku，并在 Heroku 上停用维护模式。

核心原则：在用户明确切换 DNS 之前，Heroku 始终保持完全可用。 在最后这一步之前，迁移只会新增内容。

错误处理

• 服务创建失败：显示错误，并建议修复方法（套餐无效、仓库 URL 错误）
• 环境变量迁移部分失败：显示成功和失败的项目
• Heroku 身份验证错误：提示运行 heroku login 或检查 HEROKU_API_KEY
• Render 身份验证错误：检查 MCP 配置中的 Render API 密钥

获取当前文档

每当此技能要求查阅当前 Render 文档时：

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

当任务需要多个参考资料时，对每份资料都应用此流程，并区分已验证的文档和仍不可用的文档。