ComfyUI 초보자를 위한 설치 가이드 : 초보자도 10분이면 이미지 생성 가능

@echo off
cd /d "%~dp0"

.\python_embeded\python.exe -s ComfyUI\main.py ^
  --windows-standalone-build ^
  --listen 0.0.0.0 ^
  --port 8188 ^
  --cuda-malloc ^
  --fast ^
  --preview-method latent2rgb ^
  --highvram

rem 각 옵션 설명:
rem --listen 0.0.0.0   : 같은 와이파이의 다른 기기(폰 등)에서 접속 허용
rem --cuda-malloc      : CUDA 전용 할당자 사용 (VRAM 단편화 감소, 속도 향상)
rem --fast             : 불필요한 안전 검사 제거 (속도 향상)
rem --preview-method latent2rgb : 빠른 프리뷰 (기본 auto보다 VAE 없이 빠름)
rem --highvram         : 모델을 VRAM에 최대한 유지 (12GB+ 권장)
rem                      8GB 이하라면 --normalvram 또는 --lowvram 사용

pause

# NVIDIA Container Toolkit 공식 저장소 추가
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
    | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
    | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 설치
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

# Docker 런타임에 NVIDIA 등록
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# GPU Docker 작동 확인 — nvidia-smi 출력되면 성공!
docker run --rm --gpus all ubuntu:24.04 nvidia-smi

# ── 경로 변수 정의 ──────────────────────────────────────
# 본인 환경에 맞게 수정하세요
MAIN_DIR="/opt/comfyui"          # 설정·노드·캐시 (소용량)
DATA_DIR="/mnt/storage/comfyui"  # 모델·출력·입력 (대용량)

# ── MAIN_DIR 생성 ────────────────────────────────────────
sudo mkdir -p \
  ${MAIN_DIR}/custom_nodes \
  ${MAIN_DIR}/user/default/workflows \
  ${MAIN_DIR}/dot-local \
  ${MAIN_DIR}/dot-cache \
  ${MAIN_DIR}/dot-config

# ── DATA_DIR 생성 ────────────────────────────────────────
sudo mkdir -p \
  ${DATA_DIR}/models/checkpoints \
  ${DATA_DIR}/models/loras \
  ${DATA_DIR}/models/vae \
  ${DATA_DIR}/models/controlnet \
  ${DATA_DIR}/models/upscale_models \
  ${DATA_DIR}/models/clip \
  ${DATA_DIR}/models/diffusion_models \
  ${DATA_DIR}/models/unet \
  ${DATA_DIR}/models/text_encoders \
  ${DATA_DIR}/models/embeddings \
  ${DATA_DIR}/models/ipadapter \
  ${DATA_DIR}/models/video_models \
  ${DATA_DIR}/output \
  ${DATA_DIR}/input \
  ${DATA_DIR}/temp

# ── 소유권 & 권한 설정 ───────────────────────────────────
# yanwk cu128-slim은 컨테이너 내부에서 root(uid=0)로 실행
# → 호스트 소유자를 현재 사용자로, 권한 755로 설정
sudo chown -R $(whoami):$(whoami) ${MAIN_DIR} ${DATA_DIR}
sudo chmod -R 755 ${MAIN_DIR} ${DATA_DIR}

# 컨테이너가 직접 파일을 쓰는 디렉토리는 775
sudo chmod 775 \
  ${DATA_DIR}/output \
  ${DATA_DIR}/input \
  ${DATA_DIR}/temp \
  ${MAIN_DIR}/custom_nodes \
  ${MAIN_DIR}/dot-local \
  ${MAIN_DIR}/dot-cache

# ── 확인 ─────────────────────────────────────────────────
ls -la ${MAIN_DIR}
ls -la ${DATA_DIR}/models

# ── 경로 설정 (본인 환경에 맞게 수정) ─────────────────────
MAIN_DIR=/opt/comfyui
DATA_DIR=/mnt/storage/comfyui

# ── 포트 ──────────────────────────────────────────────────
COMFYUI_PORT=8188

# ── ComfyUI 실행 플래그 (핵심!) ──────────────────────────
# 이 한 줄로 ComfyUI의 성능과 동작 방식이 결정됩니다
CLI_ARGS=--listen 0.0.0.0 --port 8188 --cuda-malloc --fast --preview-method latent2rgb --highvram --cache-none

# 각 플래그 설명:
# --listen 0.0.0.0     : 외부(다른 PC, 폰)에서 접속 허용
# --port 8188          : 접속 포트 번호
# --cuda-malloc        : CUDA 전용 메모리 할당자 (단편화 30% 감소, 속도 향상)
# --fast               : 내부 안전 검사 일부 비활성화 (속도 5~15% 향상)
# --preview-method latent2rgb : VAE 디코딩 없이 빠른 프리뷰 표시
#                        생성 중 미리보기 속도가 2~3배 빠름
# --highvram           : 모델을 VRAM에 최대한 유지 (12GB+ GPU 권장)
#                        VRAM 12GB → FLUX fp8 사용 시 최적
#                        VRAM 8GB 이하 → --normalvram 으로 변경
#                        FLUX bf16(24GB 모델) 사용 시 → --normalvram
#                        (초과분을 시스템 RAM으로 자동 오프로딩)
# --cache-none         : 워크플로우 간 모델 캐시 비활성화
#                        → VRAM 안정적 확보, OOM 방지

# ── PyTorch CUDA 메모리 최적화 ────────────────────────────
# garbage_collection_threshold:0.9 → VRAM 90% 도달 시 GC 실행
# max_split_size_mb:512            → 큰 블록 분할 기준 (단편화 방지)
PYTORCH_CUDA_ALLOC_CONF=garbage_collection_threshold:0.9,max_split_size_mb:512

# ── GPU 설정 ──────────────────────────────────────────────
NVIDIA_VISIBLE_DEVICES=0              # GPU 1개 서버: 0 / 멀티 GPU: all
NVIDIA_DRIVER_CAPABILITIES=compute,utility,video

# yanwk 이미지 내부 경로 안전 설정 (필수, 수정 불필요)
GIT_CONFIG_GLOBAL_SAFE_DIRECTORY=/root/ComfyUI

# ── 기타 ──────────────────────────────────────────────────
TZ=Asia/Seoul
PYTHONUNBUFFERED=1

services:
  comfyui:
    image: yanwk/comfyui-boot:cu128-slim
    # cu128-slim 선택 이유:
    # ✓ CUDA 12.8 — RTX 3060 Ampere 완벽 지원
    # ✓ Python 3.12 — 커스텀 노드 호환성 최고
    # ✓ xFormers 기본 포함 — cu130-slim은 미포함!
    # ✓ 매일 빌드, 500K+ pulls 검증

    container_name: comfyui
    runtime: nvidia
    restart: unless-stopped
    # unless-stopped: 수동 stop 후 서버 재부팅 시 자동 시작 안 함
    # always 대신 unless-stopped 권장 (의도치 않은 재시작 방지)

    env_file: .env
    environment:
      - NVIDIA_VISIBLE_DEVICES=${NVIDIA_VISIBLE_DEVICES:-0}
      - NVIDIA_DRIVER_CAPABILITIES=${NVIDIA_DRIVER_CAPABILITIES}
      - CLI_ARGS=${CLI_ARGS}
      - PYTORCH_CUDA_ALLOC_CONF=${PYTORCH_CUDA_ALLOC_CONF}
      - GIT_CONFIG_GLOBAL_SAFE_DIRECTORY=${GIT_CONFIG_GLOBAL_SAFE_DIRECTORY}
      - TZ=${TZ:-Asia/Seoul}
      - PYTHONUNBUFFERED=1

    volumes:
      # ── 모델 (대용량 → 빠른 스토리지 경로) ─────────────────
      # models 하위 폴더 전체 포함 (checkpoints, loras, vae 등)
      - ${DATA_DIR}/models:/root/ComfyUI/models

      # ── 생성 결과물 ─────────────────────────────────────────
      - ${DATA_DIR}/output:/root/ComfyUI/output

      # ── 입력 이미지 (img2img, ControlNet 등) ─────────────────
      - ${DATA_DIR}/input:/root/ComfyUI/input

      # ── 임시 파일 ───────────────────────────────────────────
      - ${DATA_DIR}/temp:/root/ComfyUI/temp

      # ── 커스텀 노드 (Manager 포함) ──────────────────────────
      - ${MAIN_DIR}/custom_nodes:/root/ComfyUI/custom_nodes

      # ── 워크플로우 & 사용자 설정 ─────────────────────────────
      - ${MAIN_DIR}/user:/root/ComfyUI/user

      # ── pip 패키지 보존 (★ 핵심!) ────────────────────────────
      # 이 마운트가 없으면 컨테이너 재시작마다
      # Manager로 설치한 패키지가 전부 사라집니다
      - ${MAIN_DIR}/dot-local:/root/.local

      # ── HuggingFace 캐시 (중복 다운로드 방지) ────────────────
      - ${MAIN_DIR}/dot-cache:/root/.cache

      # ── Manager 등 설정 파일 ─────────────────────────────────
      - ${MAIN_DIR}/dot-config:/root/.config

    ports:
      - "${COMFYUI_PORT:-8188}:8188"

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ['0']    # GPU 1개: ['0'] / 전체: all
              capabilities: [gpu]
        limits:
          cpus: '8.0'
          memory: 32g              # 시스템 RAM에 따라 조정
                                   # FLUX bf16 RAM 오프로딩 사용 시 64g 권장

    shm_size: '8g'                 # 공유 메모리 (영상 생성 시 16g 권장)

    ulimits:
      memlock:
        soft: -1
        hard: -1                   # 메모리 잠금 해제 (GPU 전송 최적화)
      nofile:
        soft: 65536
        hard: 65536

    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8188/system_stats > /dev/null || exit 1"]
      interval: 30s
      timeout: 15s
      retries: 5
      start_period: 120s           # 첫 실행 시 Manager 설치 시간 고려

    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "5"

# 시작 (백그라운드)
docker compose up -d

# 실시간 로그 확인 (Ctrl+C로 종료)
docker compose logs -f comfyui

# 상태 확인
docker compose ps

# 재시작
docker compose restart comfyui

# 중지
docker compose down

# GPU 사용 현황 확인
docker exec comfyui nvidia-smi

# 이미지 최신으로 업데이트
docker compose pull && docker compose up -d

models/
├── checkpoints/        ← SD 1.5, SDXL 통합 체크포인트 (.safetensors, .ckpt)
│                          예: dreamshaper_8.safetensors
│
├── diffusion_models/   ← FLUX.1, SD3.5 등 최신 분리형 모델의 UNet
│                          예: flux1-dev-fp8.safetensors
│
├── vae/               ← VAE 파일 (이미지 품질, 색감에 영향)
│                          예: ae.safetensors (FLUX용)
│
├── clip/              ← 텍스트 인코더 (FLUX는 2개 필요)
│                          예: clip_l.safetensors, t5xxl_fp8.safetensors
│
├── text_encoders/     ← SD3.5 등의 텍스트 인코더
│
├── loras/             ← LoRA 파일 (스타일, 캐릭터 추가)
│                          예: add_detail.safetensors
│
├── controlnet/        ← ControlNet 모델 (포즈, 엣지, 깊이 제어)
│
├── upscale_models/    ← ESRGAN 등 업스케일 모델
│                          예: RealESRGAN_x4plus.pth
│
├── ipadapter/         ← IP-Adapter (얼굴/스타일 참조)
│
├── unet/              ← 일부 모델의 UNet (GGUF 양자화 포함)
│
└── video_models/      ← Wan 2.2, HunyuanVideo 등 영상 생성 모델

DATA_DIR="/mnt/storage/comfyui"  # 본인 경로로 수정

# FLUX.1 Dev fp8 (12GB VRAM — 권장 시작 모델)
wget -P ${DATA_DIR}/models/diffusion_models/ \
  "https://huggingface.co/black-forest-labs/FLUX.1-dev/resolve/main/flux1-dev-fp8.safetensors"

# FLUX용 VAE
wget -P ${DATA_DIR}/models/vae/ \
  "https://huggingface.co/black-forest-labs/FLUX.1-dev/resolve/main/ae.safetensors"

# FLUX용 텍스트 인코더 (2개 모두 필요)
wget -P ${DATA_DIR}/models/clip/ \
  "https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/clip_l.safetensors"

wget -P ${DATA_DIR}/models/clip/ \
  "https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/t5xxl_fp8_e4m3fn.safetensors"

# 4배 업스케일 모델
wget -P ${DATA_DIR}/models/upscale_models/ \
  "https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth"

# 방법 A: 호스트에서 직접 (Docker 볼륨 마운트된 경로에)
cd /mnt/data/01_ai/comfyui/custom_nodes/
git clone https://github.com/Comfy-Org/ComfyUI-Manager.git
docker compose restart comfyui

# 방법 B: 컨테이너 내부에서
docker exec -it comfyui bash
cd /root/ComfyUI/custom_nodes/
git clone https://github.com/Comfy-Org/ComfyUI-Manager.git
exit
docker compose restart comfyui

FLUX.1 txt2img 노드 연결 순서:

[Load Diffusion Model]             [DualCLIPLoader]
  flux1-dev-fp8.safetensors          clip_l.safetensors
  ↓ MODEL                            t5xxl_fp8.safetensors
[ModelSamplingFlux]                  ↓ CLIP
  ↓ MODEL                          [CLIPTextEncode]
[FluxGuidance]                       프롬프트 입력
  guidance: 3.5                      ↓ CONDITIONING
  ↓ MODEL + CONDITIONING
[EmptySD3LatentImage]     →     [KSampler Advanced]
  width: 1024                         steps: 20~30
  height: 1024                        cfg: 1.0  ← FLUX는 낮게!
  batch: 1                            sampler: euler
                                      scheduler: simple
                                      denoise: 1.0
                                      ↓ LATENT
                               [VAEDecode]
                                 vae: ae.safetensors
                                 ↓ IMAGE
                               [Save Image]

⚠️ FLUX 핵심 설정값:
  CFG: 1.0 (SDXL의 7.0과 전혀 다름! 높이면 이상한 이미지 나옴)
  Negative 프롬프트: 불필요 (FLUX는 guidance로 제어)

# yanwk cu128-slim에는 xFormers가 기본 포함됩니다
# 설치 여부 확인
docker exec comfyui python3 -c "import xformers; print(xformers.__version__)"

# 만약 없다면 (cu130-slim 사용 시 해당)
docker exec comfyui pip install xformers \
  --extra-index-url https://download.pytorch.org/whl/cu128

# GPU 상태 및 VRAM 사용량 확인
nvidia-smi

# Docker 컨테이너 로그 확인 (오류 메시지 전체 보기)
docker compose logs --tail=100 comfyui

# 컨테이너 내부 Python 환경 확인
docker exec comfyui python3 -c "
import torch
print('CUDA:', torch.cuda.is_available())
print('GPU:', torch.cuda.get_device_name(0))
print('VRAM:', round(torch.cuda.get_device_properties(0).total_memory/1e9,1), 'GB')
print('PyTorch:', torch.__version__)
"

# xFormers 설치 확인
docker exec comfyui python3 -c "import xformers; print('xFormers OK:', xformers.__version__)"

# 모델 파일 목록 확인
docker exec comfyui ls /root/ComfyUI/models/diffusion_models/
docker exec comfyui ls /root/ComfyUI/models/checkpoints/