艾萝工坊

主题

常见问题与故障排查 ​

遇到运行异常或生成报错时，可以按照本指南分类逐步排查并解决问题。绝大多数故障可以通过查看对应服务的实时运行日志定位原因。

控制面板与网络访问问题 ​

控制面板打不开（5000 端口） ​

  1. 检查容器状态：在 Docker 或云平台控制台中确认 ComfyCarry 容器处于运行（Running）状态。
  2. 检查端口映射：确认访问的 URL 与外部映射端口（如 http://<IP>:5000）完全匹配。
  3. 检查后台服务：通过 SSH 或终端运行 pm2 status，检查 dashboard 服务是否在线。
  4. 查看面板日志与重启：
    bash
    pm2 logs dashboard --lines 100
pm2 restart dashboard

Cloudflare Tunnel 无法访问或频繁断开 ​

  • 公共节点连接异常：公共节点由共享服务器分配临时子域名，如果出现网络重连，请在 Cloudflare Tunnel 页面重新复制最新的公网访问链接。
  • 自定义 Tunnel 权限错误：检查 Cloudflare API Token 权限是否包含 Account: Cloudflare Tunnel (Edit) 和 Zone: DNS (Edit)。权限不足会导致 DNS 解析记录创建失败。
  • 传输协议被运营商阻断：在 Tunnel → 配置 中将 传输协议 从 Auto 切换为 HTTP/2，点击保存并重启 Tunnel 服务，可解决 UDP/QUIC 流量被本地网络或防火墙阻断的问题。

JupyterLab 无法进入或登录失效 ​

  1. 在 JupyterLab 页面中确认服务状态为运行中。
  2. 复制卡片中的 访问令牌（Access Token），在打开的 JupyterLab 登录页中手动粘贴完成认证。
  3. 若服务异常，在终端运行 pm2 restart jupyter 重启服务并查看输出日志：
    bash
    pm2 logs jupyter --lines 100

SSH 远程连接被拒绝 ​

  • 通过 Cloudflare Tunnel 连接时报错：必须在本地电脑安装 cloudflared 客户端，并使用带有 -o ProxyCommand="cloudflared access ssh --hostname %h" 的完整连接命令。
  • 端口映射直连失败：确认连接命令中的端口为外部映射端口（例如 -p 2222），而非容器内部的默认 22 端口。
  • 密码或公钥认证失败：检查本地公钥是否已成功添加到 SSH → 密钥与密码 列表中；如果使用密码登录，请重新设置或同步 Root 密码以使 sshd 重新加载配置。

模型管理与加载问题 ​

模型已下载但在列表中找不到 ​

  1. 检查存放目录：确认模型文件存放在正确的子分类目录中（例如基础大模型放入 models/checkpoints/，LoRA 放入 models/loras/，VAE 放入 models/vae/，CLIP 放入 models/clip/）。
  2. 刷新模型索引：在内容生成工作台中点击模型选择框右侧的 刷新 按钮，触发后台扫描重新加载。
  3. 分体模型组件不完整：分体模型（如 Z-Image、Wan 2.2、MiniMax H3）需要同时存在主扩散模型、文本编码器与 VAE。若缺少任一配套组件，列表将无法完成自动配对。

Hugging Face 或 CivitAI 下载失败 ​

  • CivitAI 权限限制模型：部分社区模型需要登录账户才允许下载。前往 设置 → CivitAI 填入有效的 API Key 并保存。
  • Hugging Face 授权模型：部分模型（如部分 FLUX 变体）需要先在 Hugging Face 网页端签署用户协议，并在下载请求中附带具有读取权限的 User Access Token。
  • 磁盘空间不足：在终端中运行 df -h 检查 /workspace 所在分区的剩余磁盘空间。空间占满时需清理历史生成产物或不再使用的模型。

内容生成与任务报错 ​

生成任务提示 Model not found 或 Node not found ​

  • Model not found：对应模型文件已被移动、重命名或下载不完整。请在模型管理页确认文件完整性。
  • Node not found / Unknown node type：当前工作流依赖的第三方自定义节点尚未安装。打开 ComfyUI-Manager 安装对应插件，随后运行 pm2 restart comfy 重新加载节点。

画面色彩烧焦、过度饱和或全黑全灰 ​

  • 误调高了蒸馏/DiT 模型的 CFG：在 Z-Image、Krea 2、FLUX.1、FLUX.2 等模型中，必须保持 CFG = 1.0。调高 CFG 会破坏流匹配计算，导致画面严重过曝烧焦。
  • VAE 选用错误：如果生成的图片整体蒙灰或色彩断阶，说明选用了与主模型不匹配的 VAE。请切换为官方推荐的对应 VAE。
  • Clip Skip 错误：使用 Pony、Illustrious、NoobAI 等动漫模型时，请确认高级设置中的 Clip Skip 设置为 2。

视频生成长时间无响应或无法播放 ​

  • 编码等待：视频模型生成全部帧后需要进行 VAE 空间解算与 MP4 视频压制，此阶段 GPU 显存会短暂升高，属于正常现象，等待任务状态更新为完成即可。
  • 浏览器播放兼容性：若个别浏览器无法在线播放特定编码的视频文件，可以右键下载到本地电脑，使用 VLC 或系统播放器打开。

显存不足（CUDA Out of Memory）排查 ​

当任务报错提示 torch.cuda.OutOfMemoryError 或在采样阶段突然中断时，可按以下顺序降低显存占用：

  1. 单次生成数量设为 1：将 Batch Size 降为 1。
  2. 选择量化版模型：运行 14B 以上的视频大模型或 FLUX 系列时，优先选用 FP8、GGUF 或 NVFP4 量化版本的主模型与文本编码器（如 umt5_xxl_fp8、qwen3vl_32b_nvfp4）。
  3. 降低分辨率与视频时长：
    • 图像生成可先在 1024×1024 标准尺寸下生成，再通过高清放大放大分辨率。
    • 视频生成可先采用 480p 档位和 4–5 秒时长验证动作，确认效果后再渲染高分辨率成片。
  4. 暂时关闭重度辅助模块：关闭叠加的高清修复、面部修复或多个 ControlNet 控制单元。
  5. 释放模型显存缓存：在 ComfyUI 管理页面点击 释放显存，或在终端运行 pm2 restart comfy 彻底清空 GPU 显存占用。

外部服务与云同步排查 ​

LLM AI 提示词测试连接失败 ​

  • 基础 URL 格式错误：自定义服务商的 基础 URL 通常需要包含完整版本路径（例如 https://api.example.com/v1），请检查末尾是否遗漏了 /v1。
  • 模型名称填写有误：点击输入框右侧的刷新按钮自动获取可用模型列表，或核对服务商官方文档中的 Model ID。

云存储同步未传输文件 ​

  1. 在 云存储连接 中点击 测试连接，确认网盘授权凭证未过期。
  2. 检查规则中的 本地路径（如 /ComfyUI/output）与 远端路径 是否准确无误。
  3. 检查规则的高级过滤条件（如包含规则、排除规则、大小限制）是否过滤了目标文件。
  4. 手动点击一次 立即同步，并展开实时日志查看具体的文件比对与传输报错。