render-blueprints

Render Blueprints（render.yaml）

Blueprint 使用 YAML 定义 Render 基础设施（通常位于仓库根目录的 render.yaml）。本技能侧重于编写、连接、项目/环境、预览、验证和不可变字段。详细内容见 references/。

创建或修改 Blueprint 之前，请阅读 references/blueprints.md，了解当前的规范获取、验证、仓库同步和安全工作流。

如需了解当前的计算方案术语、Plan ID 和可用性，请使用 references/compute-plans.md，而不要依赖示例中嵌入的方案目录。

添加或修改附加到服务的磁盘之前，请阅读 references/persistent-disks.md，了解当前的架构限制和配置工作流。

配置私有网络地址、端口或服务发现主机名之前，请阅读 references/private-networking.md。

选择服务类型，或将其 Dashboard 名称转换为 Blueprint 结构之前，请阅读 references/service-types.md。

适用场景

在以下情况下使用此技能：

• 创建或编辑 render.yaml / Blueprint
• 将数据库、私有服务或 Key Value 连接到应用环境变量
• 使用项目和环境对服务分组
• 为拉取请求配置预览环境
• 根据 Render 的架构或 CLI 验证 YAML
• 询问资源创建后哪些内容可以更改或不能更改

如需了解端到端部署流程和 MCP/CLI 操作，请参阅 render-deploy。如需了解 Blueprint 语法之外的环境变量策略，请参阅 render-env-vars。如需了解 Docker 专用的 Blueprint 字段，请参阅 render-docker。

Blueprint 结构

顶层键

键	用途
services	Web、worker、cron、私有服务、Key Value、静态站点（通过 web + runtime: static）
databases	托管的 PostgreSQL 实例
envVarGroups	可附加到服务的可重用环境变量集
projects	可选分组；包含 environments 和服务列表
previews	PR 预览环境的默认设置

根据是否采用 projects 模型，Blueprint 也可以使用未分组资源与限定环境范围的列表等模式。关于重复和命名方面的注意事项，请参阅 references/common-mistakes.md。

最简示例：Web + PostgreSQL

databases:
  - name: mydb
    plan: basic-256mb
    region: oregon

services:
  - type: web
    name: api
    runtime: node
    region: oregon
    plan: starter
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: mydb
          property: connectionString

服务类型

type	角色
web	公共 HTTP 服务（静态站点使用 runtime: static）
pserv	私有服务（内部 HTTP/TCP；非公共服务）
worker	长时间运行的后台进程
cron	定时任务（必须指定 schedule）
keyvalue	托管的 Key Value（兼容 Redis）；Blueprint 也接受别名 redis

运行时

常见的 runtime 值：node、python、go、ruby、rust、elixir、docker、image、static。

• docker：从 Dockerfile 构建（参见 dockerfilePath、dockerContext、dockerCommand）。
• image：运行预构建的容器映像，使用 image.url 和可选的 image.creds.fromRegistryCreds。
• static：静态站点；需要 staticPublishPath 和构建输出路径（参见参考资料）。

跨服务连接

配置变量、密钥、密钥文件或环境变量组之前，请阅读 references/environment-variables.md。

envVars 下的服务环境变量可以从其他资源获取值，而不是将密钥硬编码。环境变量组中的变量不能引用服务、数据库或其他环境变量组。

fromDatabase

通过 name 引用 databases: 中的数据库。属性包括：

• connectionString、connectionPoolString、host、port、user、password、database

fromService

通过 name 引用服务。常用属性：

• host、port、hostport、connectionString、envVarKey

哪些属性有效取决于目标服务类型（例如 Key Value 与 pserv）。请参阅 references/wiring-patterns.md。

fromGroup

按组 name 从 envVarGroups 附加共享变量。

完整模式和组合方式：references/wiring-patterns.md。

项目和环境

对于多服务应用，请使用 projects/environments 模式，而不是扁平的顶层 services/databases。此模式会将所有相关资源归入单个 Render 项目，支持多个环境（生产、预发布），并启用环境范围的配置。

projects:
  - name: my-app
    environments:
      - name: production
        services:
          - type: web
            name: api
            runtime: node
            plan: standard
            buildCommand: npm ci && npm run build
            startCommand: npm start
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString
              - key: API_SECRET
                sync: false

          - type: worker
            name: jobs
            runtime: node
            plan: starter
            buildCommand: npm ci
            startCommand: node worker.js
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString

          - type: keyvalue
            name: cache
            plan: starter
            maxmemoryPolicy: noeviction
            ipAllowList: [] # Internal access only

        databases:
          - name: db
            plan: basic-256mb

关键规则：

• 每个环境拥有自己的 services 和 databases 列表。
• 不要在根级别和环境内部同时定义同一资源。
• envVarGroups 可以限定到项目环境，也可以在整个工作区共享。
• 使用 Pro 工作区或更高级别时，环境隔离可以阻止跨环境的私有网络流量。

对于单服务应用，使用扁平的顶层 services/databases 即可。当你有多个服务、需要区分预发布和生产环境，或希望使用环境范围的环境变量组时，请采用项目模式。

预览环境

当预览请求的信息不够明确时，请先确认所需的生成模式、保留期限、预览计算方案，以及用户是否希望排除某些资源。

顶层 previews 控制 Blueprint 预览环境：

• previews.generation：off（默认）、manual 或 automatic
• previews.expireAfterDays：在 N 天后自动删除预览堆栈

不要将预览环境与服务预览混淆：

• 顶层 previews.generation: automatic 会创建 Blueprint 的预览环境，其中包含该 Blueprint 声明的资源。
• 服务级别的 previews.generation 控制该服务独立的服务预览。它不会覆盖 Blueprint 预览环境，也不会将该服务排除在其中。它只接受 manual 或 automatic；省略此项即可禁用独立的服务预览。
• 对计算服务使用 previews.plan 和 previews.numInstances 来设置预览环境实例的规格。Key Value 和 Postgres 则使用 previewPlan。

如果用户需要在 Blueprint 预览环境中完全省略某个 worker 或其他资源，请说明服务级别的预览生成设置并非排除机制；Blueprint 或应用架构必须满足这一要求。其他限制包括自动扩缩行为、sync: false 变量和数据库方案兼容性，详见 references/preview-environments.md。

不可变字段

关键： 创建资源后，某些字段无法更改。修改可能会被拒绝，或需要替换资源。

服务

• type：无法更改（例如，web → worker）。
• runtime：无法更改（例如，node → docker）。

数据库

创建后无法更改：

• name（此处指 Blueprint/数据库的逻辑标识符）
• databaseName
• user
• region
• postgresMajorVersion

请提前仔细规划其他字段（磁盘、HA、副本）；有关哪些字段可以扩容以及哪些字段需要重新创建，请参阅 Render 文档。

关键字段（速览）

区域	字段
方案	plan；计算服务的 previews.plan；Key Value/Postgres 的 previewPlan
构建/运行	buildCommand、startCommand、preDeployCommand、rootDir
部署	autoDeployTrigger：commit、checksPass 或 off
生命周期	maxShutdownDelaySeconds：1–300，默认 30
HTTP	healthCheckPath、domains
存储	disk（name、mountPath、sizeGB）
扩缩容	scaling / numInstances（参见参考文档）
Monorepo	buildFilter（paths、ignoredPaths）
Docker	dockerfilePath、dockerContext、dockerCommand、registryCredential；预构建的 image.url / image.creds

请避免使用已弃用的名称：env（使用 runtime）、redis（使用 keyvalue）、autoDeploy（使用 autoDeployTrigger）、previewsEnabled 和 pullRequestPreviewsEnabled。请使用 references/common-mistakes.md 中所述的适当顶层或服务级 previews.generation 替代项。

参考文档

文档	内容
references/blueprints.md	当前 Blueprint 规范、架构、验证、仓库同步和安全工作流
references/compute-plans.md	当前计算方案术语、Plan ID 查找、可用性和变更行为
references/environment-variables.md	当前环境变量文档、机密、组、平台变量和变更安全性
references/persistent-disks.md	服务挂载磁盘的限制、当前文档、容量调整、快照和 Blueprint 工作流
references/private-networking.md	私有网络范围、地址、Blueprint 参考、发现、端口和隔离
references/service-types.md	服务类型选择、执行模型和 Blueprint 命名
references/field-reference.md	按服务类型划分的 YAML 字段，以及数据库、组、项目、预览、扩缩容、磁盘、静态服务和 Key Value
references/wiring-patterns.md	fromDatabase / fromService / fromGroup 示例和组合连接模式
references/common-mistakes.md	分支与预览、buildFilter、副本、重复项、预览方案和连接错误
references/preview-environments.md	previews.generation、过期时间、previews.plan、previewPlan、磁盘和 PR 工作流

相关技能

• render-deploy — 部署流程、Blueprint 与直接创建、MCP/深层链接
• render-env-vars — 环境变量策略、机密、Dashboard 与 Blueprint
• render-docker — 基于 Dockerfile 的服务和镜像运行时注意事项

当前文档检索

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

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

当任务需要查阅多个参考文档时，请对每份文档分别执行此流程，并区分已验证的文档和仍不可用的文档。