render-background-workers

Render 后台工作进程

本技能介绍 Render 上的 工作进程 服务：这类进程会从队列中 消费任务，而非提供 HTTP 服务。配置 render.yaml 和私有连接时，可搭配 render-blueprints、render-env-vars 和 render-networking 使用。

适用场景

• 设计或调试 基于队列的工作进程（Celery、Sidekiq、BullMQ、Asynq 等）
• 在后台工作中选择 工作进程、Cron Job 还是 Workflow
• 将 Render Key Value 配置为 代理（而非缓存），并设置正确的 驱逐策略
• 实现 优雅关闭，避免部署时丢失正在处理的任务

各框架的设置与信号处理详情：references/queue-framework-setup.md、references/graceful-shutdown.md。

部署、重启或更改关闭行为之前，请阅读 references/deployments.md。 配置或排查工作进程的出站私有网络连接之前，请阅读 references/private-networking.md。 在工作进程、cron job 和 Workflow 之间进行选择时，请阅读 references/service-types.md。

工作进程的工作方式

• 长期运行的服务，没有入站（HTTP）流量。Render 不会像对 Web 服务或私有服务那样，为工作进程提供公共 URL 或内部主机名——工作进程无法接收发往它们的私有网络流量。
• 常见模式是 轮询循环：进程连接到 队列后端（通常是 Render Key Value，与 Redis 兼容的 Valkey 8）并 拉取任务。
• 工作进程可以在私有网络上发起出站连接，连接到 PostgreSQL、Key Value、私有服务、Web 服务（内部 URL）和公共互联网，但须遵循你的套餐和防火墙规则。

队列框架概览

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

与 Key Value 搭配使用

• 当你的框架需要 Redis 时，请使用 Render Key Value 作为 任务代理。
• 将 maxmemory policy 设为 noeviction。allkeys-lru 等策略适用于 缓存；驱逐队列键会 丢失任务。
• 在 Blueprint 中，通过 type: keyvalue 和 property: connectionString 使用 fromService 配置 REDIS_URL（或框架的等效变量）。
• Blueprint 要求 Key Value 配置 ipAllowList——请加入应能访问该实例的 CIDR（通常仅限私有网络访问时设为 []；参见 render-blueprints / Key Value 字段参考）。

最简应用和 YAML 示例见 references/queue-framework-setup.md。

工作进程、Cron 与 Workflow 的区别

需求	使用	原因
始终运行的队列消费者	后台工作进程	持续轮询；长期运行的进程
定期执行的计划任务	Cron Job	按计划运行并 退出；每次运行最长 12h
分布式并行计算	Workflow	每次运行都会获得自己的实例；支持扇出模式
高吞吐量或突发性任务	Workflow	按运行扩缩容，无需持续运行的工作进程实例

优雅关闭

• 工作进程应当：(1) 停止接收新任务，(2) 完成当前任务或 保存进度检查点，(3) 关闭连接，(4) 以 0 退出。
• 请参阅 references/deployments.md，了解 Render 当前的连接排空、信号和关闭延迟行为。

特定语言和框架的处理程序：references/graceful-shutdown.md。

Blueprint 配置

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

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

可选：在工作进程服务上设置 maxShutdownDelaySeconds，以便为需要更长排空时间的任务留出时间。

参考资料

主题	文件
Celery、Sidekiq、BullMQ、Asynq、Oban 设置 + YAML	references/queue-framework-setup.md
SIGTERM、maxShutdownDelaySeconds、各语言模式	references/graceful-shutdown.md
部署生命周期、关停、重启和验证	references/deployments.md
专用网络范围、内部地址和故障排查	references/private-networking.md
服务类型选择和执行模型	references/service-types.md

相关技能

• render-deploy — 首次部署、CLI、创建服务
• render-blueprints — 完整的 render.yaml 架构、fromService、项目
• render-networking — 专用 URL、调用关系
• render-scaling — Worker 方案、实例数量、限制

获取当前文档

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

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

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