macos-tools/stable-diffusion

ComfyUI 部署方案 - Apple M2 Ultra 优化版

专为 Apple M2 Ultra 芯片优化的 AI 图像/视频生成生产级部署方案

支持 SDXL 图像生成 + LTX-2 视频生成

📋 目录

• 方案概述
• 快速开始
• 详细安装
• 服务管理
• K8s 集成
• 性能优化
• 常见问题

---

方案概述

为什么选择 ComfyUI？

✅ 工程化最佳 - 适合产品化、接口化、可控工作流 ✅ 功能完整 - SDXL 图像生成、LTX-2 视频生成、ControlNet、IP-Adapter、LoRA 全支持 ✅ API 友好 - 可被后端服务（FastAPI/Spring）调用 ✅ 稳定可靠 - 在 Apple MPS 下表现优异

架构设计

┌─────────────────────────────────────────────────────────┐
│                    K8s 业务服务                          │
│  (FastAPI / Spring Boot / Dify / 其他应用)              │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP API
                     ↓
┌───────────────���─────────────────────────────────────────┐
│              http://host.docker.internal:8188            │
│                   ComfyUI 服务 (macOS)                   │
│              PyTorch MPS 加速 (原生性能)                 │
└─────────────────────────────────────────────────────────┘

设计理念：

• macOS 宿主机运行 ComfyUI（充分利用 MPS 加速）
• K8s Pod 通过 HTTP 调用（与 Ollama 相同模式）
• 避免容器化带来的 MPS 兼容性问题

---

快速开始

前置要求

• 硬件: Apple M2 Ultra (或 M1/M2/M3 系列)
• 系统: macOS 13+ (Ventura/Sonoma/Sequoia)
• 内存: 建议 64GB+ (SDXL 需要较大内存，LTX-2 视频生成需要更多)
• 存储: 至少 100GB 可用空间（SDXL ~10GB + LTX-2 ~56GB + 其他模型）

一键安装

cd /Users/brunogao/work/codes/tools/macos/stable-diffusion

# 1. 执行安装脚本
chmod +x install_comfyui_m2ultra.sh
./install_comfyui_m2ultra.sh

# 2. 下载模型（示例：SDXL Base）
cd ~/ComfyUI/models/checkpoints
# 从 HuggingFace 或其他源下载模型
# 例如: wget https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors

# 3. 启动服务
~/ComfyUI/run_comfyui.sh

# 4. 访问 Web UI
open http://127.0.0.1:8188

---

详细安装

1. 安装脚本说明

install_comfyui_m2ultra.sh 会自动完成：

• ✅ 检查系统环境（macOS、Apple Silicon）
• ✅ 安装 Miniforge（如果未安装 Conda）
• ✅ 创建 Python 3.11 虚拟环境
• ✅ 安装 PyTorch (MPS 支持)
• ✅ 克隆 ComfyUI 仓库
• ✅ 安装所有依赖
• ✅ 创建模型目录结构
• ✅ 生成启动脚本

2. 模型目录结构

~/ComfyUI/models/
├── checkpoints/          # 主模型 (SD1.5/SDXL)
│   ├── sd_xl_base_1.0.safetensors
│   └── sd_xl_refiner_1.0.safetensors
├── loras/                # LoRA 模型
├── vae/                  # VAE 模型
├── controlnet/           # ControlNet 模型
├── clip_vision/          # CLIP 视觉模型
├── upscale_models/       # 放大模型 (ESRGAN 等)
└── embeddings/           # Embedding 模型

3. 推荐模型下载

SDXL 基础套件:

cd ~/ComfyUI/models/checkpoints

# Base 模型 (必需)
wget https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors

# Refiner 模型 (可选，用于细化)
wget https://huggingface.co/stabilityai/stable-diffusion-xl-refiner-1.0/resolve/main/sd_xl_refiner_1.0.safetensors

放大模型:

cd ~/ComfyUI/models/upscale_models

# 4x-UltraSharp (推荐)
wget https://huggingface.co/Kim2091/UltraSharp/resolve/main/4x-UltraSharp.pth

4. LTX-2 视频生成模型（可选）

LTX-2 是 Lightricks 开发的 19B 参数视频生成模型，支持文本到视频、图像到视频生成。

一键下载所有 LTX-2 模型 (~56GB):

cd /Users/brunogao/work/codes/tools/macos/stable-diffusion

# 方式1: 使用国内镜像（推荐）
USE_MIRROR=true ./download-ltx2-models.sh

# 方式2: 使用 HuggingFace（需要代理）
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
./download-ltx2-models.sh

包含的模型:

• ltx-2-19b-dev-fp8.safetensors (25GB) - 主模型
• gemma_3_12B_it.safetensors (23GB) - 文本编码器
• ltx-2-spatial-upscaler-x2-1.0.safetensors (950MB) - 空间放大器
• ltx-2-19b-distilled-lora-384.safetensors (7.1GB) - 蒸馏 LoRA
• ltx-2-19b-lora-camera-control-dolly-left.safetensors (312MB) - 相机控制 LoRA

所需依赖（自动安装）:

source ~/miniforge3/bin/activate comfy
pip install pydantic pydantic-settings spandrel kornia

验证安装:

./verify-ltx2.sh

使用指南: 详见 LTX2-USAGE.md

---

服务管理

手动启动

# 启动服务
~/ComfyUI/run_comfyui.sh

# 访问 Web UI
open http://127.0.0.1:8188

配置开机自启 (LaunchD)

cd /Users/brunogao/work/codes/tools/macos/stable-diffusion

# 安装 LaunchAgent
chmod +x setup_launchd.sh
./setup_launchd.sh install

# 卸载服务
./setup_launchd.sh uninstall

服务管理命令:

# 启动服务
launchctl load ~/Library/LaunchAgents/com.comfyui.service.plist

# 停止服务
launchctl unload ~/Library/LaunchAgents/com.comfyui.service.plist

# 查看状态
launchctl list | grep comfyui

# 查看日志
tail -f ~/Library/Logs/ComfyUI/comfyui.log
tail -f ~/Library/Logs/ComfyUI/comfyui.error.log

健康检查

cd /Users/brunogao/work/codes/tools/macos/stable-diffusion

chmod +x healthcheck.sh
./healthcheck.sh

检查内容:

• ✅ 系统信息（CPU、内存、架构）
• ✅ Conda 环境状态
• ✅ PyTorch 和 MPS 支持
• ✅ ComfyUI 安装状态
• ✅ 模型目录和文件数量
• ✅ 服务运行状态
• ✅ 网络访问测试
• ✅ 日志文件检查

---

K8s 集成

架构说明

K8s Pod 通过 host.docker.internal 访问宿主机上的 ComfyUI 服务（与 Ollama 相同模式）。

部署配置

cd /Users/brunogao/work/codes/tools/macos/stable-diffusion

# 应用 K8s 配置
kubectl apply -f k8s-integration.yaml

配置内容

1. ConfigMap - 环境变量配置

   • COMFYUI_HOST: host.docker.internal
   • COMFYUI_PORT: 8188
   • COMFYUI_URL: http://host.docker.internal:8188

2. ExternalName Service - 服务发现

   • 将 comfyui-external 映射到宿主机

3. Python 客户端示例 - 完整的调用示例

   • 健康检查
   • 提交工作流
   • 获取生成结果

4. FastAPI Gateway 示例 - API 网关

   • RESTful API 封装
   • 请求参数验证
   • 错误处理

使用示例

Python 客户端:

import requests

COMFYUI_URL = "http://host.docker.internal:8188"

# 健康检查
response = requests.get(f"{COMFYUI_URL}/system_stats")
print(response.json())

# 提交工作流
workflow = {...}  # 你的 ComfyUI workflow JSON
response = requests.post(
    f"{COMFYUI_URL}/prompt",
    json={"prompt": workflow}
)
result = response.json()
prompt_id = result["prompt_id"]

从 K8s Pod 访问:

# 进入 Pod
kubectl exec -it <pod-name> -- bash

# 测试连接
curl http://host.docker.internal:8188/system_stats

---

性能优化

M2 Ultra 最佳实践

1. 采样器和步数选择

场景	采样器	步数	分辨率
快速预览	DPM++ 2M	15-20	1024x1024
标准质量	DPM++ 2M Karras	20-30	1024x1024
高质量	DPM++ SDE Karras	30-40	1024x1024

2. 二段式工作流（推荐）

第一步: SDXL Base (1024x1024, 20 steps)
   ↓
第二步: Upscale (4x-UltraSharp → 2048x2048)
   ↓
第三步: Refiner (可选，细化细节)

优势:

• 速���快 3-5 倍
• 内存占用更低
• 质量不降反升

3. 并发控制

M2 Ultra 建议配置:

• 同时任务数: 1-2 个
• 队列管理: 使用 Redis/DB 排队
• 超时设置: 300 秒（5 分钟）

4. 内存优化

# ComfyUI 启动参数（如需要）
python main.py \
    --listen 0.0.0.0 \
    --port 8188 \
    --lowvram  # 如果内存不足

性能基准参考

M2 Ultra (64GB 内存):

• SDXL 1024x1024, 20 steps: ~30-45 秒
• SDXL 1024x1024, 30 steps: ~45-60 秒
• Upscale 2x: ~10-15 秒
• Refiner 10 steps: ~15-20 秒

---

常见问题

1. MPS 不可用

症状: torch.backends.mps.is_available() 返回 False

解决:

# 重新安装 PyTorch
conda activate comfy
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio

# 验证
python -c "import torch; print(torch.backends.mps.is_available())"

2. 端口被占用

症状: Address already in use: 8188

解决:

# 查找占用进程
lsof -i :8188

# 杀死进程
kill -9 <PID>

# 或更换端口
python main.py --listen 0.0.0.0 --port 8189

3. 模型加载失败

症状: Model not found 或 Failed to load checkpoint

解决:

# 检查模型路径
ls -lh ~/ComfyUI/models/checkpoints/

# 确保文件完整
# SDXL Base 应该约 6.9GB
# 如果文件损坏，重新下载

4. K8s Pod 无法访问

症状: Connection refused 或 Timeout

解决:

# 1. 检查 macOS 防火墙
# 系统设置 → 网络 → 防火墙 → 允许 Python

# 2. 检查服务是否运行
lsof -i :8188

# 3. 从 Pod 内测试
kubectl exec -it <pod> -- curl http://host.docker.internal:8188/system_stats

# 4. 检查 OrbStack 网络（如果使用 OrbStack）
# OrbStack 默认支持 host.docker.internal

5. 生成速度慢

优化建议:

1. 降低步数（20-25 steps 通常足够）
2. 使用二段式工作流
3. 避免过高分辨率（先 1024 再 upscale）
4. 检查是否有其他高负载进程
5. 确保 MPS 已启用

6. 内存不足

症状: Out of memory 或系统卡顿

解决:

# 启用低显存模式
python main.py --listen 0.0.0.0 --port 8188 --lowvram

# 或使用更激进的优化
python main.py --listen 0.0.0.0 --port 8188 --novram

---

高级配置

自定义工作流

ComfyUI 使用 JSON 格式的工作流。你可以：

1. 在 Web UI 中设计工作流
2. 导出为 JSON（右键 → Save (API Format)）
3. 在代码中使用该 JSON

示例工作流位置:

~/ComfyUI/workflows/
├── text2img_basic.json
├── text2img_with_refiner.json
└── img2img_upscale.json

集成到现有系统

FastAPI 示例:

from fastapi import FastAPI
import requests

app = FastAPI()

@app.post("/generate")
async def generate(prompt: str):
    workflow = {...}  # 你的工作流
    response = requests.post(
        "http://host.docker.internal:8188/prompt",
        json={"prompt": workflow}
    )
    return response.json()

Spring Boot 示例:

@RestController
public class ComfyUIController {
    private final RestTemplate restTemplate = new RestTemplate();
    private final String COMFYUI_URL = "http://host.docker.internal:8188";

    @PostMapping("/generate")
    public ResponseEntity<?> generate(@RequestBody Workflow workflow) {
        return restTemplate.postForEntity(
            COMFYUI_URL + "/prompt",
            Map.of("prompt", workflow),
            Map.class
        );
    }
}

---

监控和维护

日志管理

# 实时查看日志
tail -f ~/Library/Logs/ComfyUI/comfyui.log

# 查看错误日志
tail -f ~/Library/Logs/ComfyUI/comfyui.error.log

# 日志轮转（可选）
# 添加到 crontab
0 0 * * * find ~/Library/Logs/ComfyUI -name "*.log" -mtime +7 -delete

性能监控

# 查看进程资源占用
ps aux | grep comfyui

# 查看端口状态
lsof -i :8188

# 系统资源监控
top -pid $(pgrep -f comfyui)

定期维护

# 更新 ComfyUI
cd ~/ComfyUI
git pull
pip install -r requirements.txt --upgrade

# 清理临时文件
rm -rf ~/ComfyUI/temp/*
rm -rf ~/ComfyUI/output/*  # 注意：会删除生成的图片

# 检查磁盘空间
du -sh ~/ComfyUI/models/*

---

安全建议

生产环境部署

1. 网络隔离

   • 仅允许内网访问
   • 使用防火墙限制端口

2. 认证授权

   • 在 API Gateway 层添加认证
   • 使用 JWT 或 API Key

3. 资源限制

   • 限制并发请求数
   • 设置请求超时
   • 实施速率限制

4. 监控告警

   • 监控服务可用性
   • 监控资源使用
   • 设置异常告警

---

参考资源

• ComfyUI 官方: https://github.com/comfyanonymous/ComfyUI
• SDXL 模型: https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0
• PyTorch MPS: https://pytorch.org/docs/stable/notes/mps.html
• 本项目: /Users/brunogao/work/codes/tools/macos/stable-diffusion

---

支持和反馈

如有问题或建议，请：

1. 运行 ./healthcheck.sh 收集诊断信息
2. 查看日志文件
3. 参考常见问题章节

---

版本: 1.0.0 更新日期: 2026-01-06 适用系统: macOS 13+ (Apple Silicon) 测试环境: MacBook Pro M3 Pro, macOS 15.0 Sequoia