openrig：从零构建GPU算力池与任务调度平台

1. 项目拆解与整体设计思路

1.1 名称背后的定位密码

我第一次看到“openrig”这个项目名称时，第一反应是“嗯，又是一个渲染器管理工具吧”，但仔细拆开这个词组会发现完全不是这么简单。openrig 由 open 和 rig 拼接而成，其中 open 强调的是开放生态、自托管、可扩展，而 rig 在影视渲染、深度学习工作站和算力调度的语境里，通常指的是“一台干了重活的机器”，比如 render node、GPU 工作站、推理服务器。所以 openrig 这个词的核心含义是：把零散分布的多台 GPU 机器/工作站统一管起来，组成一套可调度的算力池，并通过一套明确的任务队列和监控机制对外提供服务。

在真正接触这类工具之前，很多人对“算力管理”的理解停留在“我有几台机器闲着，SSH 上去敲命令跑一跑就完事”。但实际生产环境中，你就会发现这根本不可行。我见过一个工作室，三台渲染节点分别放在不同机位，系统版本不一致，显卡驱动版本不一致，有人要用其中一台跑模型推理，有人要渲染，还有人在上面跑数据清洗，最后常常因为端口冲突和资源抢占吵成一团。openrig 这类工具想解决的，就是这种多用户、多节点、多任务场景下的编排问题。

这个项目适合谁参考？一是小团队或独立开发者，手里有 2 到 5 台闲置 GPU 机器，希望统一调度；二是影视渲染、3D 设计工作室，需要把多台渲染节点纳入统一任务分发；三是做算法工程、模型推理、批量数据处理的技术团队，希望把任务提交、执行、结果回收流程化。它不适合那种“我就一台机器、单用户、自己用”的场景，因为这种场景下你直接跑终端反而更省事。

1.2 核心模块与工作流程

openrig 的整体工作流程，本质上是一个“控制平面 + 执行节点 + 客户端”的三层结构。管理者通过控制平面（通常是个 Web 服务或后台守护进程）统一接收任务、做优先级排序和调度；执行节点（rig）注册到控制平面之后，会主动上报自身的 GPU 类型、显存容量、当前负载、健康状态；而客户端则是你提交任务时用的入口，可以是命令行工具、API 接口，也可以是集成了 Web 页面的前端。

任务提交之后的流转过程大致是：客户端向管理者提交一个任务描述，里面包含执行镜像、命令、资源需求（比如需要 12GB 显存、需要 4 核 CPU）；管理者把它放入任务队列，根据各 rig 上报的空闲资源和标签匹配规则，选中一个合适的节点，下发执行指令；rig 端收到指令后开始准备运行环境、拉取镜像、执行脚本，并把运行日志实时回传给控制平面；任务结束后，rig 上报退出码、输出文件路径、资源用量。这一整套流程下来，业务方基本不需要关心任务到底跑在哪个机器上，只知道“我提交了、完成了、结果在这些路径里”。

这种“队列 + 心跳 + 租约”的调度模型，是我认为 openrig 这类工具最值得学习的地方。它没有采用很多自研平台常见的“中心化自动分配 IP 直连”做法，而是让每个节点主动 poll 任务。原因很好理解：中心化直连需要控制平面能直接访问到每个执行节点，但在真实网络环境中，很多机器躲在 NAT 后面，或者有防火墙限制，主动上报反而要简单得多。心跳机制也解决了节点失联的判定问题，如果一个节点超过 N 秒没有上报心跳，管理者就能及时把它的未完成任务重新排队，避免任务卡死。

1.3 为什么选用“任务镜像 + 调度队列”而不是直接命令下发

如果你只是想在远程机器上执行一句命令，直接 SSH + nohup 也能做到，但你会发现同样的问题出现：环境不一致、依赖冲突、日志丢失、占用的端口没人释放。openrig 引入任务镜像的思想，本质上就是给每个任务一个沙箱环境。任务不再“污染”宿主机的 Python 环境，也不会因为 A 项目需要 TensorFlow 2.4、B 项目需要 TensorFlow 2.10 而互相打架。

调度队列的意义就更大了。它把任务的执行和硬件资源的分配解耦开。我提交任务时，不需要关心“现在哪个机器闲着”，只需要描述“我需要多大的显存、大概跑多久”。调度器会自动维护一个优先级队列，高优先级的任务插队，相同优先级的按提交时间先后执行，资源不足时任务继续等待而不是失败。这个设计对渲染农场尤其友好：渲染帧任务数量多、单个任务耗时短、并发量高，如果没有队列，很难做到合理的负载均衡。

从选型角度来说，openrig 没有自己造一套完整的容器编排系统，而是聚焦在“任务调度 + 节点管理”这个层面，底层执行环境可以对接容器，也可以直接使用裸机 Python 虚拟环境。这个取舍非常务实。你要知道，很多小团队连 Kubernetes 都维护不明白，如果 openrig 强行上 K8s 做底座，学习成本和部署成本都会高到没人愿意用。相比之下，它选择轻量方案：每个节点只装一个 agent，控制平面可以单机运行，数据量也不大，这恰好能落在中小规模团队的承受范围内。

2. 核心功能拆解与部署前准备

2.1 关键功能点一览

我实际跑通 openrig 之后，把它的核心能力整理成了一张功能清单，你可以对照自己团队的场景逐一确认是否需要。

• 节点注册与管理：每台机器安装 agent 后自动注册，控制台能看到节点在线状态、GPU 型号、显存占用、任务记录。
• 任务队列与优先级：支持 FIFO 排队，也支持给不同任务设置优先级；队列满时任务不丢弃，持续等待空余资源。
• 多用户与访问控制：可以创建多个用户，每个用户有自己的认证 token，任务的归属和审计日志按用户维度隔离。
• 日志实时回流：任务在 rig 上执行时，stdout 和 stderr 会实时推送到控制平面，业务方不用登录节点就能看日志。
• 资源配额限制：可以限定某个用户最多占用多少显存、同时运行几个任务，防止一个人把全池资源耗光。
• 任务镜像管理：每个任务可以绑定一个镜像或环境描述，执行前自动准备环境，执行后自动销毁临时资源。
• 健康检查与自动重排：节点心跳超时或执行异常退出时，管理者会标记任务状态并把任务重新放入队列。

这些功能单独拿出来看都不是什么黑科技，但组合在一起就比较实用了。我见过不少团队自己写脚本做任务调度，写着写着就开始头疼：这个节点掉线了怎么办、任务跑到一半崩溃了日志在哪、两个任务同时写同一个输出目录怎么办。openrig 把这些问题全部收口了，剩下的只是你往里面填业务逻辑。

2.2 部署前的依赖规划

在动手部署 openrig 之前，我强烈建议你先梳理清楚自己的运行环境，别拿到代码就急着跑，后面处处踩坑。

控制平面这边，通常需要 Python 3.10 或更高版本，依赖的第三方库集中在 FastAPI、SQLAlchemy、Redis 客户端上。数据存储方面，openrig 默认可以使用 SQLite 起步，但如果你要跑多个节点、任务并发量上来之后，建议换成 PostgreSQL，否则并发写入会明显变慢。Redis 主要用作任务队列的暂存层，不是强制依赖，但开启了会舒服很多，特别是任务分发时要快速掌握节点状态。

执行节点这边，系统要求相对简单，只要是 Linux 系统，安装了 Python 3，并且具备 GPU 驱动和 CUDA 环境就能运行。需要注意的是节点主机的 GPU 驱动版本决定了你能跑什么版本的 CUDA，也就决定了任务镜像里预装的深度学习框架是否可用。这是最容易出问题的地方之一。如果你打算在节点上用 Docker 方式执行任务，还得确保 Docker 的 GPU runtime 配置正确，nvidia-container-toolkit装到位，否则容器内部根本看不到显卡。

网络规划我也多说一句。控制平面和节点之间有控制流，节点之间默认不互通，所以整体网络模型比较安全。但控制平面的管理端口最好只在内网监听，不要直接暴露到公网。如果你确实需要远程访问管理界面，建议用反向代理加 HTTPS。认证方面，控制平面与节点之间使用预共享 token 通信，这个 token 一旦泄露，别人就能往你的算力池里恶意提交任务，所以部署后第一件事就是换掉默认 token。

2.3 资源需求估算与场景匹配

在部署之前，很多人会问：我需要一台多大的机器来跑控制平面？我的经验是，控制平面本身非常轻，2 核 4GB 内存的虚拟机就足够支撑 50 个以内的活跃节点。真正吃资源的是执行节点上的任务。

比如影视渲染场景，一个 Blender 渲染任务可能吃满 32GB 内存和 12GB 显存，那么你在配置任务资源需求时就得写清楚gpu_mem: 12g，调度器才会把它放到有足够显存余量的节点上。而深度学习推理任务，单任务显存需求往往在 4GB 到 8GB 之间，并发任务多，调度器会频繁做资源匹配。这里有一个建议：任务资源需求不要拍脑袋写，先跑一个典型的真实任务，用nvidia-smi观察峰值占用，然后上浮 20% 余量写入任务描述。写少了任务会 OOM，写多了又会造成资源碎片，导致并发上不去。

我粗略估算过一个典型场景：5 台节点的算力池，每台节点 2 张 RTX 3090，控制平面单机部署，SQLite 存储，无 Redis，任务以渲染为主，平均每帧渲染 3 分钟。这种情况下，队列吞吐能力完全取决于 GPU 数量，控制平面没有任何压力。只有当任务频率极高（每秒数十个）时，才需要考虑把存储换成 PostgreSQL 并接入 Redis。

3. 实操过程与核心环节实现

3.1 快速搭建控制平面与首个节点

下面我以一个全新的 Ubuntu 22.04 服务器和一台 Ubuntu 20.04 工作站为例，演示从零搭建 openrig 并跑通第一个任务的完整过程。这里用的是开源社区最常见的中小型部署方案。

第一步，在控制平面服务器上安装基础依赖并拉取项目代码：

sudo apt update sudo apt install -y python3 python3-venv python3-pip git git clone https://github.com/openrig/openrig-controller.git cd openrig-controller python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

这里我特意先创建了虚拟环境，避免把依赖直接装到系统 Python 里。openrig 的依赖里有 FastAPI、httpx、APScheduler 等一堆库，直接全局装很容易跟系统包冲突，尤其是 Ubuntu 这种用 apt 管理 Python 包的系统。

第二步，初始化配置文件和数据库：

cp .env.example .env python manage.py init-db python manage.py create-user --username admin --password YourPasswd123 python manage.py generate-token --username admin

这里生成的 token 后面要用到，建议先存到密码管理器里。openrig 的初始化和 Django 管理命令风格很像，基本上只要你按顺序执行init-db和create-user，控制平面的数据库表和默认用户就建好了。

第三步，启动控制平面：

python manage.py runserver --host 0.0.0.0 --port 9910

如果你没有改配置，管理界面默认监听 9910 端口，浏览器访问http://服务器IP:9910就能看到控制台。我建议你--host不要直接写0.0.0.0，除非你已经做好了防火墙和反向代理。我本地测试时图省事直接绑了 0.0.0.0，结果被扫描工具撞了很多次。

接着在节点机器上安装 agent。这一步是重复性最高、也是最容易出错的一步，因为每台机器的系统环境多少都有些差异。

git clone https://github.com/openrig/openrig-agent.git cd openrig-agent python3 -m venv venv source venv/bin/activate pip install -r requirements.txt cp .env.example .env

然后编辑.env文件，关键配置项是控制平面地址和节点 token：

CONTROLLER_URL=http://192.168.1.10:9910 NODE_TOKEN=之前生成的长串token NODE_NAME=gpu-01 GPU_AUTO_DETECT=true

注意NODE_NAME要取一个好识别的名字，比如gpu-01、render-node-3。如果你有多个节点，名字一定不要重复，否则控制台会出现两个相同名字的节点，任务下发时容易造成混乱。

启动 agent：

python agent.py start --daemon

然后回到控制平面刷新页面，正常情况下你会看到gpu-01出现在节点列表里，状态从pending变成online。这一步如果看到节点一直显示pending或者离线，多半是服务端防火墙挡掉了 agent 的主动上报连接，或者 token 填错了，可以先在 agent 端敲tail -f logs/agent.log查看具体报错。

3.2 提交第一条任务并观察调度过程

节点接入成功后，我们提交一个最简单的 GPU 检测任务，验证链路是否通透。openrig 提供了 CLI 客户端，也可以在管理界面上直接操作，这里我用 CLI 示例：

pip install openrig-cli openrig configure --controller http://192.168.1.10:9910 --token 你的token cat > gpu_check.yaml <<'EOF' name: gpu-check-task image: python:3.10-slim gpu_mem: 1g command: nvidia-smi EOF openrig task submit --file gpu_check.yaml

提交后立刻查看任务状态：

openrig task list openrig task logs --task-id <task_id>

如果你是按上面的步骤走的，任务会经过queued -> running -> succeeded三个阶段，日志里能看到nvidia-smi输出的显卡信息。这里有个细节值得注意：任务描述里写了gpu_mem: 1g，意味着即使我们只是执行一句nvidia-smi，调度器也会找一个显存空闲超过 1GB 的节点来执行。这也是资源配额机制的雏形：资源描述越精确，调度就越合理。

如果任务一直卡在queued，通常原因有两个：一是当前没有任何一个节点上报的可用显存满足任务需求；二是节点虽然在线，但 agent 的资源上报没有成功。解决思路是去控制台的节点详情页看available_gpu_mem字段，如果显示为 0 或者为空，说明 agent 在探测 GPU 时出了问题，大概率是宿主机上nvidia-smi命令本身就不通。

3.3 常用配置项与参数调优

openrig 的配置集中在控制平面的config.yaml中，典型的可调参数有：

• 心跳超时时间：默认是 60 秒。如果你网络环境不太稳定，可以调大到 120 秒，但不要调太大，否则节点已经挂了，调度器还傻傻地等它恢复。
• 任务最大执行时间：默认 3600 秒。渲染任务或者模型训练任务往往超过 1 小时，这一步需要按实际情况放宽，否则任务到点会被强制杀掉。
• 节点并发任务上限：默认每个节点同时只执行 1 个任务。如果你节点上有 2 张卡，希望并行跑 2 个任务，可以设置为 GPU 数量。
• 日志保留天数：默认 7 天，排查问题时效性比较短，建议调到 30 天。
• 任务结果保留策略：默认执行完就清理临时文件，如果你要保存产物，需要指定输出目录，并在任务脚本里主动把产物拷贝过去。

我实际在跑渲染任务时，会把任务最大执行时间调成 0（表示不限时），因为一个高复杂度场景的单帧渲染可能跑 20 分钟，而一个序列任务要连续渲染上百帧，限时反而会给运维增加不少负担。这里建议你结合自己的业务对任务做个分类：短任务和长任务分成不同队列，给长任务单独设置更宽的超时时间。

3.4 接入多节点与标签路由

当你只有一台节点时，openrig 的价值还没完全体现出来；当你接入第二台、第三台节点时，调度才开始变得有意思。openrig 支持给节点打标签，比如gpu_type=4090、location=shanghai、role=render，任务提交时可以通过tag字段指定运行环境，实现“把渲染任务发给带渲染标签的节点、把训练任务发给 4090 节点”的效果。

接入多节点时我建议按这四步来做：先在控制台创建好节点标签模板，确定每台机器的角色；然后统一各节点的 agent 版本，不要一台跑旧版一台跑新版；接着用一条汇总命令检查所有节点健康状态；最后用几个小型探针任务测试调度器能否正确把任务分配到指定节点。这个准备工作看似繁琐，实际上能帮你省掉很多“任务跑错机器”的麻烦。

标签路由的核心配置是节点上的.env：

NODE_TAGS=gpu_type=4090,role=render

提交任务时：

openrig task submit --file render_frame.yaml --tag role=render

只有当节点上的标签与任务指定的标签完全匹配，并且资源满足条件时，这个任务才会被调度过去。这一能力在混合负载场景下尤其关键：渲染任务通常吃满显存和内存，推理任务往往更看重延迟和 GPU 吞吐，两者混跑会互相干扰，用标签拆开之后，各跑各的，互不干扰。

4. 常见问题与排查技巧实录

4.1 节点离线但进程仍在

这个问题我遇到很多次。表现是控制台显示节点离线，但你登录到节点机器上发现 agent 进程还活着，nvidia-smi也正常。原因通常是 agent 和控制器之间的心跳消息在某个时间点被网络中断了，之后 agent 进入重连循环，而控制器在超时后把节点标记为离线。

排查这类问题，建议先看 agent 日志有没有connection reset或timeout字样。如果是网络抖动导致的，可以考虑把心跳间隔调长一点，同时在控制器端设置“节点离线后保留多长时间再标记失败”，避免任务被过早重排队。还有一种低频原因：agent 所在机器的系统时间与控制平面服务器时间差得太多，心跳报文里的时间戳被判定为无效。遇到这种就直接用ntpdate或systemctl restart systemd-timesyncd校准时间戳。

4.2 任务一直卡在 queued

任务提交后一直停留在 queued，一般是资源匹配失败。你可以去控制台查看节点的“可用资源”一栏，如果显示总显存为 0，说明 agent 没有成功探测到 GPU；如果显示总显存正常但可用显存很低，说明可能是某些僵尸任务占用了显存没有释放。

有一种隐蔽情况是：节点 GPU 被别的进程占用了，不是 openrig 的任务，比如有人在宿主机上手动跑了一个 Python 脚本占了几 GB 显存。openrig 的 agent 默认只统计自身任务占用的显存，不会去实时扫描宿主机上所有进程的显存占用，所以调度器可能以为显存足够，把任务发过去后 OOM。解决办法是把gpu_mem需求调大一点，或者干脆在节点上做显存白名单，把手动跑任务的通道全部关掉。

4.3 容器任务看不到 GPU

如果你在任务里使用了容器作为运行环境，执行nvidia-smi发现报错could not select device，说明容器 GPU 支持没配好。宿主机需要安装nvidia-container-toolkit，并确保 Docker 的默认 runtime 指向nvidia。

排查时可以执行docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi验证。如果这条命令都不通，那就不是 openrig 的问题，是 Docker 层的 GPU 支持没配置好。配置完成后重启 Docker 服务，再重新提交任务就行。值得注意的一点是：不同节点的显卡驱动版本可能不同，容器镜像内安装的 CUDA 版本必须与驱动兼容，这是一个镜像层面的坑。比如我在一个驱动版本 525 的节点上跑 CUDA 11.8 的镜像没问题，但换到驱动版本 470 的节点上，任务直接崩溃，日志里是一堆CUDA initialization failed的错误。

4.4 token 泄漏与权限管理

openrig 的 token 设计比较简单，一个用户一个 token。如果你发现某个节点失联、任务异常，或者有人在你没提交任务的时候突然提交了一堆任务，那就要立刻怀疑 token 泄露了。处理方式：去控制台重新生成 token，然后逐台节点更新.env里的NODE_TOKEN，更新后重启 agent。

我建议把 token 的权限控制在最小范围内：控制平面的管理员 token 只给一到两个人；普通业务人员只用自己的账号；节点的 token 专门用于节点接入，跟用户 token 区分开。如果业务上需要对外开放任务提交入口，建议在前面加一层网关做二次校验，不要直接把控制平面的端口暴露出去。

4.5 日志与离线问题速查表

下面是我整理的一张问题速查表，基本覆盖了部署和运行阶段的高频故障：

这张表是我在实践过程中一点点积累出来的，每次遇到问题都往里面补一行。说实话，这种工具类的项目，真正让人崩溃的往往不是功能缺失，而是信息不透明。所以我的建议是：部署完 openrig 之后，第一周不要急着把业务全部迁过来，先用探针任务跑一个礼拜，观察日志、心跳、任务流转是否稳定，再逐步加大负载。

综合来说，openrig 目前的成熟度很适合中小团队把分散的 GPU 资源盘活。设计上它不搞大而全，而是聚焦在节点管理、任务调度、日志回流这三件核心事情上。如果你手上正好有几台闲置的工作站，与其让它们吃灰，不如花一个下午把它部署起来，跑上几个探针任务感受一下。等节点真正出活以后，你会明显感觉到“提交任务、等结果”这个流程变得清爽很多。