render-workflows

Render Workflows

Render Workflows 是一款基于 SDK 的产品，用于编排长时间运行的分布式任务。工作流服务会将 Python 或 TypeScript 函数注册为任务；每次任务运行都会独立执行，并可串联其他运行。

在 Workflow、cron 作业和后台工作进程之间进行选择时，请阅读 references/service-types.md。

使用 Render SDK 1.x API（Python 使用 render>=1.0.1，TypeScript 使用 @renderinc/sdk 1.x 版本）。本地验证需要 Render CLI 2.12.0 或更高版本。使用完整的可选脚手架和 CLI 部署流程时，需要 CLI 2.16.0 或更高版本。优先使用最新的兼容版本。

Render Workflows 及其 SDK 可能会引入不兼容变更。对于现有项目，应以已安装的 SDK 版本为准。对于新项目，请使用当前官方文档和入门模板。

检查当前资料

生成或修改 SDK 代码之前，请先确认已安装的版本：

render --version
python -m pip show render
npm ls @renderinc/sdk

如果尚未安装 Render CLI：

• macOS：brew install render
• Linux/macOS：curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh
• Windows：从 CLI releases page 下载可执行文件

根据问题使用相应资料：

• Python SDK reference，用于查看 Python 签名和最低版本要求
• TypeScript SDK reference，用于查看 TypeScript 签名和最低版本要求
• Render CLI reference，用于查看当前命令和标志
• Defining Workflow Tasks，用于了解任务行为和运行串联
• Limits and Pricing for Render Workflows，用于了解计算方案、配额、保留期限和定价
• Python examples 和 TypeScript examples，用于了解当前脚手架模式
• Render SDK repository，用于查看实现和变更日志

生成任务或客户端代码之前，请获取相关 SDK 示例，以验证当前 API 模式：

内容	Python	TypeScript
任务定义（子任务、重试、扇出）	example/task/main.py	examples/task/
客户端（运行、启动、取消、流式传输、列出运行）	example/client/main.py	examples/client/
异步客户端	example/client/async_main.py	—

不要在不说明的情况下升级现有项目的 SDK 主版本。如果请求包含升级，请阅读相关 SDK 变更日志，并同时迁移所有任务定义和调用方。

SDK 1.x 不变量

在生成的代码中遵循以下规则：

• Python 安装并导入的是 render 包，而不是 render_sdk。
• 每个任务函数都必须将 TaskContext 作为第一个位置参数。Render 会提供它；调用方不得将它包含在任务输入中。
• 使用 await ctx.run(task_definition, ...args) 串联任务运行。任务定义不能直接调用。
• ctx.run 链中的所有任务都属于同一个工作流服务。通过 SDK 客户端或 Render API 触发另一个工作流。
• Python 在工作流入口点调用 app.start()。TypeScript 任务注册会在工作流环境中自动启动。
• 任务参数和返回值必须可序列化为 JSON。

编写 SDK 代码时，请阅读 references/quick-reference.md。有关链式调用、扇出、重试、定时触发或跨工作流调用，请阅读 references/task-patterns.md。

选择起点

不要要求运行 render workflows init。在现有代码库中，直接添加 SDK 和任务定义，保留项目的依赖与构建约定，并使用本地开发服务器进行验证。对于精简项目或直接集成指南，请阅读 references/manual-scaffolding.md。

可选的入门脚手架

如果用户想要一个快速示例项目或新的独立工作流服务，请使用 CLI 脚手架：

render workflows init

对于非交互式设置，请明确传入语言和目标位置：

render workflows init --confirm --language python --dir workflows --git=false
render workflows init --confirm --language node --dir workflows --git=false

在现有 Git 仓库中创建脚手架时，使用 --git=false，以避免创建嵌套仓库。其他实用选项包括 --template、--install-deps 和 --install-agent-skill；请在 CLI 参考中确认当前行为。

使用 SDK 在本地试用

首次集成时，请按照可运行的 Python 或 TypeScript 本地 SDK 演练操作：定义 ping，启动本地任务服务器，从单独的客户端脚本调用它，并验证返回的 "pong"。此本地示例无需 init、部署或 Render API 密钥。请在调用应用程序的进程中设置本地模式，而不仅仅是在任务服务器的环境中设置。

添加或更改 SDK 任务定义后，请将本地开发服务器作为主要验证流程。使用工作流的实际启动命令启动它：

render workflows dev -- <workflow-start-command>

在另一个终端中，针对本地服务器列出并运行任务：

render workflows tasks list --local
render workflows start <task-name> --local --input='[]' -o json
render workflows tasks runs show <task-run-id> --local -o json

如果任务未出现在本地任务列表中，请参阅故障排除 > 本地任务列表为空或缺少任务。

位置参数输入请使用 JSON 数组。Python 任务也可以接收 JSON 对象作为命名输入。有关环境文件、自定义端口、运行检查、取消和应用客户端配置，请阅读 references/local-development.md。

在非交互模式下，workflows start 会在运行未必完成前返回新的任务运行 ID。使用该 ID 调用 tasks runs show，并在有界时间内轮询，直到运行完成、失败或取消。请验证结果或错误，而不只是确认运行已创建。

在安全且可行的情况下，请自行运行此验证，并在之后停止开发服务器。不要仅凭检查源代码就声称任务已成功注册。

本地验证后再部署

创建或发布工作流会更改用户的 Render 账户。只有当请求包含部署，且任务已在本地验证（支持本地执行时）后，才进行部署。

部署前或解读部署状态前，请阅读 references/deployments.md，其中包括工作流专属的任务注册行为。

部署前，请先进行身份验证并确认目标工作区：

render whoami
render workspace current

如果尚未通过身份验证，请使用 render login 进行交互式本地会话，或通过环境提供 RENDER_API_KEY 以用于自动化。切勿输出密钥。

确认目标分支和区域，并确保要部署的确切代码已提交并推送到 GitHub、GitLab 或 Bitbucket。这两种方式都不会部署未提交的本地更改。

有两种创建方式。MCP 两者都不支持。

方式	适用情况	运行时
Blueprint（render.yaml）	仓库使用 IaC，或工作流与其他 Render 服务一同发布	python、node
render workflows create 或 Dashboard	独立工作流，不使用 Blueprint	python、node、go、ruby、elixir，以及仅限 Dashboard 的 Docker

使用 Blueprint 部署（首选）

不要在工作流服务上设置 plan。任务计算配置在代码中（任务上的 plan），而不是服务上。

services:
  - type: workflow
    name: my-workflow
    runtime: python
    region: oregon
    repo: https://github.com/render-examples/render-workflows-examples-python
    branch: main
    rootDir: hello-world
    buildCommand: pip install -r requirements.txt
    startCommand: python main.py
    envVars:
      - key: RENDER_API_KEY
        sync: false

TypeScript 变体：使用 runtime: node、buildCommand: npm install，以及运行项目工作流入口点的 startCommand。TypeScript 起始模板使用 npm start（tsx src/main.ts）；references/manual-scaffolding.md 中的手动设置使用 npm run workflows:start。这两个命令都应与 package.json 中的脚本相符。仅当项目定义了会生成 dist/main.js 的 build 脚本时，才使用 npm run build 和 node dist/main.js。

必填项：type、name、runtime、region、startCommand，以及 buildCommand 和 repo。可选项：branch、rootDir、buildFilter、autoDeployTrigger、envVars（应用于每次任务运行）。

Schema 的 required 数组只列出了前五项。不要将其视为完整列表：缺少 buildCommand 或 repo 的工作流也会被验证器拒绝。

• buildCommand is required for non-docker workflows。只有基于 Docker 的工作流可以省略构建命令，而这类工作流无法出现在 Blueprint 中，因此 Blueprint 工作流始终需要构建命令。
• repo is required for git-based services。即使在该仓库内验证且存在 origin 远程地址，也会触发此错误；这与 web 及其他基于 Git 的类型的行为不同。

注意事项：

• 预览环境会跳过工作流服务，但其他 Blueprint 资源仍会复制。
• 如果工作区中已存在同名的 Blueprint 管理型工作流，Render 会拒绝会创建同名工作流的 Blueprint。
• Workflows 入门 FAQ 可能仍称 Blueprint 无法管理工作流。这一说法已过时。请以更新日志和 https://render.com/schema/render.yaml.json 为准。

应用前先验证：

render blueprints validate

验证通过并不能证明运行时受支持。当前，即使 Schema 不允许在工作流中使用 runtime: docker，render blueprints validate 仍会接受它。

搭配 render-blueprints 处理接线配置，并使用 render-deploy 处理应用和深层链接流程。

使用 CLI 或 Dashboard 创建

对于不使用 Blueprint 的独立工作流，请使用此方式。交互模式会提示你进行配置：

render workflows create

非交互模式使用起始模板中的构建和运行命令，或项目现有的配置：

render workflows create \
  --name my-workflow \
  --repo . \
  --branch <branch> \
  --region <region> \
  --runtime python \
  --build-command "pip install -r requirements.txt" \
  --run-command "python main.py"

--repo . 会解析仓库的远程地址。对于位于子目录中的工作流，请添加 --root-directory。可以通过可重复使用的 --env-file 和 --env-var 标志传入环境变量。切勿在命令或输出中暴露机密。

工作流可以从 Dockerfile 构建，但只能通过 Dashboard（New > Workflow）创建：CLI 和 API 无法创建此类工作流，Blueprint 也不行。基于 Docker 的工作流不需要构建命令，也无法在本地任务服务器上运行。任何创建方式都无法拉取预构建的镜像仓库镜像。

如需后续显式发布，请使用：

render workflows versions release <workflow-id> \
  --commit <pushed-commit-sha> \
  --wait

不能仅凭命令已被接受就报告部署成功。请等待发布完成，然后验证预期任务已注册，并且有一个安全任务以预期结果进入终止状态：

render workflows versions list <workflow-id> -o text
render workflows tasks list <ready-workflow-version-id> -o text
render workflows start <workflow-slug>/<task-name> --input='[]' -o json
render workflows tasks runs show <task-run-id> -o json

如果运行仍在排队或运行中，请在有限时间内轮询 tasks runs show。若发布或任务出错，请停止并报告错误，而不要无限期重试外部变更操作。

如果部署失败，请阅读 references/troubleshooting.md。如果有 render-debug 技能可用，请使用它进行更广泛的 Render 部署诊断。

触发已部署的任务

任务 slug 格式为 {workflow-slug}/{task-name}。

Python，同步：

from render import Render

render = Render()
result = render.workflows.run_task("my-workflow/hello", ["world"])
print(result.results)

Python，异步：

from render import RenderAsync

render = RenderAsync()
started = await render.workflows.start_task("my-workflow/hello", ["world"])
finished = await started
print(finished.results)

TypeScript：

import { Render } from "@renderinc/sdk";

const render = new Render();
const started = await render.workflows.startTask("my-workflow/hello", ["world"]);
const finished = await started.get();
console.log(finished.results);

除非显式传入令牌，否则这些客户端会使用 RENDER_API_KEY。请优先使用环境变量或机密管理器，而不要硬编码凭据。

工作流目前不提供原生定时触发器。需要定时执行时，请使用调用 SDK 客户端或 API 的 Render cron 作业。

限制、计算计划和定价

请勿在此技能或其参考资料中硬编码计算计划 ID、资源规格、配额、保留期限或价格。

在设置任务的 plan、估算成本或提供容量建议之前，请查阅 references/compute-plans.md 和 Render Workflows 的限制与定价。技能中只保留编写正确代码所需的 API 形式约束。

参考资料

• references/quick-reference.md：SDK 1.x 的任务和客户端接口
• references/compute-plans.md：任务 plan 值的当前计算计划指南
• references/deployments.md：部署生命周期和 Workflow 任务注册
• references/service-types.md：如何在 Workflows 与其他服务类型之间进行选择
• references/task-patterns.md：任务链式调用、扇出、重试、cron 触发器和跨工作流调用
• references/local-development.md：本地服务器、CLI 运行、环境配置和限制
• references/troubleshooting.md：常见的设置、注册、执行和客户端故障
• references/manual-scaffolding.md：不使用 workflows init 直接设置 SDK 项目

相关技能

• render-blueprints：在 render.yaml 中设置 type: workflow、预览和连接配置
• render-deploy：包含工作流的多服务应用的 Blueprint 应用流程
• render-debug：诊断部署和运行时故障
• render-monitor：检查服务运行状况和性能

当前文档检索

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

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

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