n8n-workflows AI 自动化栈实战指南：n8n + Agent Zero + ComfyUI 的一键部署与 Webhook 生图流水线

本文基于仓库中的 DELIVERY-SUMMARY.md 交付总结展开，系统讲解 ai-stack/ 目录下这套 "AI Automation Stack" 的完整构成：Docker Compose 三服务编排、跨平台启动脚本、预置 n8n 工作流模板、环境变量模板与 7 份分层文档体系。读完后，你将能够一条命令拉起 n8n（5678）、Agent Zero（50080）、ComfyUI（8188）三服务栈，理解 GPU 检测与 CPU 回退机制，并掌握 Webhook 驱动 ComfyUI 生图的完整调用链与轮询等待实现。

交付总览：这套 Stack 到底包含什么

DELIVERY-SUMMARY.md 将整套交付物概括为一个"开箱即装"（open and it installs）的本地 AI 自动化栈，目标是生产可用且对不同技能水平的用户都友好。交付物分为四大类：

1. Docker Compose 配置（ai-stack/docker-compose.yml）：编排 n8n、Agent Zero、ComfyUI 三个服务，采用共享卷架构，支持 GPU 加速与 CPU 回退，并配置了健康检查与重启策略；
2. 启动脚本：ai-stack/start.ps1（Windows PowerShell）与 ai-stack/start.sh（Linux/macOS bash），具备 Docker 安装检查、GPU 检测、目录创建、镜像拉取、服务健康等待与状态报告等完整自动化能力；
3. 预置 n8n 工作流：ai-stack/workflows/comfyui-image-generation.json（Webhook → ComfyUI → 响应的完整生图流水线）与 ai-stack/workflows/comfyui-simple-test.json（连通性测试工作流）；
4. 配置文件：ai-stack/.env 环境变量模板与 ai-stack/.gitignore 数据目录排除规则。

配套的文档体系共 7 份指南（详见后文"文档体系"一节），官方给出的统计如下：

指标	数值
交付文件总数	14
文档篇数	7（合计约 30 页）
工作流模板	2
支持平台	Windows、macOS、Linux
包含服务	n8n、Agent Zero、ComfyUI
代码总行数	约 2,100 行

交付总结声明该分支为 feature/ai-automation-stack，状态为 "Ready for PR"，即这套 Stack 以功能分支形式提交、可独立评审合并。

核心编排：docker-compose.yml 三服务架构

ai-stack/docker-compose.yml 是整个 Stack 的骨架。文件头部注释明确了三大访问入口：

• n8n：http://localhost:5678（工作流编排引擎，"The Conductor"）
• Agent Zero：http://localhost:50080（AI Agent 运行时与 UI）
• ComfyUI：http://localhost:8188（AI 图像生成）

服务定义与端口映射

服务	镜像	容器名	端口映射	关键特性
n8n	n8nio/n8n:latest	ai-stack-n8n	5678:5678	健康检查、/shared 卷
agent-zero	frdel/agent-zero-run:latest	ai-stack-agent-zero	50080:80	依赖 n8n 启动、/shared 卷
comfyui	aidockorg/comfyui-cuda:latest	ai-stack-comfyui	8188:8188	NVIDIA GPU 预留、/comfyui 四目录卷

三个服务统一挂在名为 ai-stack-network 的 bridge 网络上，保证容器间可通过服务名互相访问（例如 n8n 中的工作流直接请求 http://comfyui:8188/...）。

n8n 的环境变量细节

n8n 服务的 environment 配置体现了若干实操要点：

• WEBHOOK_URL=http://localhost:5678：注释特别标注这是"critical for correct webhook URLs in editor"，即编辑器中生成的 Webhook 地址是否正确，直接取决于该变量；
• GENERIC_TIMEZONE 与 TZ 均使用 ${TZ:-America/Los_Angeles} 语法，从宿主机 .env 读取时区，默认美西时区；
• EXECUTIONS_DATA_PRUNE=true + EXECUTIONS_DATA_MAX_AGE=168：开启执行数据清理，执行记录保留 168 小时（7 天）；
• N8N_PAYLOAD_SIZE_MAX=256：放大了请求体上限，注释说明目的是"Allow calling local services"——生图流水线的响应中会携带图像元数据，较大的 payload 上限可避免大响应被截断；
• 卷挂载：./data/n8n:/home/node/.n8n 持久化 n8n 实例数据，./shared:/shared 提供三服务共享的交换目录；
• 健康检查：wget -qO- http://localhost:5678/healthz，间隔 30s、超时 10s、重试 3 次、启动宽限期 30s。

ComfyUI 侧的卷映射将 ComfyUI 的四大目录全部落到宿主机的共享区：模型（models）、输出（output）、输入（input）、自定义节点（custom_nodes），对应 ./shared/comfyui/*。GPU 支持通过 deploy.resources.reservations.devices 声明 driver: nvidia, count: all, capabilities: [gpu]，注释明确提示该依赖需要 NVIDIA Container Toolkit。ComfyUI 健康检查使用 curl -f http://localhost:8188/system_stats，启动宽限期放宽到 60s（模型加载较慢）。

CPU 回退变体

文件底部保留了一段被注释的 comfyui-cpu 服务定义（ai-stack/docker-compose.yml#L111-L127），使用 frdel/comfyui-docker:latest 镜像并在 CLI_ARGS 中追加 --cpu，挂载相同的四个卷，且归入 cpu-only profile。从源码结构看，这为"无 GPU 环境下取消注释即切换"的官方回退路径提供了依据；而启动脚本则用命令行参数 --cpu 触发同样的降级逻辑（见下节）。

启动脚本：跨平台的自动化部署流程

ai-stack/start.sh（bash）与 ai-stack/start.ps1（PowerShell）实现了交付总结中宣称的"one-command deployment"。两个脚本参数一一对应：

选项	bash	PowerShell	作用
跳过拉镜像	--no-pull / -n	-NoPull	跳过 docker pull 阶段
CPU 模式	--cpu / -c	-CPU	ComfyUI 以 CPU 模式运行
停止栈	--stop / -s	-Stop	执行 docker compose down
查看日志	--logs / -l	-Logs	执行 docker compose logs -f
查看状态	--status	-Status	执行 docker compose ps

五步启动流程

以 ai-stack/start.sh 为例，脚本按五步推进，每一步都有彩色状态输出：

1. 前置检查：command -v docker 确认 Docker 已安装并打印版本号；docker info 确认守护进程在运行；docker compose version 确认 Compose 插件可用。GPU 检测使用 nvidia-smi --query-gpu=name --format=csv,noheader，成功则记录 GPU 名称，失败仅提示"use --cpu flag for CPU mode"，不阻断流程（GPU 为可选项）。
2. 创建目录结构：脚本内置 13 个目录清单（data/n8n、data/agent-zero，以及 shared/comfyui/models/ 下的 checkpoints、loras、vae、controlnet、upscale_models、embeddings、clip 七个模型子目录，加 output、input、custom_nodes 和 shared/workflows），逐一 mkdir -p。这与 Compose 文件中的卷路径、.gitignore 中排除 data/ 与 shared/ 的规则完全对应，形成"脚本建目录 → 卷持久化 → git 不跟踪"的闭环。
3. 拉取镜像：默认依次 docker pull 三个镜像（n8nio/n8n:latest、frdel/agent-zero-run:latest、aidockorg/comfyui-cuda:latest）；注意 bash 脚本拉取的是 aidockorg/comfyui-cuda:latest，与 Compose 文件一致，而 ai-stack/start.ps1#L168 中拉取的 ComfyUI 镜像为 yanwk/comfyui-boot:latest——这是两个平台脚本之间的一处可留意差异，实际以 docker compose up 时 Compose 文件声明的镜像为准。
4. 启动栈：当 --cpu 被显式指定或未检测到 NVIDIA GPU 时，脚本打印"Starting in CPU mode"并导出 COMFYUI_ARGS="--cpu" 环境变量，随后 docker compose up -d，再 sleep 10 等待服务就绪。
5. 状态展示：docker compose ps 输出容器状态，并打印三个服务的访问地址、常用后续命令（--stop / --logs / --status），以及共享目录位置提示（./shared 为三服务共用，ComfyUI 模型位于 ./shared/comfyui/models）。

Windows 版 ai-stack/start.ps1 流程完全同构：参数声明、Docker/GPU 检查（try/catch 包裹）、相同 13 目录清单、镜像拉取、CPU 模式环境变量、状态报告，唯一差异是拉取的 ComfyUI 镜像名与输出风格。

预置工作流：从连通性测试到完整生图流水线

连通性测试工作流

ai-stack/workflows/comfyui-simple-test.json（名称 "ComfyUI Simple Test"，标签 ComfyUI / Test）用于验证 n8n 能否通过内部网络访问 ComfyUI，节点链路为：

1. Status Check Webhook（n8n-nodes-base.webhook）：GET comfyui-status 路径，responseMode: responseNode；
2. Get ComfyUI Stats：HTTP Request 请求 http://comfyui:8188/system_stats；
3. Get Available Nodes：HTTP Request 请求 http://comfyui:8188/object_info；
4. Format Response（Code 节点）：汇总系统统计与可用节点数量，并返回一组常用端点清单（/prompt、/history/{prompt_id}、/queue、/system_stats、/view?filename=...）；
5. Respond（Respond to Webhook）：以 JSON 形式回传。

两条 HTTP 请求并行发出、共同汇入 Format Response，构成一次"双端点探活"。

生图流水线工作流

ai-stack/workflows/comfyui-image-generation.json（名称 "ComfyUI Image Generation Pipeline"）是交付总结所称"Full webhook→ComfyUI→response pipeline"，完整节点链为：

Webhook Trigger → Prepare ComfyUI Workflow → Submit to ComfyUI → Extract Prompt ID
→ Wait 2 Seconds → Check Generation Status → Check if Complete → Generation Complete?
        ┌──────────────────────────────────────┴─────────────────────────────────┐
        ▼ true（status == completed）                                             ▼ false
Respond with Image（JSON 200）                                    Wait and Retry → 回到 Check Generation Status

关键实现细节（均可在文件源码中逐一核对）：

• 入参解析（Prepare ComfyUI Workflow，Code 节点）：从 Webhook 请求体提取 prompt、negative_prompt、seed、steps、cfg、width、height，均带默认值（缺省 prompt 为 "a beautiful sunset over mountains, highly detailed, 4k"；steps=20、cfg=7、512x512、seed 缺省随机生成）；
• 工作流构造：Code 节点内以 API 格式构建了一个标准 txt2img 图——节点 3 为 KSampler（euler / normal scheduler / denoise=1）、节点 4 为 CheckpointLoaderSimple（加载 v1-5-pruned-emaonly.safetensors，即要求模型已放入 shared/comfyui/models/checkpoints/）、节点 5 为 EmptyLatentImage、节点 6/7 为正负向 CLIPTextEncode、节点 8 为 VAEDecode、节点 9 为 SaveImage（filename_prefix: n8n_generated）；
• 提交与轮询：HTTP 节点 POST 到 http://comfyui:8188/prompt，jsonBody 为 {{ JSON.stringify({ prompt: $json.prompt }) }}；随后 Extract Prompt ID 节点校验 prompt_id 存在并初始化 check_count=0、max_checks=60；Wait 节点每次等待 2 秒后请求 http://comfyui:8188/history/{prompt_id}；
• 完成判定：Check if Complete 节点在 history 命中且存在 images 输出时返回 status: completed，并组装 image_urls（http://comfyui:8188/view?filename=...&type=output）与生成参数；未命中则自增 check_count，达到 60 次（即约 2 分钟轮询上限）抛出 "Generation timed out" 错误；
• 分支响应：IF 节点按 status == completed 分流——成功走 Respond with Image（JSON 200），失败经 Wait and Retry 回到轮询循环，超时/异常分支由 Respond with Error 以 500 状态码返回 Generation failed 详情。

两个工作流的 meta.templateCredsSetupCompleted 均为 true，意味着导入 n8n 后即可激活使用，无需额外配置凭据（全部走内部网络 HTTP 调用）。

配置文件：.env 与 .gitignore

ai-stack/.env 是环境变量模板，交付总结中将其描述为"Environment variables template"。实际内容包含：

• TZ=America/Los_Angeles：三服务共用的时区；
• N8N_BASIC_AUTH_ACTIVE=false / N8N_BASIC_AUTH_USER=admin / N8N_BASIC_AUTH_PASSWORD=changeme：基础认证开关与默认凭据（默认值 changeme 显然需要在生产环境中修改）；
• 两项被注释的可选配置：反向代理场景下的外部 WEBHOOK_URL，以及供 Agent Zero 使用的 OPENAI_API_KEY、ANTHROPIC_API_KEY。

ai-stack/.gitignore 的排除策略体现了数据与代码分离的思路：data/ 与 shared/（两个持久化卷目录）整体忽略；.env.local、.env.production、.env.*.local 等携带密钥的变体被忽略，而 !.env 反排除规则保证模板本身继续被跟踪；此外还覆盖日志（*.log、logs/）、临时文件（*.tmp、.cache/）、IDE 文件、备份文件与操作系统产物。

文档体系：7 份分层指南与导航结构

交付总结的另一半篇幅用于描述 7 份配套文档的定位与分工（均位于 ai-stack/ 目录下）：

文档	目标读者	篇幅	核心内容
INDEX.md	所有用户（导航中枢）	—	按经验水平/目标分类、建议阅读顺序、快速链接、成功路径
QUICK-START.md	有经验的开发者	1 页	3 步极简流程、命令速查，5 分钟跑起来
EASY-INSTALL.md	零基础新手	5 页	带视觉指示的分步安装、"你会看到什么"示例、Docker 安装详解
TROUBLESHOOTING.md	所有用户	4 页	10 个常见问题与解法、报错解释、紧急重置步骤
CHEAT-SHEET.md	日常使用者	3 页	全部命令、API 速查、常见修复表、可打印格式、备份说明
SUMMARY.md	学习型用户	4 页	系统架构、4 天学习路径、用例、系统要求、成功清单
README.md	高级用户	8 页	完整技术文档、API 参考、集成架构、安全注意事项、部署指南

交付总结用一张层级图描述了这套文档的导航关系：INDEX.md 位于顶层作为"Navigation & Guidance"，向下分流到三条主路径——QUICK-START（Fast）、EASY-INSTALL（Detailed）、README（Complete）；三条主路径再共同汇聚到三个支撑文档——TROUBLESHOOTING（Fix）、CHEAT-SHEET（Reference）、SUMMARY（Learn）。

与之配套的是三类典型用户旅程：

• 完全新手：读 INDEX → 按 EASY-INSTALL 分步安装 → 遇到问题查 TROUBLESHOOTING → 打印 CHEAT-SHEET 备用 → 用 SUMMARY 深入学习；
• 有经验用户：读 INDEX → QUICK-START 三条命令跑起 → CHEAT-SHEET 日常参考 → README 深入；
• 排障用户：遇到问题 → 查 TROUBLESHOOTING 的 10 个常见问题 → 定位解法 → 回到工作。

交付总结强调的核心特性与后续规划

DELIVERY-SUMMARY.md 将整套 Stack 的价值主张归纳为四个维度，并逐条给出支撑特性：

• 用户体验：一键部署、自动 GPU 检测、CPU 回退模式、清晰状态报告、完整错误处理、多层级文档；
• 技术质量：生产级 Docker Compose、全服务健康检查、持久卷、共享数据架构、网络隔离、重启策略（三个服务均为 restart: unless-stopped）；
• 文档质量：7 份指南、覆盖多种经验水平、视觉化指示、分步说明、排障覆盖、速查材料；
• 亮点总结：真正 turnkey（单命令部署、自动环境准备、无需手动配置）、无障碍（全技能层级文档）、生产可用（健康检查/重启策略/卷管理/安全考量）、可扩展（结构清晰、文档完备、易于扩展）。

在可选增强方向上，文档列出了后续规划清单：视频教程、Docker Hub 镜像、Kubernetes manifests、Terraform/IaC 模板、CI/CD 流水线示例、更多工作流模板、模型下载自动化、Web 端安装器。值得注意的是，当前仓库根目录实际已存在 k8s/（含 namespace、deployment、service、ingress、configmap 五个清单）与 helm/workflows-docs/ 目录，说明规划清单中的部分方向在仓库其他分支/模块中已有落地形态，可作为延伸阅读。

适用前提与限制

结合交付总结与 ai-stack/docker-compose.yml 的实际配置，使用这套 Stack 需满足：

1. 宿主机已安装 Docker 且 Compose v2 插件可用（启动脚本会前置校验，缺失即中止并提示）；
2. GPU 加速需要 NVIDIA GPU 与 NVIDIA Container Toolkit；无 GPU 时通过 --cpu 显式降级，或启用 Compose 文件中注释掉的 comfyui-cpu 变体；
3. 生图工作流默认加载 v1-5-pruned-emaonly.safetensors 检查点，需先将其放入 shared/comfyui/models/checkpoints/，否则流水线会在模型加载环节失败；
4. 轮询上限为 60 次 × 2 秒 ≈ 2 分钟，CPU 模式下复杂图生成可能触达该超时上限，可按需调整 Wait 间隔与 max_checks；
5. 默认 N8N_BASIC_AUTH_ACTIVE=false，栈面向 localhost 本地使用设计，公网暴露前需开启认证并修改 .env 中的默认口令。

这套 "AI Automation Stack" 的价值在于：它不是孤立的三份文档，而是把编排配置（Compose）、部署自动化（双平台脚本）、可运行的业务模板（两个 Webhook 工作流）与分层文档体系（7 份指南）打包成一个可独立评审的功能分支，读者可以从 ai-stack/INDEX.md 进入，按自身水平选择路径，最终在 5 分钟内获得一个可对外提供生图 Webhook 服务的本地 AI 自动化栈。