教程

ComfyUI 部署指南：LTX-2.3 视频生成模型从环境配置到上线全流程

从零开始在阿里云 L20 48GB GPU 服务器上部署 ComfyUI 并跑通 Lightricks LTX-2.3 视频生成模型的完整教程。涵盖 GPU 环境检查、PyTorch 与 CUDA 安装、ComfyUI 与 Manager 部署、HuggingFace 国内镜像配置与登录、模型与 LoRA 多 tmux 并行下载、阿里云安全组放行、显存不足（OOM）应对方案等关键环节，附 L20 / A100 / A10 实测显卡选型建议。

阅读时长: 7 分钟
共 3317字
作者: eimoon.com
#ComfyUI #LTX-2.3 #AI 视频生成 #模型部署 #GPU

这是一份在云 GPU 服务器上部署 ComfyUI 并跑通 Lightricks LTX-2.3 视频生成模型的完整教程，从环境检查、依赖安装、模型下载，到端口放行和显存优化，每一步都给出可直接复制的命令。

官方资源

服务器配置要求

  • GPU：NVIDIA L20 48GB / A100 40GB+ / H100 / RTX 4090 24GB（推荐 L20 或更高）
  • 系统：Ubuntu 22.04 LTS
  • CUDA 驱动：已预装

显卡选型说明（实测）

显卡 显存 跑 LTX-2.3 22B fp8 备注
A10 24GB ❌ 跑不起来 主模型 + Gemma 文本编码器加载就 OOM
RTX 4090 24GB ⚠️ 勉强（必须 --lowvram） 速度慢，可作开发测试
L20 48GB ✅ 推荐 阿里云性价比之选，本教程实测平台
A100 40/80GB ✅ 推荐 高负载、批量生成场景
H100 80GB ✅ 旗舰 多任务并行

⚠️ A10 24GB 无法运行本教程的 fp8 主模型 + Gemma 12B 文本编码器组合。即使加 --lowvram，加载 Gemma 时也会 OOM。最低建议 40GB 显存以上的卡。

💡 本教程基于云厂商提供的 GPU 镜像，开机即自带 NVIDIA 驱动和 CUDA 环境（阿里云、腾讯云、AutoDL 等都有类似的 “Ubuntu 22.04 + GPU Driver + CUDA” 公共镜像可选）。如果你用的是纯净系统，需要先自行安装 NVIDIA 驱动和 CUDA Toolkit，再继续后面的步骤。

一、确认环境

# 确认驱动和 CUDA 版本
nvidia-smi

# 确认 CUDA toolkit（有输出说明已装，报错不影响，PyTorch 自带 runtime）
nvcc --version

二、安装依赖

# 安装 PyTorch（CUDA 12.8，L20 / Ada / Hopper 推荐）
pip install torch torchvision torchaudio \
  --index-url https://download.pytorch.org/whl/cu128

# 验证 GPU 是否可用
python3 -c "import torch; print(torch.cuda.is_available())"
# 输出 True 即正常

# 安装 huggingface 下载工具
pip install huggingface_hub hf_transfer

三、安装 ComfyUI

git clone https://github.com/comfyanonymous/ComfyUI
cd ComfyUI
pip install -r requirements.txt

四、安装 ComfyUI Manager

cd ~/ComfyUI/custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager

五、配置 HuggingFace 镜像（国内服务器必须）

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
echo 'export HF_HUB_ENABLE_HF_TRANSFER=1' >> ~/.bashrc
source ~/.bashrc

六、下载模型

登录 HuggingFace（可选但强烈推荐）

下载公开模型本身不要求登录，但登录后有两个好处：

  • 提高限流阈值：未登录用户限流更严，并行下载容易触发 429 错误
  • 可下载 gated 模型：部分模型（如 Llama 系列）需要先在网页上 “Agree and access” 后才能下载

第一步：获取 token

  1. 访问 https://huggingface.co/settings/tokens
  2. 点击 Create new token
  3. Type 选 Read（只下载用 Read 即可，不要给 Write 权限）
  4. 命名比如 comfyui-server，点击创建
  5. 复制生成的 hf_... 字符串（只显示一次，丢了只能重新生成）

第二步：在服务器上登录

# 交互式登录（推荐）
hf auth login

按提示粘贴 token 后回车。

⚠️ 粘贴 token 时看不到回显是正常的，直接粘完按回车即可。 提示 Add token as git credential? (Y/n) 时一般选 n。

或者使用环境变量（适合脚本/自动化）：

echo 'export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

验证登录状态：

hf auth whoami

显示用户名即登录成功。

模型直链（可手动浏览器下载）

checkpoints

loras

latent_upscale_models

text_encoders

模型目录结构

ComfyUI/models/
├── checkpoints/
│   └── ltx-2.3-22b-dev-fp8.safetensors
├── loras/
│   ├── ltx-2.3-22b-distilled-lora-384.safetensors
│   └── gemma-3-12b-it-abliterated_lora_rank64_bf16.safetensors
├── latent_upscale_models/
│   └── ltx-2.3-spatial-upscaler-x2-1.1.safetensors
└── text_encoders/                                 # 官方目录树未列出，但实际运行需要
    └── gemma_3_12B_it_fp8_e4m3fn.safetensors

💡 官方说明里 models/ 目录树不包含 text_encoders/，但 LTX-2.3 在 ComfyUI 中需要通过 LTXAVTextEncoderLoader 节点加载 Gemma 文本编码器，因此必须额外下载并放入 text_encoders/ 目录。

安装 tmux

模型文件较大（合计约 50GB+），强烈建议在 tmux 中下载，防止 SSH 断开导致下载中断。

apt install tmux -y

下面提供两种下载方案，推荐方案 B（并行），速度可以快 3–5 倍。

方案 A：串行下载（单 session）

适合带宽一般或想保持简单的场景。

# 新建 session
tmux new -s download

# 在 session 中依次执行（按 Ctrl+B 再按 D 可挂到后台）
# 主模型 fp8（29.1GB）
cd ~/ComfyUI/models/checkpoints
hf download Lightricks/LTX-2.3-fp8 \
  ltx-2.3-22b-dev-fp8.safetensors --local-dir .

# 空间超分模型（996MB）
cd ~/ComfyUI/models/latent_upscale_models
hf download Lightricks/LTX-2.3 \
  ltx-2.3-spatial-upscaler-x2-1.1.safetensors --local-dir .

# Distilled LoRA（7.61GB）
cd ~/ComfyUI/models/loras
hf download Lightricks/LTX-2.3 \
  ltx-2.3-22b-distilled-lora-384.safetensors --local-dir .

# Gemma LoRA
cd ~/ComfyUI/models/loras
hf download Comfy-Org/ltx-2 \
  split_files/loras/gemma-3-12b-it-abliterated_lora_rank64_bf16.safetensors \
  --local-dir .

# Gemma 文本编码器 fp8（推荐，13.2GB，通用兼容）
cd ~/ComfyUI/models/text_encoders
hf download GitMylo/LTX-2-comfy_gemma_fp8_e4m3fn \
  gemma_3_12B_it_fp8_e4m3fn.safetensors --local-dir .

方案 B：并行下载（推荐）

阿里云 GPU 实例通常有几 Gbps 出口带宽，单个 hf download 用不满。开多个 tmux session 并行下载能跑满总带宽，5 个左右是性价比最高的并发数。

# 主模型 fp8（29.1GB）
tmux new -s dl-main -d \
  "cd ~/ComfyUI/models/checkpoints && \
   hf download Lightricks/LTX-2.3-fp8 \
     ltx-2.3-22b-dev-fp8.safetensors --local-dir ."

# Distilled LoRA（7.61GB）
tmux new -s dl-lora1 -d \
  "cd ~/ComfyUI/models/loras && \
   hf download Lightricks/LTX-2.3 \
     ltx-2.3-22b-distilled-lora-384.safetensors --local-dir ."

# Gemma LoRA
tmux new -s dl-lora2 -d \
  "cd ~/ComfyUI/models/loras && \
   hf download Comfy-Org/ltx-2 \
     split_files/loras/gemma-3-12b-it-abliterated_lora_rank64_bf16.safetensors \
     --local-dir ."

# Gemma 文本编码器 fp8（13.2GB）
tmux new -s dl-text -d \
  "cd ~/ComfyUI/models/text_encoders && \
   hf download GitMylo/LTX-2-comfy_gemma_fp8_e4m3fn \
     gemma_3_12B_it_fp8_e4m3fn.safetensors --local-dir ."

# 空间超分模型（996MB）
tmux new -s dl-upscale -d \
  "cd ~/ComfyUI/models/latent_upscale_models && \
   hf download Lightricks/LTX-2.3 \
     ltx-2.3-spatial-upscaler-x2-1.1.safetensors --local-dir ."

-d 表示创建后立即放后台，无需手动挂起。命令会在该 session 中独立执行。

监控下载进度

# 查看所有下载 session
tmux ls

# 进入某个 session 看实时进度（看完按 Ctrl+B 再按 D 退出）
tmux attach -t dl-main

# 监控各模型目录大小变化
watch -n 2 'du -sh ~/ComfyUI/models/*/'

# 实时查看网络带宽（可选）
apt install -y nload && nload

⚠️ 注意事项

  • 磁盘空间：合计约 51GB，下载前用 df -h 确认至少有 80GB 可用空间
  • 不要无限并发：5 个左右是甜区，超过 10 个反而互相抢带宽 + 可能触发 HuggingFace 限流
  • 触发限流时（出现 429 错误或速度骤降）：减少并发数，或执行 hf auth login 登录后再下载

验证下载结果

下载完成后，强烈建议用下面这条命令一次性核对所有目录的内容，避免文件下到错误位置导致 ComfyUI 加载不到：

find ~/ComfyUI/models \
  -type d \( \
    -name "checkpoints" -o \
    -name "loras" -o \
    -name "text_encoders" -o \
    -name "latent_upscale_models" -o \
    -name "vae" \
  \) -exec sh -c \
    'echo "=== $1 ==="; ls -lh "$1"; echo' _ {} \;

预期输出（参考）：

目录 应该包含的文件 大小
checkpoints/ ltx-2.3-22b-dev-fp8.safetensors 28G
loras/ ltx-2.3-22b-distilled-lora-384.safetensors 7.1G
loras/ gemma-3-12b-it-abliterated_lora_rank64_bf16.safetensors 600M
text_encoders/ gemma_3_12B_it_fp8_e4m3fn.safetensors（或 fp4_mixed） 13G / 8.8G
latent_upscale_models/ ltx-2.3-spatial-upscaler-x2-1.1.safetensors 950M

常见错误与修复

情况 1：文件被下到子目录里（最常见，多数情况无需处理）

hf download 会保留仓库的原始路径结构，导致出现这种嵌套：

~/ComfyUI/models/loras/split_files/loras/gemma-3-12b-it-abliterated_lora_rank64_bf16.safetensors
~/ComfyUI/models/text_encoders/split_files/text_encoders/gemma_3_12B_it_fp4_mixed.safetensors

较新版 ComfyUI 对模型目录是递归扫描的，子目录里的文件能正常识别，只是在节点下拉框里会显示成带路径前缀的名字（如 split_files/loras/xxx.safetensors）。只要节点能选到、能跑通，就无需移动。

只在以下情况需要把文件移到模型目录根：

  • 节点下拉框里完全看不到该文件（旧版 ComfyUI 不递归扫描）
  • 复用别人的 workflow.json 时报"model not found"，对方的文件名里没有 split_files/ 前缀

需要时执行：

# 移动 LoRA 到正确位置（用通配符，避免长文件名复制时被截断）
mv ~/ComfyUI/models/loras/split_files/loras/*.safetensors ~/ComfyUI/models/loras/

# 移动 text_encoder 到正确位置
mv ~/ComfyUI/models/text_encoders/split_files/text_encoders/*.safetensors ~/ComfyUI/models/text_encoders/

# 清理空的子目录和下载缓存
rm -rf ~/ComfyUI/models/loras/split_files ~/ComfyUI/models/loras/.cache
rm -rf ~/ComfyUI/models/text_encoders/split_files ~/ComfyUI/models/text_encoders/.cache

💡 小提示：处理超长文件名时优先用 *.safetensors 通配符。直接复制带反斜杠续行的完整文件名时，部分终端会在单词中间硬换行导致命令断裂。

情况 2：超分模型放错目录

比如 ltx-2.3-spatial-upscaler-x2-1.1.safetensors 被下到了 loras/：

mkdir -p ~/ComfyUI/models/latent_upscale_models
mv ~/ComfyUI/models/loras/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
   ~/ComfyUI/models/latent_upscale_models/

情况 3：文件大小为 0 或几 KB

下载未完成或网络中断，删除后重新下载即可：

rm 文件路径
# 重新执行对应的 hf download 命令

💡 调整文件位置后，需要在 ComfyUI 网页右上角点 刷新（🔄）按钮，或重启 ComfyUI 进程才能识别新文件。

七、启动 ComfyUI

模型下载完成后，新开一个 tmux session 来运行 ComfyUI（与下载 session 分开，便于管理）。

在 tmux 中启动

# 新建 session（tmux 已在第六节安装过）
tmux new -s comfyui

# 启动 ComfyUI（显存不足时加 --lowvram）
cd ~/ComfyUI
python main.py --listen 0.0.0.0 --port 8188

# 挂到后台：按 Ctrl+B，松开，再按 D

常用 tmux 命令

tmux ls                         # 查看所有 session
tmux attach -t comfyui          # 回到 ComfyUI session
tmux attach -t download         # 回到下载 session 查看进度
tmux kill-session -t comfyui    # 结束 session

八、阿里云安全组放行端口

控制台 → 安全组 → 添加入方向规则：

  • 端口：8188
  • 来源：0.0.0.0/0

浏览器访问：http://你的公网IP:8188

九、显存不足（OOM）解决方法

# 方法 1：低显存模式
python main.py --listen 0.0.0.0 --port 8188 --lowvram

# 方法 2：极限省显存（全卸到内存，速度慢）
python main.py --listen 0.0.0.0 --port 8188 --novram

生成参数建议：

  • 分辨率不超过 768x512
  • 帧数控制在 25 帧以内

注意事项

  • A10 24GB 实测无法运行本教程（fp8 主模型 + Gemma 12B 加载即 OOM），推荐 L20 48GB 或 A100 40GB 以上
  • 多卡部署不能合并显存，ComfyUI 默认只用 GPU 0
  • Gemma fp4_mixed 格式需要支持 fp4 计算的显卡（Ada / 50xx 系列等），不支持的卡请用 fp8 版本
  • Gemma 模型放 text_encoders/ 目录，用 LTXAVTextEncoderLoader 节点加载

十、LTX-2.3 提示词撰写技巧

官方给出三个核心维度，写好这三块能显著提升出片质量：

  1. 核心动作（Core Actions）：按时间顺序描述画面里发生的事件和动作
  2. 视觉细节（Visual Details）：把希望出现在视频里的所有视觉元素都写清楚（人物外观、场景、光线、色调、镜头语言等）
  3. 音频（Audio）：描述场景需要的环境音效和对话台词

LTX-2.3 支持原生音视频联合生成，提示词里写音频描述会直接影响输出。

十一、问题反馈

问题类型 反馈仓库
工作流跑不起来 / 运行报错 ComfyUI/issues
前端 / UI 问题 ComfyUI_frontend/issues
工作流模板问题 workflow_templates/issues
LTX-2.3 模型 / 节点问题 ComfyUI-LTXVideo/issues

提交 issue 前请先把 ComfyUI 升级到最新版本，并确认所需模型已正确放入对应目录。

本文链接地址：https://blog.eimoon.com/p/comfyui-ltx-2.3-deployment-guide/

作者：eimoon.com

分享转载说明：本文由作者原创，转载请注明出处。

© 2023 - 2026 longlikun
使用 Hugo 构建
主题 Stack 由 Jimmy 设计