render-docker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Render Docker Deployments

Render Docker 部署

Render uses BuildKit for Docker builds. All compute service types that support custom runtimes can use runtime: docker
(build from a Dockerfile in the repo) or runtime: image
(pull a prebuilt image; no Dockerfile build on Render). Deeper patterns and copy-paste templates live under

references/

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

references/

目录下。

When to Use

适用场景

Authoring or debugging a Dockerfile for a Render service
Choosing runtime: docker
vs runtime: image
in a Blueprint
Wiring private base images or prebuilt images with registry credentials
Multi-stage builds, build args, secrets, and layer caching
Performance and security hardening of container images on Render

For full Blueprint authoring, see render-blueprints. For end-to-end deploy flows, see render-deploy.

为Render服务编写或调试 Dockerfile
在Blueprint中选择 runtime: docker
还是 runtime: image
为私有基础镜像或预构建镜像配置仓库凭证
多阶段构建、构建参数、密钥和层缓存相关操作
在Render上对容器镜像进行性能和安全加固

如需完整的Blueprint编写指南，请查看 render-blueprints。如需端到端部署流程，请查看 render-deploy。

Render Docker Builds

Render Docker 构建

BuildKit is used for Docker builds on Render.
runtime: docker
: Render builds an image from your repo using
```
dockerfilePath
```
,
```
dockerContext
```
, and optional
```
dockerCommand
```
(overrides image
```
CMD
```
).
runtime: image
: Render pulls image.url
; no repo-based image build. Pair with registryCredential
when the registry is private.

Render上的Docker构建使用 BuildKit。
runtime: docker
：Render使用
```
dockerfilePath
```
、
```
dockerContext
```
和可选的
```
dockerCommand
```
（覆盖镜像的
```
CMD
```
）从你的仓库构建镜像。
runtime: image
：Render拉取 image.url
指定的镜像；不基于仓库构建镜像。当仓库为私有时，需搭配 registryCredential
使用。

Blueprint Configuration

Blueprint 配置

Field	Role
`dockerfilePath`	Path to the Dockerfile (default `./Dockerfile` )
`dockerContext`	Build context directory (what is sent to the daemon)
`dockerCommand`	Overrides the container `CMD` after the image is built
`image.url`	Image reference for `runtime: image` (registry/repo:tag or digest)
`registryCredential`	Auth for private pulls; often `fromRegistryCreds` → Dashboard-stored credential

Example sketch (values illustrative):

yaml

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

For

runtime: image

, set

image.url

and, if needed,

registryCredential

per Registry Configuration below.

字段	作用
`dockerfilePath`	Dockerfile的路径（默认值为 `./Dockerfile` ）
`dockerContext`	构建上下文目录（即发送给守护进程的内容）
`dockerCommand`	镜像构建完成后覆盖容器的 `CMD`
`image.url`	`runtime: image` 模式下的镜像引用（仓库/镜像:标签或摘要）
`registryCredential`	私有镜像拉取的认证信息；通常使用 `fromRegistryCreds` 关联存储在Dashboard中的凭证

示例配置（仅作演示）：

yaml

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

，若有需要，可按照下方仓库配置设置

registryCredential

。

Multi-Stage Builds

多阶段构建

Recommended for production. Use a builder stage for compilation and dependency installation, and a minimal runner stage that only copies artifacts and runtime files. Benefits:

Smaller images and faster pulls
Fewer tools and secrets in the final image (smaller attack surface)
Clear separation between build-time and run-time dependencies

See

references/dockerfile-patterns.md

for language-specific templates.

生产环境推荐使用。使用一个构建器阶段进行编译和依赖安装，再使用一个精简的运行器阶段仅复制产物和运行时文件。优势如下：

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

如需语言特定模板，请查看

references/dockerfile-patterns.md

。

Build Args vs Secrets

构建参数 vs 密钥

Critical: Never pass secrets via
ARG
. Build arguments are stored in image layers and can be recovered from the image history or intermediate layers.

Prefer runtime environment variables (Render env vars / secret files) for application secrets.
For build-time secrets (e.g. private package feeds), use Docker BuildKit secret mounts (
```
RUN --mount=type=secret,...
```
) rather than
```
ARG
```
.

Treat anything sensitive as runtime or BuildKit secret mount, not as a build arg.

重点注意： 切勿通过
ARG
传递密钥。构建参数会存储在镜像层中，可从镜像历史或中间层恢复。

应用密钥优先使用运行时环境变量（Render的环境变量/密钥文件）。
对于构建时密钥（如私有包源），请使用 Docker BuildKit密钥挂载（
```
RUN --mount=type=secret,...
```
）而非
```
ARG
```
。

任何敏感信息都应作为运行时变量或BuildKit密钥挂载处理，而非构建参数。

Registry Configuration

仓库配置

Private base images (for

runtime: docker

) or prebuilt images (

runtime: image

) need authentication:

Store credentials in the Render Dashboard under Registry Credentials.
In Blueprint, reference them with registryCredential.fromRegistryCreds.name
(match the Dashboard name).

Supports common registries (Docker Hub, GHCR, ECR, Google Artifact Registry, and others). Step-by-step per provider:

references/registry-setup.md

Prebuilt image services do not auto-deploy when the tag moves in the registry; trigger a manual redeploy or use a deploy hook when you publish a new image.

私有基础镜像（用于

runtime: docker

）或预构建镜像（

runtime: image

）需要进行身份认证：

在Render Dashboard的Registry Credentials中存储凭证。
在Blueprint中，通过 registryCredential.fromRegistryCreds.name
引用这些凭证（需与Dashboard中的名称匹配）。

支持常见镜像仓库（Docker Hub、GHCR、ECR、Google Artifact Registry等）。各提供商的分步指南请查看

references/registry-setup.md

。

预构建镜像服务不会在仓库中标签更新时自动部署；发布新镜像时，请触发手动重新部署或使用部署钩子。

Layer Caching

层缓存

Render caches Docker layers between builds; order Dockerfile instructions so that frequently unchanged layers stay early (see
```
references/optimization-guide.md
```
).
Tags and caching: mutable tags like latest
can resolve to stale cached images. Prefer immutable references: digest (
```
repo/image@sha256:...
```
) or version pins (
```
v1.2.3
```
).

Render在构建之间会缓存Docker层；调整Dockerfile指令顺序，让不常变更的层排在前面（详情请查看
```
references/optimization-guide.md
```
）。
标签与缓存：像**
```
latest
```
这类可变标签可能会解析为过期缓存的镜像。优先使用不可变引用：摘要（
repo/image@sha256:...
）或版本固定标签**（
```
v1.2.3
```
）。

Platform Specifics

平台细节

Render builds linux/amd64. Avoid assumptions about other architectures in production images.
Port binding matches native services: bind HTTP to 0.0.0.0:$PORT
(Render sets
```
PORT
```
).
Health checks behave like non-Docker web services (
```
healthCheckPath
```
, etc.).
Secret files from Render appear under /etc/secrets/
— do not rely on repo-root secret paths inside the container unless you copy or mount them explicitly in the image.

Render构建 linux/amd64 架构的镜像。生产环境镜像中请勿假设其他架构。
端口绑定与原生服务一致：将HTTP绑定到 0.0.0.0:$PORT
（Render会设置
```
PORT
```
变量）。
健康检查的行为与非Docker Web服务一致（如
```
healthCheckPath
```
等字段）。
Render提供的密钥文件位于 /etc/secrets/
目录下——除非你在镜像中明确复制或挂载，否则不要依赖容器内仓库根目录的密钥路径。

.dockerignore

and Start Commands

.dockerignore

与启动命令

Always maintain a .dockerignore
that excludes node_modules
, .git
, .env
, build artifacts, logs, and OS junk. This shrinks context upload time and avoids leaking local files into layers. Lists and rationale:
```
references/optimization-guide.md
```
.
Custom start command: if you need multiple shell steps, use a single shell form, e.g. /bin/sh -c 'set -e; ./migrate && exec node server.js'
(prefer exec
so your app receives signals for graceful shutdown).

务必维护一个 .dockerignore
文件，排除 node_modules
、.git
、.env
、构建产物、日志和系统垃圾文件。这会缩小上下文上传时间，避免本地文件泄露到镜像层中。详细列表和原理请查看
```
references/optimization-guide.md
```
。
自定义启动命令：如果需要多个Shell步骤，请使用单个Shell命令形式，例如 /bin/sh -c 'set -e; ./migrate && exec node server.js'
（优先使用 exec
，以便你的应用接收信号实现优雅关闭）。

References

参考文档

Document	Contents
`references/dockerfile-patterns.md`	Multi-stage templates (Node, Python, Go, Ruby, Rust, static sites)
`references/registry-setup.md`	Docker Hub, GHCR, ECR, Artifact Registry + Blueprint wiring
`references/optimization-guide.md`	Layer order, `.dockerignore` , BuildKit cache mounts, debugging

文档	内容
`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缓存挂载、调试指南