render-docker

Render Docker 部署

Render 使用 BuildKit 进行 Docker 构建。所有支持自定义运行时的计算服务类型都可以使用 runtime: docker（从仓库中的 Dockerfile 构建）或 runtime: image（拉取预构建镜像；Render 不会构建 Dockerfile）。更深入的模式和可直接复制粘贴的模板位于 references/ 下。

适用场景

• 为 Render 服务编写或调试 Dockerfile
• 在 Blueprint 中选择 runtime: docker 还是 runtime: image
• 配置带有注册表凭据的 私有基础镜像 或 预构建镜像
• 多阶段构建、构建参数、密钥和层缓存
• 加固 Render 上容器镜像的性能和安全性

如需了解 Blueprint 的完整编写方法，请参阅 render-blueprints。如需了解端到端部署流程，请参阅 render-deploy。

在部署已构建或预构建的镜像之前，请阅读 references/deployments.md，了解当前的触发、生命周期、健康检查和信号行为。

Render Docker 构建

• Render 上的 Docker 构建使用 BuildKit。
• runtime: docker：Render 使用仓库中的内容构建镜像，可通过 dockerfilePath、dockerContext 和可选的 dockerCommand 指定配置（dockerCommand 会覆盖镜像的 CMD）。
• runtime: image：Render 会拉取 image.url；不会基于仓库构建镜像。若注册表为私有，请设置 image.creds.fromRegistryCreds.name。

Blueprint 配置

字段	作用
dockerfilePath	Dockerfile 路径（默认为 ./Dockerfile）
dockerContext	构建上下文目录（发送给守护进程的内容）
dockerCommand	镜像构建完成后，覆盖容器的 CMD
image.url	runtime: image 的镜像引用（注册表/仓库:标签或摘要）
image.creds	Dashboard 中存储的私有预构建镜像凭据引用
registryCredential	Dashboard 中存储的凭据引用，供 runtime: docker 使用的私有基础镜像使用

示例草图（值仅供说明）：

services:
  - type: web
    name: api
    runtime: docker
    region: oregon
    plan: starter
    dockerfilePath: ./Dockerfile
    dockerContext: .
    dockerCommand: node server.js
    envVars:
      - key: PORT
        value: 10000

对于 runtime: image，请设置 image.url，并根据需要按照下方的 注册表配置设置 image.creds。

多阶段构建

生产环境推荐使用。 使用 builder 阶段进行编译和依赖安装，再使用精简的 runner 阶段，仅复制构件和运行时文件。优点：

• 镜像更小，拉取更快
• 最终镜像中包含的工具和密钥更少（攻击面更小）
• 清晰地区分构建时和运行时依赖

请参阅 references/dockerfile-patterns.md，查看特定语言的模板。

构建参数与密钥

至关重要： 切勿通过 ARG 传递密钥。 构建参数会存储在镜像的层中，可从镜像历史记录或中间层中恢复。

• 应优先使用运行时环境变量（Render 环境变量 / 密钥文件）存储应用程序密钥。
• 对于构建时密钥（例如私有软件包源），应使用 Docker BuildKit 密钥挂载（RUN --mount=type=secret,...），而不是 ARG。

所有敏感内容都应作为运行时密钥或通过 BuildKit 密钥挂载处理，而不是构建参数。

注册表配置

私有基础镜像（用于 runtime: docker）或预构建镜像（用于 runtime: image）需要身份验证：

• 在 Render Dashboard 的注册表凭据中存储凭据。
• 对于 runtime: docker，使用 registryCredential.fromRegistryCreds.name 引用私有基础镜像凭据。
• 对于 runtime: image，使用 image.creds.fromRegistryCreds.name 引用私有预构建镜像凭据。

支持常见注册表（Docker Hub、GHCR、ECR、Google Artifact Registry 等）。各提供商的分步说明：references/registry-setup.md。

预构建镜像服务不会在可变注册表标签变更时自动部署。发布新镜像后，请通过 Dashboard、受支持的 API 或部署钩子流程手动触发部署。优先使用不可变标签或摘要，以确保每次部署都指定明确的制品；完整的触发和验证工作流请参阅 references/deployments.md。

层缓存

• Render 会在构建之间缓存 Docker 层；请合理安排 Dockerfile 指令顺序，让经常不变的层靠前（参见 references/optimization-guide.md）。
• 标签和缓存：像 latest 这样的可变标签可能会解析为过期的缓存镜像。优先使用不可变引用：摘要（repo/image@sha256:...）或固定版本（v1.2.3）。

平台特性

• Render 使用 linux/amd64 构建。生产镜像中不要假定使用其他架构。
• 端口绑定与原生服务一致：将 HTTP 绑定到 0.0.0.0:$PORT（Render 会设置 PORT）。
• 健康检查遵循 references/deployments.md 中所述的相同平台行为。
• Render 提供的密钥文件位于 /etc/secrets/ 下——除非在镜像中明确复制或挂载，否则不要依赖容器内仓库根目录下的密钥路径。

.dockerignore 和启动命令

• 始终维护一个**.dockerignore，排除 node_modules、.git、.env**、构建产物、日志和操作系统杂项文件。这样可以缩短上下文上传时间，并避免将本地文件泄露到镜像层中。列表和说明：references/optimization-guide.md。
• **自定义启动命令：**如果需要执行多个 Shell 步骤，请使用单个 Shell 形式，例如 /bin/sh -c 'set -e; ./migrate && exec node server.js'（优先使用 exec，以便应用接收信号并优雅关闭）。

参考资料

文档	内容
references/dockerfile-patterns.md	多阶段模板（Node、Python、Go、Ruby、Rust、静态站点）
references/registry-setup.md	Docker Hub、GHCR、ECR、Artifact Registry + Blueprint 配置
references/optimization-guide.md	层顺序、.dockerignore、BuildKit 缓存挂载、调试
references/deployments.md	部署触发、生命周期、健康检查、关闭和验证

相关技能

• render-deploy — 部署流程、Blueprint 与 Dashboard、运维步骤
• render-blueprints — 完整的 render.yaml 架构、配置和验证
• render-web-services — Web 服务行为、健康检查和 HTTP 边缘情况

当前文档检索

每当此技能指示你查阅 Render 的当前文档时：

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

如果任务需要多个参考资料，请对每份资料都执行此流程，并区分已验证的文档与仍不可用的文档。