RenderCtl Studio

RenderCtl Studio 是面向 Blender、优云智算 GPU 实例和直接 SSH 主机的多任务渲染控制台。安装一个 npm 包即可在本机打开 WebUI，完成连接配置、实例选择、硬件探测、.blend 导入、渲染提交、实时监控、断点下载、视频合成、结果验证和可选安全关机。

项目默认只在 127.0.0.1 提供服务。Windows 后台模式通过任务计划程序和隐藏启动器运行，不需要保留 CMD、PowerShell 或 Python 黑框。

主要能力

• 优云智算与 SSH 账号密码作为平行连接方式统一管理。
• 多连接、多项目和多任务统一管理。
• 同一 GPU 实例串行、不同实例并行，避免争抢显卡。
• 自动发现 Blender、Python、FFmpeg、GPU、显存、CPU、内存、磁盘和可写工作区。
• 直接调用 Blender 无界面自检，读取真实版本、Cycles 设备及 OPTIX/CUDA/HIP/ONEAPI/METAL 后端。
• AUTO 自动选择兼容的 Cycles GPU 后端；默认不悄悄回落到 CPU 渲染。
• Cycles 等渲染参数、帧范围、分辨率和监控标题均可配置。
• 自适应监控采样，不使用固定“8 秒周期”。
• PNG 帧断点续传，并按清单核对大小与 SHA-256。
• 自动生成 RGB24 无压缩母版和 H.264 成片，并验证分辨率、帧率、帧数和时长。
• 优云智算支持实例发现、开机、手动关机，以及交付验证通过后的可选自动关机；默认不自动关机。
• 随包提供配套 Codex Skill，帮助代理安全地操作和排查整套流水线。

环境要求

• 本地：Node.js 20 或更高版本。
• 云端实例：已经安装 Blender、Python 3 与对应 GPU 驱动。
• Windows 静默后台模式：Windows 10/11 与当前用户可用的任务计划程序。

FFmpeg、FFprobe、SSH、Web 服务和参数校验等本机依赖均由 npm 安装。云端 Blender 运行脚本使用实例已有的环境；探测与配置不会擅自在计费实例内安装或升级软件。

安装与启动

从 npm registry 安装：

npm install -g @zuens2020/renderctl-studio
renderctl-studio

从 GitHub Release 下载 .tgz 后安装：

npm install -g ./zuens2020-renderctl-studio-0.5.0.tgz
renderctl-studio

默认打开 http://127.0.0.1:8787。无浏览器启动：

renderctl-studio --no-open

Windows 静默运行

renderctl-studio background install
renderctl-studio background status
renderctl-studio open

停止或移除后台任务：

renderctl-studio background stop
renderctl-studio background uninstall

配套 Codex Skill

安装 npm 包后执行：

renderctl-studio skill install

查看安装位置：

renderctl-studio skill status

已有同名 Skill 时不会覆盖。确认更新后执行：

renderctl-studio skill install --force

使用流程

1. 启动 WebUI，在“资源”中配置优云智算账号，或填写 SSH 主机、端口、用户名与密码。
2. 选择已经准备好 Blender 环境的实例或 SSH 目标，运行“探测并配置”；推荐路径与 GPU 后端会自动回填。
3. 导入 .blend，填写项目名称与修订号。
4. 创建任务并配置帧、分辨率、采样、监控标题和交付格式。
5. 明确确认可能产生的云端计费后提交任务。
6. 控制台持续显示渲染、下载、编码和验证状态。
7. 优云智算任务只有在勾选“自动关机”且输出验证完成后才会关闭实例；直接 SSH 不执行开关机。

两种连接方式

| 能力 | 优云智算 | SSH 账号密码 | |---|---|---| | 发现目标 | 自动读取账号内实例 | 每个配置对应一台主机 | | Blender/GPU 探测 | 支持 | 支持 | | 开机与手动关机 | 支持，需要确认 | 不支持 | | 交付后自动关机 | 可选，默认关闭 | 不支持 | | 上传、监控、下载与验证 | 支持 | 支持 |

直接 SSH 可在 WebUI 配置，也可使用 CLI。密码从环境变量读取，避免进入 shell 历史：

RENDERCTL_SSH_PASSWORD='…' renderctl-ssh connection set render-box \
  --host gpu.example.com --port 22 --username render
renderctl-ssh target configure --connection render-box --device AUTO

云端环境自动探测

默认将 Blender、Python 和 Cycles 设备设为 auto / AUTO。两种连接方式使用相同的两层探测：先通过 SSH 发现可执行文件、系统资源和 GPU 驱动，再启动一次 Blender --background --factory-startup 自检实际可用的 Cycles 后端。报告按连接和目标保存在本机，任务提交时会重新探测，避免镜像、驱动或路径变化后沿用旧配置。

命令行也可只读探测或保存建议：

renderctl-compshare instance probe INSTANCE_ID
renderctl-compshare instance configure INSTANCE_ID --device AUTO

configure 只保存本机配置，不启动实例、不安装软件。目标必须已处于可 SSH 连接状态；优云智算实例启停仍要求单独明确确认。

详细说明见使用手册。

安全边界

• 优云智算私钥和 SSH 密码只保存在本机数据目录，不返回到 WebUI 状态接口。
• WebUI 默认不监听局域网或公网地址。
• 实例启停、任务提交、远端取消和账号删除必须显式确认。
• 监控暂时不可达时不会自动重复提交渲染。
• 未验证完整清单、全部帧和最终输出时，不会把任务标记为完成或关闭云机。

开发

npm ci
npm run check
npm test
npm run pack:verify

本项目采用 MIT License。