n8n-workflows 的 AI Stack 实战指南：用 n8n + Agent Zero + ComfyUI 搭建本地 AI 自动化栈

本文以仓库中 AI Stack 文档索引 为主线，完整还原这套本地 AI 自动化栈（n8n 工作流引擎 + Agent Zero 智能体运行时 + ComfyUI 图像生成）的文档体系、一键启动方式与验证流程。读完本文，你将能够：为不同经验水平选择合适的入门文档路径、通过 start.sh / start.ps1 一键拉起全部三个服务、读懂 docker-compose.yml 中的端口/卷/健康检查配置，并用仓库预置的 n8n 工作流验证 ComfyUI 连通性与首次图像生成。

AI Stack 的三个服务与访问入口

ai-stack/INDEX.md 给出的"Quick Links"明确了栈内三个服务的本地访问地址，这也是启动后第一个要核对的清单：

服务	用途	端口	访问地址
n8n	工作流自动化引擎（"指挥者"）	5678	http://localhost:5678
Agent Zero	AI 智能体运行时与规划 UI	50080	http://localhost:50080
ComfyUI	AI 图像/视频生成	8188	http://localhost:8188

从 docker-compose.yml 的源码可以确认这三个端口映射与索引文档完全一致，同时能拿到更精确的部署细节：

• n8n：镜像 n8nio/n8n:latest，映射 5678:5678，健康检查为 wget -qO- http://localhost:5678/healthz（间隔 30 秒、超时 10 秒、重试 3 次、启动宽限期 30 秒）；
• Agent Zero：镜像 frdel/agent-zero-run:latest，映射 50080:80（Web UI 在容器内 80 端口），通过 depends_on: n8n 声明启动顺序；
• ComfyUI：镜像 aidockorg/comfyui-cuda:latest，映射 8188:8188，通过 CLI_ARGS=--listen 0.0.0.0 --port 8188 监听容器网络；健康检查为 curl -f http://localhost:8188/system_stats（启动宽限期 60 秒，因为模型服务加载较慢）；其 deploy.resources.reservations.devices 声明了 driver: nvidia, count: all 的 GPU 预留，前提是宿主机安装了 NVIDIA Container Toolkit。

三个服务都挂在同一个 ai-stack-network bridge 网络上，容器间互访使用服务名（如 http://comfyui:8188），而不是 localhost——这一点在排查"n8n 连不上 ComfyUI"问题时是关键。

选择你的入口文档：从 INDEX.md 出发的两条路线

INDEX.md 的核心职责就是为不同读者分流。它按"完全新手"与"快速上手"两类给出了起点：

完全新手（没用过 Docker 或命令行）

1. EASY-INSTALL.md（Windows/Mac）：逐步图文说明、通俗解释每个概念、带"你会看到什么"的示例，适合第一次接触 Docker 的人；
2. UBUNTU-INSTALL.md（Ubuntu/Linux）：完整的 Ubuntu 安装指南、Linux 上的 Docker 配置、NVIDIA GPU 配置以及 Ubuntu 专属排错。

快速上手（只想尽快跑起来）

QUICK-START.md 只有 3 个步骤：装 Docker → 获取仓库中的 ai-stack 目录 → 运行启动脚本，宣称"5 分钟跑起来"，适合有经验的读者。

四份参考文档与文档总览表

INDEX 文档将剩余材料归为"参考指南"，并给出了一张文档总览表。这里完整继承该表，同时把各文档的实际职责结合仓库内容补齐：

文档	篇幅	难度	定位
QUICK-START.md	1 页	简单	三步跑起来
EASY-INSTALL.md	5 页	简单	新手详细安装指南
CHEAT-SHEET.md	3 页	中等	命令速查（适合打印）
TROUBLESHOOTING.md	4 页	中等	故障修复、错误信息解释、紧急重置
SUMMARY.md	4 页	中等	系统概览、学习路径、用例清单
README.md	8 页	进阶	完整文档：API 参考、架构、集成指南

各文档的职责边界：

• CHEAT-SHEET：全部命令集中在一处——启停/状态/日志、服务 URL、重要目录、ComfyUI API 速查（POST /prompt、GET /history/{prompt_id}、GET /view?filename=...&type=output）、n8n 工作流导入六步法、紧急重置（docker compose down -v）与备份命令（CHEAT-SHEET.md）；
• TROUBLESHOOTING：按"你会看到什么"组织故障，覆盖 Docker 未安装、守护进程未运行、macOS 权限拒绝、端口占用、Windows 脚本窗口闪退（Set-ExecutionPolicy RemoteSigned）等场景（TROUBLESHOOTING.md）；
• SUMMARY：系统概览、Day 1 起的分天学习路径、硬件需求（CPU 模式最低 8GB 内存/20GB 磁盘；GPU 模式建议 16GB 内存/50GB 磁盘/NVIDIA 6GB+ 显存）与成功检查清单（SUMMARY.md）；
• README：完整架构、ComfyUI API 参考、.env 配置与安全说明（README.md）。

建议阅读顺序：Day 1 到日常参考

INDEX.md 给出的"Day 1 → Ongoing"路线是整套文档体系的使用节奏，这里原样保留：

Day 1：安装

1. QUICK-START.md（如果是新手则先读 EASY-INSTALL.md）
2. 把整个栈跑起来
3. 在浏览器中打开全部三个服务

Day 2：第一次使用

1. SUMMARY.md —— 理解你手上有什么
2. 导入测试工作流
3. 生成第一张图

Day 3：深入学习

1. README.md —— 学习细节
2. 实验不同工作流
3. 尝试不同的 prompt

日常：作为参考手册

1. CHEAT-SHEET.md —— 随手可查
2. TROUBLESHOOTING.md —— 出问题时
3. README.md —— 需要细节时

其中 Day 2 的"导入测试工作流"对应仓库中 ai-stack/workflows/ 目录下的两个预置 JSON：先导入 comfyui-simple-test.json 验证连通性，再导入 comfyui-image-generation.json 跑通完整生图链路（下文有验证细节）。

按经验水平与按目标的两条选择路径

按经验水平

新手（从未用过 Docker）:
1. EASY-INSTALL.md     ← 从这里开始
2. TROUBLESHOOTING.md  ← 遇到问题时
3. CHEAT-SHEET.md      ← 打印一份
4. SUMMARY.md          ← 继续学习

中级（用过 Docker）:
1. QUICK-START.md      ← 跑起来
2. SUMMARY.md          ← 理解系统
3. CHEAT-SHEET.md      ← 日常速查
4. README.md           ← 深入阅读

高级（熟悉 Docker）:
1. README.md           ← 完整文档
2. docker-compose.yml  ← 按需求定制
3. CHEAT-SHEET.md      ← 快速参考

按目标

• "我只要它能跑起来" → QUICK-START.md 或 EASY-INSTALL.md
• "某处坏了" → TROUBLESHOOTING.md
• "这东西怎么用？" → SUMMARY.md → README.md
• "某个命令是什么？" → CHEAT-SHEET.md
• "我想彻底搞懂一切" → README.md → docker-compose.yml

一键启动：start.sh 与 start.ps1 的完整参数

无论走哪条文档路线，最终都会落到同一个动作：在 ai-stack 目录运行启动脚本。INDEX.md 的"Success Path"第 3 步即"Run the start script"。

Linux/macOS（start.sh）：

chmod +x start.sh
./start.sh               # 启动
./start.sh --stop        # 停止
./start.sh --logs        # 查看日志
./start.sh --status      # 查看状态
./start.sh --no-pull     # 拉取前不 pull 镜像
./start.sh --cpu         # 强制 CPU 模式（不用 GPU）

Windows PowerShell（start.ps1）：

.\start.ps1              # 启动
.\start.ps1 -Stop        # 停止
.\start.ps1 -Logs        # 查看日志
.\start.ps1 -Status      # 检查状态
.\start.ps1 -NoPull      # 不 pull 镜像直接启动
.\start.ps1 -CPU         # 强制 CPU 模式

从 start.sh 源码可以看到参数解析与 --help 的完整定义（支持 -n、-c、-s、-l 等短选项），以及脚本执行时实际完成的 5 件事，与 README.md 中"脚本会做什么"一一对应：

1. 检查 Docker：依次验证 docker 命令存在、docker info 守护进程可用、docker compose version 可用；再用 nvidia-smi --query-gpu=name 探测 NVIDIA GPU，探测不到则提示"使用 --cpu 进入 CPU 模式"；
2. 创建目录结构：一次性创建 14 个目录，包括 data/n8n、data/agent-zero、shared/comfyui/models/{checkpoints,loras,vae,controlnet,upscale_models,embeddings,clip}、shared/comfyui/{output,input,custom_nodes} 与 shared/workflows；
3. 拉取镜像：n8nio/n8n:latest、frdel/agent-zero-run:latest、aidockorg/comfyui-cuda:latest（--no-pull 跳过）；
4. 启动栈：docker compose up -d，若检测到无 GPU 或指定了 --cpu，会导出 COMFYUI_ARGS="--cpu" 环境变量并提示以 CPU 模式启动；
5. 展示状态与 URL：docker compose ps 后打印三个服务地址，出现 "AI Stack is running!" 即启动成功。

一个值得注意的源码级细节：start.sh 中 --cpu 导出的是 COMFYUI_ARGS 变量，而当前 docker-compose.yml 中正式的 comfyui 服务写死了 CLI_ARGS=--listen 0.0.0.0 --port 8188，CPU 变体（frdel/comfyui-docker:latest + --cpu，带 cpu-only profile）目前以注释块形式存在。从源码结构看，若纯 CPU 环境下 CUDA 镜像无法运行，可以推断需要手动启用该注释块中的 comfyui-cpu 服务作为替代方案。

验证首次运行：健康检查与两个预置工作流

栈跑起来后，按 INDEX 文档"Quick Links"核对三个 URL 可访问，再叠加两个更硬核的健康检查（来自 CHEAT-SHEET.md）：

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

随后进入 SUMMARY.md 的 Day 2 流程：

1. 连通性测试（ai-stack/workflows/comfyui-simple-test.json）

导入 n8n 并激活后，访问 http://localhost:5678/webhook/comfyui-status，应返回 ComfyUI 的系统统计。从该工作流的节点构成看（解析 JSON 可确认），它由 5 个节点组成：Webhook 触发 → 两个 HTTP Request 分别抓取 ComfyUI 统计与可用节点列表 → Code 节点格式化 → Respond to Webhook 返回，是一条典型的只读探活链路。

2. 完整生图管线（ai-stack/workflows/comfyui-image-generation.json）

激活后发送 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
  }'

从该工作流的 12 个节点可以看出完整轮询逻辑：Webhook 触发 → Code 组装 ComfyUI 工作流 JSON → HTTP 提交 POST /prompt → 提取 prompt_id → Wait 2 秒 → HTTP 查询 GET /history/{prompt_id} → Code 判断是否完成 → IF 分支：完成则 Respond with Image，未完成则进入 "Wait and retry" 的等待-重试循环，异常走 "Respond with error"。这正是 README.md 中"Typical Workflow Loop"（触发 → 规划 → 生成 → 轮询 → 交付）在 n8n 侧的落地实现。

配置要点：端口、GPU 与 .env

• 端口冲突：按 README.md 说明，编辑 docker-compose.yml 的 ports 段改为 "新端口:容器端口" 即可；三个容器端口分别是 5678、80（Agent Zero）、8188；
• GPU 不可见：确认 NVIDIA 驱动与 NVIDIA Container Toolkit 已装，重启 Docker，用 docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi 验证；
• .env 环境变量（见 README.md）：

TZ=America/Los_Angeles            # 时区，compose 中默认也是 America/Los_Angeles
N8N_BASIC_AUTH_ACTIVE=false       # 非本地部署时应启用 Basic Auth
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=changeme
OPENAI_API_KEY=sk-your-key-here    # Agent Zero 可选
ANTHROPIC_API_KEY=sk-ant-your-key-here
WEBHOOK_URL=https://your-domain.com  # 反向代理后必须配置

• 安全基线：默认所有服务仅 localhost 可达；对外暴露前需加反向代理（Traefik/Caddy/nginx）、启用 n8n 认证、API key 只放 .env 且不要提交到 git。

Pro Tips 与成功路径

INDEX 文档最后给出的 5 条经验建议与 9 步成功路径，是收尾自查清单：

Pro Tips

1. 打印 CHEAT-SHEET.md，放在电脑旁边；
2. 收藏 INDEX.md 作为导航页；
3. 即使有基础，也建议先通读 EASY-INSTALL.md；
4. 读 SUMMARY.md 建立全局理解；
5. 常备 TROUBLESHOOTING.md——"你迟早会用到它"。

Success Path（9 步）

1. 阅读 EASY-INSTALL.md 或 QUICK-START.md
2. 安装 Docker Desktop
3. 运行启动脚本
4. 打开全部三个服务
5. 导入测试工作流
6. 生成第一张图
7. 阅读 SUMMARY.md 继续学习
8. 构建自己的工作流
9. 分享你的成果

对照 SUMMARY.md 的成功检查清单逐项打勾（Docker 在运行、启动脚本成功、三个 URL 可访问、测试工作流通、首图生成成功）后，即可基于 docker-compose.yml 的卷结构（data/n8n 持久化工作流与凭据、shared/comfyui/models 放模型、shared/workflows 跨服务共享文件）开始构建属于自己的 n8n + ComfyUI 自动化工作流。