👁️ 382

👍 161

📅 2026-06-13 收录

🔄 2026-06-13 更新

render

🔗 打开网站

📁 render

Skills

🚀 访问网站 📁 查看更多

正文内容

Render 技能

使用蓝图（render.yaml）、Render 控制台或 Render API 在 Render 上部署与管理应用。本技能复现 Codex render-deploy 流程：分析代码库 → 生成/校验 Blueprint → 提交并推送 → 一键控制台深度链接 → 可选通过 API 或 mcporter 进行验证或重新部署。

何时使用此技能

当用户希望执行以下操作时启用该技能：

在 Render 上部署、托管或发布应用
创建或编辑 render.yaml 蓝图（适用于新项目或已有仓库）
添加 Web 服务、静态网站、私有服务（pserv）、Worker、Cron 任务、Postgres 数据库或 Key Value 实例
配置环境变量、健康检查、扩缩容策略、磁盘挂载或部署区域
设置预览环境（Preview Environments）或项目（Projects）
校验 Blueprint 文件，或获取控制台/API 访问链接

部署方式选择

若已设置 RENDER_API_KEY → 优先使用 REST API 或 MCP（最快；无需用户点击）。参考 references/rest-api-deployment.md 获取请求体格式，或在已配置时使用 mcporter（参见 references/mcp-integration.md）。
若未设置 API 密钥 → 使用 Blueprint + 深度链接方式（用户需先提交并推送代码，再点击深度链接完成部署）。

检查 API 密钥是否已设置：

[ -n "$RENDER_API_KEY" ] && echo "RENDER_API_KEY is set" || echo "RENDER_API_KEY is not set"

快速上手路径（面向新用户）

为降低使用门槛，在深入分析前，请按以下简短流程操作：

询问用户是否希望通过 Git 仓库 部署（Blueprint 与深度链接均依赖 Git 远程仓库）；若仅需指导，则跳过部署步骤。若无远程仓库，需先创建并推送。
询问应用是否需要数据库、Worker、Cron 或其他服务，以便选择最匹配的 Blueprint 结构。

随后遵循下方 部署到 Render 流程（Blueprint → 推送 → 深度链接 → 验证）。

前置条件检查

Git 远程仓库 — Blueprint 部署必需。运行 git remote -v；若无输出，请提示用户在 GitHub/GitLab/Bitbucket 创建仓库、添加 origin 远程地址，并推送代码。
Render CLI（可选） — 用于本地 Blueprint 校验：render blueprints validate render.yaml。安装方式：brew install render 或 [Render CLI](https://github.com/render-oss/cli)。
API 密钥（可选） — 用于验证部署状态或触发重新部署：[控制台 → API Keys](https://dashboard.render.com/u/*/settings#api-keys)。请将 RENDER_API_KEY 设置为环境变量。

安全注意事项

切勿在 render.yaml 中硬编码密钥 — 对 API 密钥、密码、Token 等敏感信息始终使用 sync: false；用户需在控制台中手动填写。
部署前务必校验 Blueprint — 执行 render blueprints validate render.yaml 或调用 [Validate Blueprint API](https://api-docs.render.com/reference/validate-blueprint)，避免推送无效 YAML。
严格校验用户输入值 — 当将用户提供的环境变量名、服务名等写入 YAML 时，须进行转义或加引号处理，防止注入风险。

参考资料

references/codebase-analysis.md（检测运行时、构建/启动命令、环境变量）
references/blueprint-spec.md（根级字段、服务类型、环境变量、校验规则）
references/rest-api-deployment.md（直接调用 API 创建服务：ownerId、请求体结构、类型映射）
references/mcp-integration.md（Render MCP 工具、mcporter 使用方法、支持的运行时/套餐/区域）
references/post-deploy-checks.md（通过 API 校验部署状态与健康状况）
references/troubleshooting-basics.md（构建失败、启动失败、运行时异常）
assets/（示例 Blueprint：node-express.yaml、python-web.yaml、static-site.yaml、web-with-postgres.yaml）

Blueprint 基础知识

文件位置：render.yaml 必须置于 Git 仓库根目录（强制要求）。
根级字段（官方规范）：services、databases、envVarGroups、projects、ungrouped、previews.generation、previews.expireAfterDays。
规范文档：[Blueprint YAML Reference](https://render.com/docs/blueprint-spec)。IDE 校验用 JSON Schema：https://render.com/schema/render.yaml.json（例如 VS Code/Cursor 中 Red Hat 提供的 YAML 扩展）。

校验命令：render blueprints validate render.yaml（Render CLI v2.7.0+），或调用 [Validate Blueprint API](https://api-docs.render.com/reference/validate-blueprint)。

服务类型

type	用途
`web`	公开 HTTP 应用或静态网站（静态站请使用 `runtime: static`）
`pserv`	私有服务（仅可通过内部主机名访问，无公网 URL）
`worker`	后台常驻 Worker（持续运行，如任务队列）
`cron`	定时任务（支持 cron 表达式；运行后退出）
`keyvalue`	Render Key Value 实例（兼容 Redis/Valkey；定义于 `services` 下）

注意：私有服务应使用 pserv，而非 private。Key Value 是一种 type: keyvalue 的服务；新版 Blueprint 中不应使用独立的根级字段（如旧版 keyValueStores 和 fromKeyValueStore），请统一采用官方格式。

运行时（Runtimes）

推荐使用 runtime（env 字段已弃用）：node、python、elixir、go、ruby、rust、docker、image、static。
静态网站：type: web、runtime: static，且必须指定 staticPublishPath（例如 ./build 或 ./dist）。

最小化 Web 服务示例

services:
  - type: web
    name: my-app
    runtime: node
    buildCommand: npm install
    startCommand: npm start
    envVars:
      - key: NODE_ENV
        value: production

Python 示例：runtime: python、buildCommand: pip install -r requirements.txt、startCommand: uvicorn app.main:app --host 0.0.0.0 --port $PORT（或 gunicorn）。如需指定版本，请在 envVars 中设置 PYTHON_VERSION / NODE_VERSION。

静态网站

- type: web
  name: my-blog
  runtime: static
  buildCommand: yarn build
  staticPublishPath: ./build

可选字段：headers、routes（重定向/重写规则）。详见 [Static Sites](https://render.com/docs/static-sites)。

环境变量（Env Vars）

字面量：key + value（禁止硬编码密钥）
来自 Postgres：fromDatabase.name + fromDatabase.property（如 connectionString）
来自 Key Value 或其他服务：fromService.type + fromService.name + fromService.property（如 connectionString、host、port、hostport），或 fromService.envVarKey 引用另一服务的环境变量
密钥 / 用户手动设置：sync: false（首次创建时用户将在控制台被提示填写；后续新增密钥需手动添加）。不可用于环境变量组（envVarGroups）内。
自动生成值：generateValue: true（生成 base64 编码的 256-bit 随机值）
共享变量：fromGroup:[].name>（引用环境变量组）

环境变量组不可引用其他服务（即组内禁止 fromDatabase / fromService），也不可使用 sync: false。密钥及数据库/KV 引用应放在 服务级 envVars 中，或通过 fromGroup 引用组后再补充服务专属变量。

数据库（Render Postgres）

databases:
  - name: my-db
    plan: basic-256mb
    databaseName: my_app
    user: my_user
    region: oregon
    postgresMajorVersion: "18"

可用套餐（当前）：free、basic-256mb、basic-1gb、basic-4gb、pro-*、accelerated-*。
历史套餐（停用）：starter、standard、pro、pro plus（不再支持新建数据库）。
可选字段：diskSizeGB、ipAllowList、readReplicas、highAvailability.enabled。
在服务中引用：fromDatabase.name，property: connectionString。

Key Value（Redis/Valkey）

Key Value 实例是 type: keyvalue（或已弃用的 redis）的服务。ipAllowList 为必填项：设为 [] 表示仅限内部访问；- source: 0.0.0.0/0 表示允许外部访问。

services:
  - type: keyvalue
    name: my-cache
    ipAllowList:
      - source: 0.0.0.0/0
        description: everywhere
    plan: free
    maxmemoryPolicy: allkeys-lru

在其他服务中引用：fromService.type: keyvalue、fromService.name: my-cache、property: connectionString。
常用策略：allkeys-lru（缓存场景）、noeviction（任务队列等）。详见 [Key Value](https://render.com/docs/key-value)。

注意：部分旧仓库仍使用根级 keyValueStores 和 fromKeyValueStore；官方规范统一使用 services + fromService。新 Blueprint 请始终采用官方格式。

Cron 任务

- type: cron
  name: my-cron
  runtime: python
  schedule: "0 * * * *"
  buildCommand: "true"
  startCommand: python scripts/daily.py
  envVars: []

schedule 为标准 cron 表达式（分时日月周）。buildCommand 为必填项（如无需构建，可设为 "true"）。免费套餐不支持 cron / worker / pserv。

环境变量组（Env Var Groups）

跨服务共享变量。组内禁止使用 fromDatabase / fromService / sync: false —— 仅支持字面量或 generateValue: true。

envVarGroups:
  - name: app-env
    envVars:
      - key: CONCURRENCY
        value: "2"
      - key: APP_SECRET
        generateValue: true

services:
  - type: web
    name: api
    envVars:
      - fromGroup: app-env
      - key: DATABASE_URL
        fromDatabase:
          name: my-db
          property: connectionString

健康检查、区域、预部署命令

仅限 Web 服务：healthCheckPath: /health（实现零停机部署）
区域：region: oregon（默认）、ohio、virginia、frankfurt、singapore（创建时设定，后续不可更改）
预部署命令：preDeployCommand（构建完成后、启动前执行，例如数据库迁移）

扩缩容（Scaling）

手动扩缩容：numInstances: 2
自动扩缩容（Professional 工作区）：scaling.minInstances、scaling.maxInstances、scaling.targetCPUPercent 或 scaling.targetMemoryPercent。不支持挂载持久化磁盘的服务

磁盘、单体仓库（Monorepo）、Docker

持久化磁盘：disk.name、disk.mountPath、disk.sizeGB（支持 web、pserv、worker）
单体仓库（Monorepo）：rootDir、buildFilter.paths / buildFilter.ignoredPaths、dockerfilePath / dockerContext
Docker：runtime: docker（基于 Dockerfile 构建）或 runtime: image（从镜像仓库拉取）。如需覆盖启动命令，请使用 dockerCommand 而非 startCommand

预览环境（Preview Environments）与项目（Projects）

预览环境：根级 previews.generation: off | manual | automatic，可选 previews.expireAfterDays。各服务可单独设置 previews.generation、previews.numInstances、previews.plan。
项目/环境（Projects/Environments）：根级 projects 字段，每个项目包含 environments 列表（每项列出 services、databases、envVarGroups）。适用于 staging/production 分离。可选 ungrouped 字段存放不属于任何环境的资源。

常见部署模式

全栈应用（Web + Postgres + Key Value）

Web 服务通过 fromDatabase 连接 Postgres，通过 fromService 连接 Key Value。在 Blueprint 中添加一个 databases 条目和一个 type: keyvalue 服务，并在 Web 服务的 envVars 中同时引用二者。参考 assets/web-with-postgres.yaml 配置 Postgres；再添加 Key Value 服务及 fromService 引用 Redis 连接字符串。

微服务架构（API + Worker + Cron）

单个 Blueprint 中定义多个服务：type: web 作为 API、type: worker 作为后台处理器、type: cron 作为定时任务。可通过 envVarGroups 共享变量，或重复声明；使用 fromDatabase / fromService 共享数据库/Redis 连接。所有服务共用同一 branch，并根据各自运行时配置 buildCommand / startCommand。

Pull Request 预览环境

设置根级 previews.generation: automatic（或 manual），可选 previews.expireAfterDays: 7。每个 PR 将获得独立预览 URL；必要时可在服务级通过 previews.generation、previews.numInstances 或 previews.plan 覆盖全局配置。

套餐（Plans）

plan: free | starter | standard | pro | pro plus（Web / pserv / worker 还支持 pro max、pro ultra）。留空表示沿用现有套餐，或对新服务默认使用 starter。free 套餐不适用于 pserv、worker、cron。

控制台与 API

控制台：https://dashboard.render.com — New → Blueprint，连接仓库并选择 render.yaml
Key Value 创建页：https://dashboard.render.com/new/redis

API 访问

若需通过 Agent 调用 Render API（验证部署、触发部署、查询服务/日志等）：

获取 API 密钥：控制台 → Account Settings → [API Keys](https://dashboard.render.com/u/*/settings#api-keys)
存储为环境变量：将 RENDER_API_KEY 设置为环境变量（例如 skills.entries.render.env 或进程级环境变量）
认证方式：所有请求使用 Bearer Token：Authorization: Bearer $RENDER_API_KEY
API 文档：https://api-docs.render.com — 包含服务管理、部署、日志、Blueprint 校验等全部接口

新部署检查清单

编写或更新 render.yaml，至少包含 services（可选 databases、envVarGroups、projects）。使用 runtime 字段，并采用官方 Key Value 格式（type: keyvalue 定义于 services，引用使用 fromService）
仅在服务级 envVars 中 对密钥使用 sync: false；明确告知用户需在控制台中填写。禁止在环境变量组中放置密钥
Key Value 服务必须设置 ipAllowList（必需字段）
执行校验：render blueprints validate render.yaml 或调用 Validate Blueprint API
用户需提交并推送代码，然后使用 Blueprint 深度链接（https://dashboard.render.com/blueprint/new?repo=）完成部署。若已设置 RENDER_API_KEY，可选通过 API 进行部署验证或重新部署

规则

优先使用 Blueprint 定义完整应用；仅当 Blueprint 无法表达某需求时，才建议使用控制台或 API
严禁提交真实 API 密钥或密钥；一律使用 sync: false 并明确说明用户需在控制台中设置哪些环境变量
使用 runtime（弃用 env）。Python/Node 应用如需指定版本，请在 envVars 中设置 PYTHON_VERSION / NODE_VERSION
引用 Key Value 或其他服务时，必须使用 fromService 并指定正确 type（例如 keyvalue、pserv）