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文件关键配置项是控制平面地址和节点 tokenCONTROLLER_URLhttp://192.168.1.10:9910 NODE_TOKEN之前生成的长串token NODE_NAMEgpu-01 GPU_AUTO_DETECTtrue注意NODE_NAME要取一个好识别的名字比如gpu-01、render-node-3。如果你有多个节点名字一定不要重复否则控制台会出现两个相同名字的节点任务下发时容易造成混乱。启动 agentpython 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_type4090、locationshanghai、rolerender任务提交时可以通过tag字段指定运行环境实现“把渲染任务发给带渲染标签的节点、把训练任务发给 4090 节点”的效果。接入多节点时我建议按这四步来做先在控制台创建好节点标签模板确定每台机器的角色然后统一各节点的 agent 版本不要一台跑旧版一台跑新版接着用一条汇总命令检查所有节点健康状态最后用几个小型探针任务测试调度器能否正确把任务分配到指定节点。这个准备工作看似繁琐实际上能帮你省掉很多“任务跑错机器”的麻烦。标签路由的核心配置是节点上的.envNODE_TAGSgpu_type4090,rolerender提交任务时openrig task submit --file render_frame.yaml --tag rolerender只有当节点上的标签与任务指定的标签完全匹配并且资源满足条件时这个任务才会被调度过去。这一能力在混合负载场景下尤其关键渲染任务通常吃满显存和内存推理任务往往更看重延迟和 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 日志与离线问题速查表下面是我整理的一张问题速查表基本覆盖了部署和运行阶段的高频故障现象可能原因排查命令 / 做法节点一直显示 pendingagent 没有启动成功、token 不正确tail -f logs/agent.log核对.env中的NODE_TOKEN节点状态 online.task 却一直 queued可用显存不足、标签未匹配控制台查看节点的available_gpu_mem检查任务标签任务运行后立刻失败镜像拉取失败、命令不存在查看任务实际日志或先手动在节点上跑一次同样的命令管理界面无法打开端口未监听、防火墙拦截ss -lntp检查端口sudo ufw allow 9910任务日志不实时刷新WebSocket 连接中断刷新页面检查控制平面日志任务完成后产物找不到任务脚本没有拷贝产物在任务命令里显式cp到指定输出目录节点离线但进程存在网络抖动、心跳超时调开心跳超时时间校准系统时间数据库写入缓慢SQLite 锁竞争迁移到 PostgreSQL这张表是我在实践过程中一点点积累出来的每次遇到问题都往里面补一行。说实话这种工具类的项目真正让人崩溃的往往不是功能缺失而是信息不透明。所以我的建议是部署完 openrig 之后第一周不要急着把业务全部迁过来先用探针任务跑一个礼拜观察日志、心跳、任务流转是否稳定再逐步加大负载。综合来说openrig 目前的成熟度很适合中小团队把分散的 GPU 资源盘活。设计上它不搞大而全而是聚焦在节点管理、任务调度、日志回流这三件核心事情上。如果你手上正好有几台闲置的工作站与其让它们吃灰不如花一个下午把它部署起来跑上几个探针任务感受一下。等节点真正出活以后你会明显感觉到“提交任务、等结果”这个流程变得清爽很多。 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文件关键配置项是控制平面地址和节点 tokenCONTROLLER_URLhttp://192.168.1.10:9910 NODE_TOKEN之前生成的长串token NODE_NAMEgpu-01 GPU_AUTO_DETECTtrue注意NODE_NAME要取一个好识别的名字比如gpu-01、render-node-3。如果你有多个节点名字一定不要重复否则控制台会出现两个相同名字的节点任务下发时容易造成混乱。启动 agentpython 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_type4090、locationshanghai、rolerender任务提交时可以通过tag字段指定运行环境实现“把渲染任务发给带渲染标签的节点、把训练任务发给 4090 节点”的效果。接入多节点时我建议按这四步来做先在控制台创建好节点标签模板确定每台机器的角色然后统一各节点的 agent 版本不要一台跑旧版一台跑新版接着用一条汇总命令检查所有节点健康状态最后用几个小型探针任务测试调度器能否正确把任务分配到指定节点。这个准备工作看似繁琐实际上能帮你省掉很多“任务跑错机器”的麻烦。标签路由的核心配置是节点上的.envNODE_TAGSgpu_type4090,rolerender提交任务时openrig task submit --file render_frame.yaml --tag rolerender只有当节点上的标签与任务指定的标签完全匹配并且资源满足条件时这个任务才会被调度过去。这一能力在混合负载场景下尤其关键渲染任务通常吃满显存和内存推理任务往往更看重延迟和 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 日志与离线问题速查表下面是我整理的一张问题速查表基本覆盖了部署和运行阶段的高频故障现象可能原因排查命令 / 做法节点一直显示 pendingagent 没有启动成功、token 不正确tail -f logs/agent.log核对.env中的NODE_TOKEN节点状态 online.task 却一直 queued可用显存不足、标签未匹配控制台查看节点的available_gpu_mem检查任务标签任务运行后立刻失败镜像拉取失败、命令不存在查看任务实际日志或先手动在节点上跑一次同样的命令管理界面无法打开端口未监听、防火墙拦截ss -lntp检查端口sudo ufw allow 9910任务日志不实时刷新WebSocket 连接中断刷新页面检查控制平面日志任务完成后产物找不到任务脚本没有拷贝产物在任务命令里显式cp到指定输出目录节点离线但进程存在网络抖动、心跳超时调开心跳超时时间校准系统时间数据库写入缓慢SQLite 锁竞争迁移到 PostgreSQL这张表是我在实践过程中一点点积累出来的每次遇到问题都往里面补一行。说实话这种工具类的项目真正让人崩溃的往往不是功能缺失而是信息不透明。所以我的建议是部署完 openrig 之后第一周不要急着把业务全部迁过来先用探针任务跑一个礼拜观察日志、心跳、任务流转是否稳定再逐步加大负载。综合来说openrig 目前的成熟度很适合中小团队把分散的 GPU 资源盘活。设计上它不搞大而全而是聚焦在节点管理、任务调度、日志回流这三件核心事情上。如果你手上正好有几台闲置的工作站与其让它们吃灰不如花一个下午把它部署起来跑上几个探针任务感受一下。等节点真正出活以后你会明显感觉到“提交任务、等结果”这个流程变得清爽很多。