Juice使用指南：用juicify让任意应用透明访问远程GPU的完整教程

Juice使用指南：用juicify让任意应用透明访问远程GPU的完整教程

【免费下载链接】Juice-LabsJuice Community Version Public Release项目地址: https://gitcode.com/gh_mirrors/ju/Juice-Labs

Juice 是一款 GPU-over-IP（网络GPU）客户端/服务器软件：在装有物理 GPU 的机器上运行 Juice Server，任意一台运行 Juice Client 的电脑即可通过网络透明访问这块 GPU。配合juicify命令行工具，无需修改任何应用代码，用一条命令就能让本地没有显卡的应用直接跑在远程 GPU 上。本文是面向新手的完整教程，带你 3 步完成远程 GPU 透明访问。

为什么需要 Juice？远程GPU的痛点

GPU 算力的使用有一个天然限制：吃 GPU 的应用必须和 GPU 在同一台物理机上。这导致两个极端问题——

• 🖥️ 终端设备（笔记本、云桌面、瘦客户端）根本装不下、也带不动大功率显卡
• 📉 机房里的高端 GPU 大量闲置，利用率普遍低于 15%

Juice 把"应用所在主机"和"物理 GPU"解耦：客户端与服务器均可运行在物理机、虚拟机或容器上，同时支持 Linux 和 Windows。唯一硬性要求：有一块 GPU 可供服务，客户端与服务器之间网络连通。

整体架构：Juice 的三大核心组件

客户端应用完全感知不到 GPU 是远程的，这就是"透明访问"的含义。

快速上手：3 步完成远程 GPU 透明访问

第 1 步：在 GPU 机器上启动 Juice Server（Agent）

# 监听 0.0.0.0:43210，把本机 GPU 暴露到网络 juice-agent

如果需要启用 HTTPS，可加--generate-cert自动生成证书（证书生成逻辑见 cmd/agent/main.go）。

第 2 步：在应用机器上安装 Juice Client 与 juicify

Client 和 juicify 一起分发（Linux 为JuiceClient包），二者放在同一目录即可。

第 3 步：用 juicify 启动你的任意应用

# 语法：juicify [选项] <应用> [应用参数] juicify --address=192.168.1.100 my-gpu-app --width 1920

就这样！my-gpu-app会"透明地"在远程 GPU 上运行。

如何用 juicify 配置连接？常用参数速查

juicify 的所有命令行参数定义在 cmd/juicify/app/juicify.go：

💡 小技巧：也可以把servers、accessToken、requirements等配置写入 juicify 同目录下的juice.cfg文件，之后直接juicify <应用>即可，无需每次传参（配置读取逻辑同样在 cmd/juicify/app/juicify.go）。

juicify 的透明原理：应用为什么毫无感知？

在 Linux 上，juicify 获取到 GPU 会话后会注入两组环境变量再启动你的应用（实现见 cmd/juicify/app/juicify_linux.go）：

1. VK_ICD_FILENAMES/VK_DRIVER_FILES指向 Juice 自带的JuiceVlk.json——Vulkan 驱动被悄悄替换为 Juice 的远程驱动
2. LD_PRELOAD注入libjuicejuda.so——图形 API 调用被透明重定向到网络

因此任何基于 Vulkan 的应用（游戏、渲染器、AI 推理框架）都无需改动一行代码。会话在 pkg/restapi/types.go 中定义了queued → assigned → active → closed的完整生命周期，juicify 会轮询等待会话变为active后才真正启动应用。

如何启动 Juice Server？Agent 参数说明

Agent 的启动参数定义在 cmd/agent/app/agent.go：

在 Docker 中部署时，需要加--gpus all将 GPU 直通进容器，详细说明见 docker/server/README.md。

进阶：用 Controller 统一管理多台 GPU

当 GPU 超过 1 台时，建议部署 Controller（源码入口 cmd/controller/main.go）：

• 会话调度：多个客户端共享同一张卡，按需动态分配，显著提高 GPU 利用率
• 资源池（Pool）与权限：按池分组管理 GPU，create_session、register_agent、admin三级权限控制（定义见 pkg/restapi/types.go）
• 监控：内置 Prometheus 端点，可采集 GPU 利用率、显存占用、温度、功耗、风扇转速等指标（GpuMetrics结构见 pkg/restapi/types.go）
• 存储：默认 SQLite 文件controller.db，也支持 PostgreSQL（初始化脚本见 cmd/controller/storage/postgres/scripts/）

# 启动 Controller：8080 端口 + 前端 + 后端 juice-controller --frontend --backend

常见问题排查清单

项目关键文件导航

• 🚀 juicify 主程序与参数定义：cmd/juicify/app/juicify.go
• 🐧 Linux 下透明注入实现：cmd/juicify/app/juicify_linux.go
• 🖥️ Windows 客户端实现：cmd/juicify/app/juicify_windows.go
• 📡 Agent（GPU 端）入口：cmd/agent/main.go
• 🎛️ Controller（调度中心）入口：cmd/controller/main.go
• 🧾 REST API 与指标类型定义：pkg/restapi/types.go
• 🐳 GPU 端 Docker 部署文档：docker/server/README.md
• 🐳 客户端 Docker 镜像构建：docker/client/Dockerfile

如需从源码构建全部组件，可克隆仓库后运行构建脚本 Build-All.ps1（Windows）：

git clone https://gitcode.com/gh_mirrors/ju/Juice-Labs

小结

Juice 用 GPU-over-IP 的方式把显卡变成了"网络服务"，而juicify是它最优雅的入口：一条命令，零代码修改，任意应用透明跑在远程 GPU 上。无论是给无显卡的笔记本加速 3D 渲染，还是把机房闲置的 GPU 池化共享给整个团队，这套 3 步流程都能让你快速落地。

【免费下载链接】Juice-LabsJuice Community Version Public Release项目地址: https://gitcode.com/gh_mirrors/ju/Juice-Labs