n8n-workflows AI Stack：基于 Docker Compose 一键部署 n8n + Agent Zero + ComfyUI 本地自动化栈

本文以 n8n-workflows 仓库中 ai-stack/SUMMARY.md 总览文档为核心，结合 ai-stack/docker-compose.yml、ai-stack/start.sh、ai-stack/start.ps1 及预置工作流 JSON 的源码实现，完整讲解这套"开箱即用"本地 AI 自动化栈的组成结构、三个服务（n8n / Agent Zero / ComfyUI）的端口与访问方式、启动停止操作、四日学习路径、典型使用场景、系统配置要求、安全边界以及常见故障排查方法。读完后你将能够独立在本地部署整条"编排 + 智能体 + 图像生成"流水线，并复现其中的 ComfyUI 连通性测试与图像生成 Webhook 工作流。

一、AI 自动化栈的组成：三个容器，一条流水线

SUMMARY.md 开篇给出了一张栈的概览图：整个 AI AUTOMATION STACK 由三个服务组成，各自监听固定端口——

服务	端口	定位	本机访问地址
n8n	5678	工作流编排引擎（The Conductor）	http://localhost:5678
Agent Zero	50080	AI 智能体运行时与规划 UI	http://localhost:50080
ComfyUI	8188	AI 图像/视频生成	http://localhost:8188

从 ai-stack/docker-compose.yml 源码可以看到，三个服务分别使用以下镜像：

• n8n：n8nio/n8n:latest，容器名 ai-stack-n8n；
• Agent Zero：frdel/agent-zero-run:latest，容器名 ai-stack-agent-zero，Web UI 映射在容器 80 端口，对外暴露 50080；
• ComfyUI：aidockorg/comfyui-cuda:latest，容器名 ai-stack-comfyui，默认通过 CLI_ARGS=--listen 0.0.0.0 --port 8188 启动，并在 deploy.resources.reservations.devices 中声明了 NVIDIA GPU 预留（driver: nvidia, count: all, capabilities: [gpu]）。

三者都接入同一个 bridge 网络 ai-stack-network，这意味着容器之间可以用服务名互访（例如 n8n 请求 http://comfyui:8188），这是后文工作流里 HTTP 节点能直连 ComfyUI 的关键前提。README 中描述的典型工作流闭环是：

1. Trigger：n8n 收到 webhook / 定时 / 事件触发；
2. Plan（可选）：n8n 调用 Agent Zero 做决策与规划；
3. Generate：n8n 向 ComfyUI 的 POST /prompt 提交工作流；
4. Poll：n8n 轮询 GET /history/{prompt_id} 直到完成；
5. Deliver：n8n 取回产物并发送到目标（IM、邮件、存储等）。

三者还通过共享卷 ./shared/ 交换数据（ComfyUI 输出、共享工作流文件、跨服务数据），该目录由启动脚本自动创建。

二、ai-stack 目录结构与各文件职责

SUMMARY.md 列出的文件清单与仓库实际内容一致。以仓库根目录视角看，ai-stack/ 下包含：

ai-stack/
├── QUICK-START.md                 ← 3 步快速上手
├── EASY-INSTALL.md                ← 图文详细安装指南
├── TROUBLESHOOTING.md             ← 故障排查
├── README.md                      ← 完整文档
├── SUMMARY.md                     ← 本文章依据的总览
├── CHEAT-SHEET.md                 ← 速查卡
├── INDEX.md / UBUNTU-INSTALL.md   ← 文档索引 / Ubuntu 专项安装
├── docker-compose.yml             ← 栈配置（三服务编排）
├── start.ps1                      ← Windows (PowerShell) 启动器
├── start.sh                       ← Mac/Linux 启动器
└── workflows/
    ├── comfyui-image-generation.json  ← 完整图像生成流水线
    └── comfyui-simple-test.json       ← ComfyUI 连通性测试

其中运行时会另外自动创建两类持久化目录（见 ai-stack/README.md 与启动脚本中的 DIRECTORIES 数组）：

• data/n8n：n8n 的工作流与凭据，挂载到容器内 /home/node/.n8n；
• data/agent-zero：Agent Zero 数据，挂载到 /app/data；
• shared/comfyui/{models,output,input,custom_nodes}：模型、生成图、输入图、自定义节点，分别挂载到 ComfyUI 容器内对应路径。

三、启动、访问与停止：完整操作速查

3.1 启动栈

Windows（PowerShell）：

.\start.ps1

Mac/Linux：

./start.sh

这两个启动脚本并非简单封装 docker compose up。以 ai-stack/start.sh 为例，从源码看它实际执行了五个阶段：

1. 前置检查：依次校验 docker --version、docker info（守护进程是否在运行）、docker compose version，任一失败即退出；
2. GPU 探测：尝试 nvidia-smi --query-gpu=name，检测到 NVIDIA GPU 才标记 HAS_GPU=true，否则提示可用 --cpu 强制 CPU 模式；
3. 创建目录：批量 mkdir -p 出 data/n8n、data/agent-zero 以及 shared/comfyui/models/{checkpoints,loras,vae,controlnet,upscale_models,embeddings,clip} 等 13 个目录；
4. 拉取镜像：docker pull 三个服务镜像（可用 --no-pull 跳过）；
5. 启动并展示状态：docker compose up -d，等待 10 秒后打印 docker compose ps 和三个服务的访问 URL。

3.2 脚本支持的完整参数

SUMMARY.md 的 Quick Reference 只列了启动与停止，而 ai-stack/CHEAT-SHEET.md 和两份启动脚本源码给出了全量参数：

Windows（PowerShell，ai-stack/start.ps1 以 param([switch]$...) 定义）：

.\start.ps1              # 启动栈
.\start.ps1 -Stop        # 停止栈（执行 docker compose down）
.\start.ps1 -Logs        # 查看日志（docker compose logs -f）
.\start.ps1 -Status      # 查看状态（docker compose ps）
.\start.ps1 -NoPull      # 启动但不拉取镜像
.\start.ps1 -CPU         # 强制 CPU 模式（无 GPU 加速）

Mac/Linux（ai-stack/start.sh 的 case 解析，支持长短两种写法）：

./start.sh               # 启动栈
./start.sh --stop        # 停止栈
./start.sh --logs        # 查看日志
./start.sh --status      # 查看状态
./start.sh --no-pull     # 跳过拉镜像
./start.sh --cpu         # 强制 CPU 模式
./start.sh --help        # 查看帮助

也可以绕过脚本直接操作 Docker Compose：

docker compose up -d     # 启动
docker compose down      # 停止
docker compose logs -f   # 日志
docker compose ps        # 状态

3.3 服务访问

服务	URL	用途
n8n	http://localhost:5678	创建与运行自动化工作流
Agent Zero	http://localhost:50080	AI 助手、任务规划
ComfyUI	http://localhost:8188	AI 生成图像

不依赖浏览器也可以直接探活（ai-stack/CHEAT-SHEET.md 中的服务自检命令）：

curl http://localhost:5678/healthz        # n8n 健康检查
curl http://localhost:8188/system_stats   # ComfyUI 系统状态

这两个端点恰好与 docker-compose.yml 中的健康检查呼应：n8n 容器用 wget http://localhost:5678/healthz（interval 30s、start_period 30s），ComfyUI 容器用 curl http://localhost:8188/system_stats（interval 30s、start_period 60s、retries 5）。ComfyUI 的 start_period 更长，与其模型加载较慢的启动特征匹配。

四、四日学习路径：从能跑到会生成

SUMMARY.md 的核心价值之一是一条渐进式学习路线，四个阶段均对应仓库中真实存在的文件与工作流：

Day 1：跑起来

1. 阅读 ai-stack/QUICK-START.md；
2. 安装 Docker（Windows/macOS 用 Docker Desktop，Linux 可参考 ai-stack/UBUNTU-INSTALL.md）；
3. 执行启动脚本；
4. 在浏览器中打开三个服务 URL 验证。

Day 2：测试 ComfyUI 连通性

1. 在 n8n 中导入 ai-stack/workflows/comfyui-simple-test.json；
2. 激活工作流；
3. 访问 http://localhost:5678/webhook/comfyui-status；
4. 确认返回的 JSON 中 status: "connected"。

从该工作流 JSON 的节点结构看，它由 5 个节点组成：Webhook 触发器（n8n-nodes-base.webhook，path 为 comfyui-status，responseMode 为 responseNode）→ 两个并行的 HTTP Request 节点（分别请求 http://comfyui:8188/system_stats 与 http://comfyui:8188/object_info）→ Code 节点汇总（统计 object_info 返回的可用节点数量，并输出各 API 端点清单）→ Respond to Webhook 节点返回格式化 JSON。注意 HTTP 节点里用的是容器内网地址 http://comfyui:8188 而非 localhost——这正是 docker-compose.yml 中 ai-stack-network 网络带来的能力，也是 README 故障排查一节强调的要点（"使用 http://comfyui:8188，不要用 localhost"）。

Day 3：生成第一张图

1. 导入 ai-stack/workflows/comfyui-image-generation.json 并激活；
2. 发送测试请求（ai-stack/README.md 给出的示例）：

curl -X POST http://localhost:5678/webhook/generate-image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cyberpunk city at night, neon lights, rain, highly detailed",
    "negative_prompt": "blurry, low quality",
    "steps": 20,
    "cfg": 7,
    "width": 512,
    "height": 512
  }'

3. 收到包含 image_urls 的 JSON 响应，即第一张 AI 生成图（文件落在 shared/comfyui/output/）。

该流水线工作流（ComfyUI Image Generation Pipeline）值得细看，它是 SUMMARY.md "Day 3" 步骤的完整落地，节点链路为：

• Webhook Trigger（POST generate-image）→
• Prepare ComfyUI Workflow（Code 节点）：从请求体解析 prompt、negative_prompt、seed（缺省随机）、steps（默认 20）、cfg（默认 7）、width/height（默认 512），拼装出 ComfyUI 原生 txt2img 工作流——含 CheckpointLoaderSimple（checkpoint 为 v1-5-pruned-emaonly.safetensors）、EmptyLatentImage、正负 CLIPTextEncode、KSampler（euler / normal / denoise 1）、VAEDecode 与 SaveImage（前缀 n8n_generated）；
• Submit to ComfyUI（HTTP POST http://comfyui:8188/prompt，body 为 {"prompt": <工作流JSON>}）；
• Extract Prompt ID（Code 节点，取出 prompt_id，初始化 check_count=0、max_checks=60）；
• Wait 2 Seconds（n8n-nodes-base.wait，利用 webhookId 实现可恢复的暂停）→
• Check Generation Status（GET http://comfyui:8188/history/{{ $json.prompt_id }}）→
• Check if Complete（Code 节点：若 history 中出现目标 prompt 且 outputs 内含 images 则返回 status: completed 并拼出 /view?filename=...&type=output 图片 URL；否则 check_count+1，达到 60 次（约 2 分钟）抛出超时错误）→
• Generation Complete?（IF 节点，判断 status == "completed"）→ 成功分支走 Respond with Image，未完成分支走 Wait and Retry（再等 2 秒后回到 Check Generation Status，形成轮询循环）。

这套"提交 → 轮询 → 分支"模式就是 SUMMARY.md 所述 "Generate → Poll → Deliver" 闭环的 n8n 实现范例，可以直接作为自建工作流的模板。

Day 4+：自建工作流——学习 n8n 基础、尝试不同 prompt、接入更多服务（本仓库 workflows/ 目录下按集成服务分目录存放了上千个 n8n 工作流 JSON，可作为改造素材）、把创意过程自动化。

五、系统要求与使用场景

5.1 系统要求

SUMMARY.md 给出的硬件门槛分两档：

档位	内存	磁盘	CPU/GPU	系统
最低（CPU 模式）	8 GB	20 GB 可用	任意现代处理器	Windows 10+、macOS 10.15+、Linux
推荐（GPU 模式）	16 GB	50 GB 可用（放模型）	NVIDIA GPU，6+ GB 显存	Windows 10+、Linux（macOS 无 NVIDIA）

GPU 模式的实际前提是安装了 NVIDIA 驱动 + NVIDIA Container Toolkit，且 docker-compose.yml 中 ComfyUI 的 deploy.resources.reservations.devices 才会真正生效。没有 GPU 时启动脚本会自动/可通过 --cpu 参数进入 CPU 模式；compose 文件末尾还预留了被注释的 comfyui-cpu 服务（镜像 frdel/comfyui-docker，CLI_ARGS 加 --cpu，profile 为 cpu-only），需要时取消注释即可。

另外注意 ai-stack/start.sh 中 CPU 模式是通过导出环境变量 COMFYUI_ARGS="--cpu" 实现的，而当前 compose 文件里 ComfyUI 服务固定读取 CLI_ARGS 变量——可以推断 CPU 模式的实际生效依赖所用 ComfyUI 镜像对 COMFYUI_ARGS 的支持，或直接启用注释中的 comfyui-cpu 服务，实操时建议以 docker compose ps 与健康检查状态为准。

5.2 典型使用场景

SUMMARY.md 归纳的四类用途：

1. 自动化图像生成：定时生成每日 artwork、从 RSS 内容派生图像、自动产出社交媒体素材；
2. AI 驱动的工作流：让 Agent Zero 规划复杂任务、n8n 执行计划、ComfyUI 产出视觉内容——三者分工即 compose 文件中 "The Conductor / agent runtime / media generation" 的注释定位；
3. 创意自动化：批量图像处理、设计变体生成、项目素材生产；
4. 学习与实验：学习工作流自动化、实验 AI 图像生成、构建自定义集成。

模型准备方面（ai-stack/README.md 的模型放置表）：Stable Diffusion checkpoints 放 shared/comfyui/models/checkpoints/，LoRA 放 loras/，VAE 放 vae/，ControlNet 放 controlnet/，upscale 模型放 upscale_models/，embeddings 放 embeddings/。预置的图像生成工作流默认加载 v1-5-pruned-emaonly.safetensors，因此首次生成图片前需要先把该 SD 1.5 checkpoint 放入 checkpoints 目录，否则 CheckpointLoaderSimple 会因找不到模型而失败。

六、安全边界：本地默认可用，暴露前须加固

SUMMARY.md 的安全说明与 compose 配置一一对应，可归纳为两条原则：

默认配置（仅本机安全）

• 三个服务端口映射到 localhost，默认无外部访问；
• 本地使用无需认证（n8n 未启用 Basic Auth）。

如果要共享/公网暴露（进阶操作）

• 加反向代理（Traefik/Caddy/nginx）；
• 启用 n8n 认证（README 的 .env 示例支持 N8N_BASIC_AUTH_ACTIVE、N8N_BASIC_AUTH_USER、N8N_BASIC_AUTH_PASSWORD）；
• 配置 HTTPS 证书；
• 设置防火墙规则；
• API Key（如 OPENAI_API_KEY、ANTHROPIC_API_KEY）只留在 .env 中，不要提交进 git。

文档中的醒目警告仍然成立：不要在没有安全措施的暴露下直接连入互联网。

七、故障排查：先日志，再对照速查表

SUMMARY.md 的 Quick Help 给出的三步定位法：

1. 确认 Docker 在运行（任务栏/菜单栏可见鲸鱼图标）；
2. 阅读 ai-stack/TROUBLESHOOTING.md；
3. 查看日志：Windows 用 .\start.ps1 -Logs，Mac/Linux 用 ./start.sh --logs（二者底层都是 docker compose logs -f）。

常见问题的速查表（SUMMARY.md 原文表格 + ai-stack/CHEAT-SHEET.md 补充）：

问题	快速处理
Docker not found	安装 Docker Desktop
Port in use	重启计算机，或先 --stop 再 --status 定位占用
Permission denied	Windows 以管理员运行；Mac 执行 chmod +x start.sh
Can't connect	等待约 2 分钟让服务完成启动
Out of space	清理旧文件，docker system prune -a

更深入的排查手段来自 ai-stack/README.md 的 Troubleshooting 一节：

# 查看日志 / 重启单个服务 / 彻底重置
docker compose logs -f
docker compose restart n8n
docker compose down -v
docker compose up -d

• ComfyUI 看不到 GPU：确认驱动与 NVIDIA Container Toolkit 已装，重启 Docker，用 docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi 验证；
• n8n 连不上 ComfyUI：确认 HTTP 节点用的是容器内网地址 http://comfyui:8188，并用 docker compose ps 确认 ComfyUI 处于 healthy；
• 端口冲突：修改 docker-compose.yml 中 ports 的 "NEW_PORT:INTERNAL_PORT" 映射。

成功检查清单

SUMMARY.md 末尾的 Success Checklist 是验收整条流水线的标准：

• [ ] Docker Desktop 已安装并在运行；
• [ ] AI Stack 已解压到本地；
• [ ] 启动脚本成功执行（终端出现 "AI Stack is running!"）；
• [ ] 三个服务 URL 均能在浏览器打开；
• [ ] 测试工作流（comfyui-simple-test.json）已导入且返回 connected；
• [ ] 第一张图像生成成功。

八、小结

n8n-workflows 仓库的 ai-stack/ 目录提供了一条以 ai-stack/SUMMARY.md 为总纲、以 ai-stack/docker-compose.yml 为编排核心、以 ai-stack/start.sh / ai-stack/start.ps1 为操作入口的本地 AI 自动化部署方案：n8n 负责触发与编排、Agent Zero 负责规划、ComfyUI 负责图像生成，三者通过统一 bridge 网络与 ./shared/ 共享卷协作。仓库同时附带 comfyui-simple-test.json（连通性自测）与 comfyui-image-generation.json（提交-轮询-交付的完整图像流水线）两个可导入 n8n 的工作流，配合四日学习路径与速查文档，可以在本地先验证、再扩展地构建自己的 AI 自动化场景。