render-web-services

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Render Web Services

Render Web服务

This skill covers Web Service behavior on Render: how traffic reaches your process, how deploys go live, and how optional features (domains, disks, auto-deploy) interact. Use it alongside Blueprint and networking skills when wiring

render.yaml

or Dashboard settings.

本技能涵盖Render上的Web服务行为：流量如何到达你的进程、部署如何上线，以及可选功能（域名、磁盘、自动部署）之间的交互方式。在配置

render.yaml

或控制台设置时，可结合Blueprint和网络相关技能使用。

When to Use

使用场景

Configuring or debugging port binding, PORT, or multi-port web services
TLS/HTTPS expectations at the edge vs inside the container
Health checks blocking or rolling back deploys
Custom domains, DNS, and certificate provisioning
Auto-deploy, CI-gated deploys, and PR preview generation
Persistent disks and their impact on scaling and zero-downtime
Deploy lifecycle: build, pre-deploy, swap, drain, rollback, shutdown delay

Deeper patterns live under

references/

(health checks, domains, deploy phases).

配置或调试端口绑定、PORT或多端口Web服务
边缘节点与容器内部的TLS/HTTPS配置预期
健康检查阻止部署或触发回滚的情况
自定义域名、DNS及证书颁发
自动部署、CI校验部署和PR预览生成
持久化磁盘及其对扩容和零停机的影响
部署生命周期：构建、预部署、切换、流量排空、回滚、关机延迟

更深入的模式请查看

references/

目录下的内容（健康检查、域名、部署阶段）。

Port Binding

端口绑定

Listen on 0.0.0.0
(all interfaces). Binding only to localhost
or 127.0.0.1
prevents Render’s proxy from reaching your app.
Use the PORT
environment variable for the HTTP listen port. Render sets it for you; the default is often
10000
and you can change the configured value in the service Settings in the Dashboard.
Reserved ports (do not bind your application to these for normal traffic): 18012
, 18013
, 19099
.

监听**
```
0.0.0.0
```
（所有网络接口）。仅绑定到
```
localhost
```
或
```
127.0.0.1
```
**会导致Render的代理无法访问你的应用。
使用**
```
PORT
```
环境变量指定HTTP监听端口。Render会自动设置该变量，默认值通常为
10000
，你可以在控制台的服务设置**中修改配置值。
保留端口（正常流量请勿将应用绑定到这些端口）：18012
、18013
、19099
。

Multi-port Web Services

多端口Web服务

Only one port receives public HTTP traffic: the port aligned with PORT
.
Additional open ports are reachable on Render’s private network only (not from the public internet through the same public URL pattern).

只有与**
```
PORT
```
一致的端口会接收公开**HTTP流量。
其他开放端口仅能在Render的私有网络内访问（无法通过公网URL模式从互联网访问）。

TLS and HTTPS

TLS与HTTPS

TLS terminates at Render’s edge. The edge speaks HTTPS to clients; your process typically receives plain HTTP on
```
PORT
```
.
HTTPS redirect for clients is handled by the platform; users hitting HTTP are redirected appropriately at the edge.
Do not terminate TLS inside the app for the primary public listener unless you have a rare, explicit need—standard Web Services assume HTTP behind the proxy.

TLS在Render边缘节点终止。边缘节点与客户端通过HTTPS通信；你的进程通常在
```
PORT
```
上接收纯HTTP请求。
客户端的HTTPS重定向由平台处理；访问HTTP的用户会在边缘节点被自动重定向。
除非有特殊明确需求，否则不要在应用内部为主公开监听器终止TLS——标准Web服务默认代理后使用HTTP。

Health Checks

健康检查

Configure a path via healthCheckPath
in a Blueprint or the Health Check Path field in the Dashboard.
Render issues HTTP GET requests to that path. Responses must be 2xx
or
3xx
for success.
Failed health checks prevent a new deploy from going live (the deploy does not succeed in taking production traffic as expected).
Render probes on a repeat interval with a per-request timeout; both are configurable in service settings (see Dashboard). Failed checks during rollout prevent the new revision from receiving traffic.
Check frequency, timeouts, and tuning guidance in
```
references/health-check-patterns.md
```
.

通过Blueprint中的**
```
healthCheckPath
```
或控制台的健康检查路径**字段配置检查路径。
Render会向该路径发送HTTP GET请求。响应状态码为**
```
2xx
```
或
```
3xx
```
**时视为检查成功。
健康检查失败会阻止新部署上线（部署无法按预期接管生产流量）。
Render会按照重复间隔进行探测，每个请求有超时时间；两者均可在服务设置中配置（请查看控制台）。部署过程中检查失败会阻止新版本接收流量。
检查频率、超时时间及调优指南请查看
```
references/health-check-patterns.md
```
。

Custom Domains

自定义域名

Point DNS with a CNAME to [service-name].onrender.com
(use your service’s hostname from the Dashboard).
Render automatically provisions and renews TLS certificates for verified domains.
Apex (root) domains need provider-specific CNAME-like or flattened records where plain CNAME at
```
@
```
is unsupported.
Wildcard domains (e.g.
```
*.example.com
```
) are supported when configured and verified.
Multiple custom domains per service are supported; Blueprints can list them under the domains
field.

See

references/custom-domains.md

for Dashboard steps, verification, and troubleshooting.

将DNS的CNAME记录指向**
```
[service-name].onrender.com
```
**（使用控制台中你的服务主机名）。
Render会为已验证的域名自动颁发并续期TLS证书。
顶级（根）域名在不支持
```
@
```
记录使用纯CNAME的情况下，需要使用服务商特定的类CNAME或扁平化记录。
配置并验证后，支持通配符域名（例如
```
*.example.com
```
）。
每个服务支持多个自定义域名；Blueprint可在**
```
domains
```
**字段中列出这些域名。

控制台操作步骤、验证及排查方法请查看

references/custom-domains.md

。

Auto-Deploy and PR Previews

自动部署与PR预览

autoDeployTrigger
(Blueprint) / auto-deploy settings control when production deploys run:
- commit
  — deploy on every push to the tracked branch
- checksPass
  — deploy only when required Git checks pass
- off
  — manual deploys only (Dashboard, CLI, hooks)
PR previews are configured under Blueprint previews.generation
(and related preview settings); generation behavior depends on repo integration and plan.

autoDeployTrigger
（Blueprint）/自动部署设置控制生产环境部署的触发时机：
- commit
  — 每次向跟踪分支推送代码时触发部署
- checksPass
  — 仅当所需Git检查通过时触发部署
- off
  — 仅支持手动部署（控制台、CLI、钩子）
PR预览在Blueprint的**
```
previews.generation
```
**（及相关预览设置）中配置；生成行为取决于仓库集成和套餐计划。

Persistent Disks

持久化磁盘

Attach disks via the disk
field in a Blueprint (or equivalent Dashboard storage settings).
A service with an attached persistent disk is single-instance only: horizontal scaling is not available in that configuration.
Zero-downtime deploys are disabled when a persistent disk is attached—deploys follow a different rollout pattern.
Disk size increases are allowed; decreases are not.
The disk is not mounted during the build phase—only at runtime in the running service.

通过Blueprint中的**
```
disk
```
**字段（或控制台中对应的存储设置）挂载磁盘。
挂载了持久化磁盘的服务只能是单实例：该配置下不支持水平扩容。
挂载持久化磁盘时零停机部署会被禁用——部署将遵循不同的发布模式。
允许增大磁盘容量；不允许减小。
磁盘不会在构建阶段挂载——仅在运行中的服务运行时挂载。

Deploy Lifecycle

部署生命周期

Typical flow:

Build — clone repo, run buildCommand
, produce the runnable artifact/image.
Pre-deploy command (optional) — runs in the new image before traffic switches; use for migrations. If it fails, the deploy is canceled.
Deploy — new instances start; health checks must pass before traffic moves.
Zero-downtime swap (when applicable) — traffic shifts to new instances; old instances drain in-flight work.

maxShutdownDelaySeconds
(range 1–300, default 30) bounds how long old instances may continue handling requests during drain before shutdown.
Rollbacks — revert to a previous successful deploy from the Dashboard.

Full sequence, hooks, filters, and CLI notes:

references/deploy-lifecycle.md

典型流程：

构建 — 克隆仓库，执行**
```
buildCommand
```
**，生成可运行的工件/镜像。
预部署命令（可选）——在流量切换前在新镜像中执行；用于数据迁移。如果命令执行失败，部署将被取消。
部署 — 启动新实例；健康检查通过后才会切换流量。
零停机切换（适用时）——流量转移到新实例；旧实例排空正在处理的请求。

maxShutdownDelaySeconds
（范围1–300，默认30）限制旧实例在排空期间处理请求的最长时间，超时后将关机。
回滚 — 从控制台恢复到之前的成功部署版本。

完整流程、钩子、过滤器及CLI说明请查看

references/deploy-lifecycle.md

。

Free Tier Notes

免费套餐说明

Free Web Services have separate limits: services spin down after inactivity (cold starts on the next request), and they do not support scaling beyond a single instance or persistent disks. Treat free-tier behavior as distinct from paid Web Service defaults when advising on uptime and scaling.

免费Web服务有单独的限制：服务在闲置后会自动停止（下次请求时会冷启动），且不支持单实例以外的扩容或持久化磁盘。在提供可用性和扩容建议时，请区分免费套餐与付费Web服务的默认行为。

References

参考资料

Topic	File
Health check design, timeouts, pitfalls	`references/health-check-patterns.md`
Domains, DNS, TLS verification	`references/custom-domains.md`
Build, pre-deploy, drain, rollbacks, triggers	`references/deploy-lifecycle.md`

主题	文件
健康检查设计、超时、常见问题	`references/health-check-patterns.md`
域名、DNS、TLS验证	`references/custom-domains.md`
构建、预部署、流量排空、回滚、触发器	`references/deploy-lifecycle.md`