render-background-workers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Render Background Workers

Render 后台工作进程

This skill explains worker services on Render: processes that consume jobs from a queue instead of serving HTTP. Pair with render-blueprints, render-env-vars, and render-networking when wiring

render.yaml

and private connectivity.

本技能介绍Render上的工作进程（worker）服务：这类进程不提供HTTP服务，而是从队列中消费任务。在配置

render.yaml

和私有连接时，可搭配render-blueprints、render-env-vars和render-networking技能使用。

When to Use

使用场景

Designing or debugging queue-backed workers (Celery, Sidekiq, BullMQ, Asynq, etc.)
Choosing between a worker, Cron Job, or Workflow for background work
Configuring Render Key Value as a broker (not a cache) with correct eviction policy
Implementing graceful shutdown so in-flight jobs are not lost on deploy

Per-framework setup and signal-handling detail:

references/queue-framework-setup.md

references/graceful-shutdown.md

设计或调试基于队列的工作进程（Celery、Sidekiq、BullMQ、Asynq等）
为后台处理任务选择工作进程、定时任务（Cron Job）或工作流（Workflow）
将Render Key Value配置为消息代理（broker）（而非缓存），并设置正确的淘汰策略（eviction policy）
实现优雅停机，避免部署时丢失正在处理的任务

各框架的设置和信号处理细节可参考：

references/queue-framework-setup.md

、

references/graceful-shutdown.md

。

How Workers Work

工作进程的运行机制

Long-running services with no inbound (HTTP) traffic. Render does not expose a public URL or internal hostname for workers the way it does for web or private services—workers cannot receive private network traffic directed at them.
The typical pattern is a poll loop: the process connects to a queue backend (often Render Key Value, Redis-compatible Valkey 8) and pulls jobs.
Workers can initiate outbound connections on the private network—to PostgreSQL, Key Value, private services, web services (internal URLs), and the public internet—subject to your plan and firewall rules.

长期运行的服务，无入站（HTTP）流量。Render不会像Web服务或私有服务那样为工作进程提供公网URL或内部主机名——工作进程无法接收指向它们的私有网络流量。
典型模式是轮询循环：进程连接到队列后端（通常是Render Key Value、兼容Redis的Valkey 8）并拉取任务。
工作进程可发起出站连接，访问私有网络中的PostgreSQL、Key Value、私有服务、Web服务（内部URL）以及公网，具体取决于你的套餐和防火墙规则。

Queue Framework Overview

队列框架概览

Framework	Language	Queue backend	Notes
Celery	Python	Key Value	Most common Python task queue
Sidekiq	Ruby	Key Value	Standard for Rails
BullMQ	Node.js	Key Value	Modern Node queue
Asynq	Go	Key Value	Go async task processing
Oban	Elixir	Postgres (not a Key Value queue)	Queue stored in the database

框架	编程语言	队列后端	说明
Celery	Python	Key Value	最常用的Python任务队列
Sidekiq	Ruby	Key Value	Rails的标准队列方案
BullMQ	Node.js	Key Value	现代Node.js队列
Asynq	Go	Key Value	Go语言异步任务处理框架
Oban	Elixir	Postgres（非Key Value队列）	队列存储在数据库中

Pairing with Key Value

与Key Value服务搭配使用

Use Render Key Value as the job broker when your framework expects Redis.
Set maxmemory policy to noeviction
. allkeys-lru
and similar policies are for caches; evicting queue keys drops jobs.
Wire REDIS_URL
(or your framework’s equivalent) via fromService
with
```
type: keyvalue
```
and
```
property: connectionString
```
in the Blueprint.
Blueprints require
ipAllowList
on Key Value—include the CIDRs that should reach the instance (often
```
[]
```
for private-network-only access; see render-blueprints / Key Value field reference).

See

references/queue-framework-setup.md

for minimal app + YAML examples.

当你的框架需要Redis时，可将Render Key Value作为任务代理（job broker）。
将maxmemory policy设置为**
```
noeviction
```
。
```
allkeys-lru
```
及类似策略适用于缓存**；淘汰队列键会导致任务丢失。
在Blueprint中，通过**
```
fromService
```
配置
```
REDIS_URL
```
**（或框架对应的变量），设置
```
type: keyvalue
```
和
```
property: connectionString
```
。
Blueprint要求Key Value服务配置
ipAllowList
——添加允许访问实例的CIDR（通常设为
```
[]
```
以仅允许私有网络访问；详见render-blueprints / Key Value字段参考）。

如需最简应用+YAML示例，请查看

references/queue-framework-setup.md

。

Worker vs Cron vs Workflow

工作进程 vs 定时任务 vs 工作流

Need	Use	Why
Always-on queue consumer	Background Worker	Polls continuously; long-lived process
Periodic scheduled task	Cron Job	Runs on a schedule, exits; 12h max per run
Distributed parallel compute	Workflow	Each run gets its own instance; fan-out patterns
High-volume or bursty jobs	Workflow	Scales per run without a continuously running worker instance

需求	选择	原因
持续运行的队列消费者	后台工作进程	持续轮询；长期运行的进程
周期性调度任务	定时任务（Cron Job）	按计划运行，执行后退出；单次运行最长12小时
分布式并行计算	工作流（Workflow）	每次运行使用独立实例；支持扇出模式
高容量或突发任务	工作流（Workflow）	无需持续运行工作进程实例，可根据运行需求扩展

Graceful Shutdown

优雅停机

Before stopping an instance, Render sends SIGTERM
, then waits up to maxShutdownDelaySeconds
(1–300, default 30) before SIGKILL
.
Workers should: (1) stop accepting new jobs, (2) finish the current job or checkpoint progress, (3) close connections, (4) exit 0.
Set maxShutdownDelaySeconds
to at least your longest safe job duration (see Dashboard or Blueprint).

Language- and framework-specific handlers:

references/graceful-shutdown.md

在停止实例前，Render会发送**
```
SIGTERM
```
信号，然后等待最多
```
maxShutdownDelaySeconds
```
（取值范围1–300**，默认30），之后发送**
```
SIGKILL
```
**信号。
工作进程应：(1) 停止接收新任务，(2) 完成当前任务或保存检查点（checkpoint）进度，(3) 关闭连接，(4) 以状态码0退出。
将**
```
maxShutdownDelaySeconds
```
设置为至少等于你的最长安全任务时长**（可在控制台或Blueprint中配置）。

各语言和框架的具体处理方式可参考：

references/graceful-shutdown.md

。

Blueprint Configuration

Blueprint配置

Minimal pattern: type: worker
, runtime
, buildCommand
, startCommand
, and envVars
wired from Key Value.

yaml

services:
  - type: keyvalue
    name: jobs
    plan: starter
    region: oregon
    maxmemoryPolicy: noeviction
    ipAllowList: []

  - type: worker
    name: task-worker
    runtime: python
    region: oregon
    plan: starter
    buildCommand: pip install -r requirements.txt
    startCommand: celery -A tasks worker --loglevel=info
    envVars:
      - key: REDIS_URL
        fromService:
          name: jobs
          type: keyvalue
          property: connectionString

Optional: maxShutdownDelaySeconds
on the worker service for longer draining jobs.

最简模式：type: worker
、runtime
、buildCommand
、startCommand
，以及从Key Value服务配置的**

envVars

**。