n8n-workflows AI Stack 运维速查：本地 n8n + Agent Zero + ComfyUI 一体化栈的命令参考、ComfyUI API 与故障处理

本文以 ai-stack/CHEAT-SHEET.md 为骨架，系统梳理 n8n-workflows 仓库中「AI Automation Stack」子项目的日常运维操作：如何在 Windows 与 Mac/Linux 上启动、停止、查看状态与日志，如何理解三个服务（n8n / Agent Zero / ComfyUI）的端口与健康检查端点，如何调用 ComfyUI API 提交与轮询出图任务，以及如何执行 Docker 维护、紧急重置、备份与安全加固。读完后，你可以把这篇文档当作「打印版速查表」配合源码直接使用，并在遇到问题时快速定位到 ai-stack/docker-compose.yml 与启动脚本中的对应实现。

栈的整体构成：三个服务、三个端口

AI Stack 是一个单命令可部署的本地 AI 自动化栈，由三个容器化服务组成，均定义在 ai-stack/docker-compose.yml 中：

服务	角色	端口	访问地址
n8n	工作流编排引擎（"指挥者"）	5678	http://localhost:5678
Agent Zero	AI Agent 运行时与规划界面	50080	http://localhost:50080
ComfyUI	AI 图像/视频生成	8188	http://localhost:8188

三者共享一个 ai-stack-network 桥接网络（见 ai-stack/docker-compose.yml#L129-L132），这意味着容器内部可以互相用服务名（如 http://comfyui:8188）访问，而浏览器访问则一律走 localhost 加宿主端口——这一点是后文「n8n 连不上 ComfyUI」类问题的关键。

启动与停止：完整的命令参考

速查表（CHEAT-SHEET）中给出的基础命令如下。

Windows（PowerShell）

# Start
.\start.ps1

# Stop
.\start.ps1 -Stop

# Check Status
.\start.ps1 -Status

# View Logs
.\start.ps1 -Logs

Mac / Linux

# Start
./start.sh

# Stop
./start.sh --stop

# Check Status
./start.sh --status

# View Logs
./start.sh --logs

速查表之外：脚本实际支持的全部参数

CHEAT-SHEET 只列出了四个动作，但 ai-stack/start.sh 与 ai-stack/start.ps1 实际支持更多选项，建议一并纳入你的日常参考。两个脚本的参数解析分别位于 start.sh#L61-L100（bash while 循环）与 start.ps1#L8-L14（PowerShell param 块）：

功能	Windows	Mac/Linux
启动	.\start.ps1	./start.sh
停止	.\start.ps1 -Stop	./start.sh --stop（短参 -s）
查看状态	.\start.ps1 -Status	./start.sh --status
查看日志	.\start.ps1 -Logs	./start.sh --logs（短参 -l）
跳过拉取镜像	.\start.ps1 -NoPull	./start.sh --no-pull（短参 -n）
强制 CPU 模式	.\start.ps1 -CPU	./start.sh --cpu（短参 -c）
帮助	—	./start.sh --help（短参 -h）

各动作在源码中的落点很直接：stop 执行 docker compose down，logs 执行 docker compose logs -f，status 执行 docker compose ps（见 start.sh#L103-L118）。

启动脚本到底做了什么

运行 ./start.sh 时，脚本按五步执行，正好解释了速查表「Success Indicators」中为什么终端会打印出那串服务地址：

1. 前置检查：依次验证 docker 命令存在、Docker daemon 正在运行、docker compose 可用，并尝试通过 nvidia-smi 探测 NVIDIA GPU（start.sh#L124-L167）；
2. 创建目录结构：按 DIRECTORIES 数组批量 mkdir -p，覆盖 data/n8n、data/agent-zero 以及 shared/comfyui/models 下的 checkpoints、loras、vae、controlnet、upscale_models、embeddings、clip 等模型子目录（start.sh#L174-L188）；
3. 拉取镜像：默认拉取 n8nio/n8n:latest、frdel/agent-zero-run:latest、aidockorg/comfyui-cuda:latest 三个镜像，可用 --no-pull 跳过（start.sh#L202-L217）；
4. 启动栈：docker compose up -d，随后 sleep 10 等待服务就绪；
5. 打印状态：docker compose ps 加三色服务 URL 横幅。

两点与源码相关的观察值得注意：

• 镜像以 compose 文件为准：脚本中的 docker pull 只是预热，真正决定容器镜像的是 ai-stack/docker-compose.yml#L75 中声明的 aidockorg/comfyui-cuda:latest。从源码看，start.ps1 中预热的 ComfyUI 镜像（yanwk/comfyui-boot:latest，见 start.ps1#L168）与 compose 文件声明的镜像并不一致，Windows 用户若手动验证镜像版本时请以 compose 文件为准。
• CPU 模式的实际生效方式：start.sh 在检测到无 GPU 或传入 --cpu 时会导出 COMFYUI_ARGS="--cpu"（start.sh#L224-L227），但当前版本的 docker-compose.yml 中 ComfyUI 服务的 CLI_ARGS 固定为 --listen 0.0.0.0 --port 8188（docker-compose.yml#L80），并未引用该环境变量；compose 文件中另有一个被注释掉的 comfyui-cpu 服务变体，其 CLI_ARGS 显式带 --cpu（docker-compose.yml#L108-L127）。从源码结构看，若确需在无 GPU 环境跑 CPU 推理，更稳妥的做法是启用该注释变体而非依赖 --cpu 参数。

服务健康检查：速查表里的两条 curl 从哪里来

速查表「Check if Services are Running」给出的两条命令：

curl http://localhost:5678/healthz
curl http://localhost:8188/system_stats

并非任意 URL，它们与 docker-compose.yml 中配置的健康检查端点一一对应：

• n8n 容器的 healthcheck 就是 wget -qO- http://localhost:5678/healthz，每 30 秒一次、重试 3 次、启动宽限 30 秒（docker-compose.yml#L42-L47）；
• ComfyUI 容器的 healthcheck 是 curl -f http://localhost:8188/system_stats，每 30 秒一次、重试 5 次、启动宽限 60 秒（docker-compose.yml#L101-L106）。

因此当浏览器打不开服务时，先用 docker compose ps 看容器是否处于 Up (healthy)，再用上面的 curl 区分「容器活着但应用未就绪」与「端口未映射」两种情况。Agent Zero 在 compose 文件中未配置 healthcheck（docker-compose.yml#L52-L67），只能靠浏览器访问 http://localhost:50080 确认。

关键目录结构：数据在哪里、模型放哪里

速查表给出的目录速览：

ai-stack/
├── data/n8n/              ← Your n8n workflows
├── data/agent-zero/       ← Agent Zero data
└── shared/
    └── comfyui/
        ├── models/        ← Put AI models here
        ├── output/        ← Generated images here
        └── input/         ← Input images here

结合启动脚本的 DIRECTORIES 列表（start.sh#L174-L188）与 ai-stack/README.md 的目录说明，完整结构如下：

ai-stack/
├── docker-compose.yml      # 栈的主配置
├── start.ps1 / start.sh    # 双平台启动脚本
├── data/                   # 持久化数据（脚本自动创建）
│   ├── n8n/                # n8n 工作流与凭据 → 容器内 /home/node/.n8n
│   └── agent-zero/         # Agent Zero 数据 → 容器内 /app/data
└── shared/                 # 三服务共享卷 → 容器内 /shared
    ├── comfyui/
    │   ├── models/         # checkpoints / loras / vae / controlnet /
    │   │                   # upscale_models / embeddings / clip
    │   ├── output/         # 生成的图片
    │   ├── input/          # 输入图片
    │   └── custom_nodes/   # ComfyUI 扩展节点
    └── workflows/          # 跨服务共享的工作流文件

这些宿主机目录通过 compose 文件中的 volume 映射进容器：n8n 挂载 ./data/n8n 与 ./shared（docker-compose.yml#L36-L38），Agent Zero 挂载 ./shared 与 ./data/agent-zero（docker-compose.yml#L60-L62），ComfyUI 挂载 models / output / input / custom_nodes 四个目录（docker-compose.yml#L81-L89）。也就是说，宿主机上 shared/comfyui/output/ 里的文件就是 ComfyUI 生成结果的本体，不需要额外从容器里拷贝。

ComfyUI API 速查：从速查表三条到完整参考

速查表「ComfyUI API Quick Reference」收录了三条最常用端点：

# 提交出图任务
POST http://localhost:8188/prompt

# 查询任务状态
GET http://localhost:8188/history/{prompt_id}

# 获取生成的图片
GET http://localhost:8188/view?filename={name}&type=output

ai-stack/README.md 的 API Reference 在此基础上补充了两条：GET /queue（查看队列状态）与 GET /system_stats（系统状态，即上文健康检查所用端点）。POST /prompt 的请求体为 {"prompt": { /* ComfyUI 工作流 JSON */ }}，响应返回 {"prompt_id": "..."}，后续的 history 轮询与 view 取图都围绕这个 prompt_id 展开。

预置工作流印证：这套 API 在仓库里如何被真实调用

仓库内 ai-stack/workflows/comfyui-image-generation.json 是一个完整的 Webhook 出图流水线，它把上面的 API 串成了异步轮询闭环：

1. Webhook 触发：POST /webhook/generate-image，接收 prompt、negative_prompt、seed、steps、cfg、width、height 参数，缺省时回退为「日落风景」提示词与 512×512 等默认值；
2. 构造 ComfyUI 工作流：Code 节点在 JS 中动态拼装 txt2img 工作流 JSON（KSampler + CheckpointLoaderSimple + EmptyLatentImage + 双 CLIPTextEncode + VAEDecode + SaveImage，checkpoint 默认指向 v1-5-pruned-emaonly.safetensors）；
3. 提交任务：HTTP Request 节点 POST http://comfyui:8188/prompt（comfyui-image-generation.json#L28-L42）——注意这里用的是容器内网络名 comfyui 而非 localhost；
4. 轮询完成：等待 2 秒后 GET http://comfyui:8188/history/{{prompt_id}}（#L53-L75），Code 节点检查 history 中是否出现带 outputs.images 的记录；未完成则递增 check_count，最多 60 次（即约 2 分钟）后抛出超时错误；
5. 交付结果：完成后 Respond with Image 节点以 JSON 返回 image_urls（形如 http://comfyui:8188/view?filename=...&type=output）；失败路径经 Wait and Retry 回到轮询节点，最终由 Respond with Error 以 500 状态码返回。

调用示例（来自 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
  }'

另一个 ai-stack/workflows/comfyui-simple-test.json 是连通性自检工作流：GET /webhook/comfyui-status 触发后，并行请求 ComfyUI 的 /system_stats 与 /object_info（统计可用节点数量），聚合为一段「connected」状态 JSON 返回（#L18-L49）。在导入正式出图工作流之前，建议先跑这个轻量测试确认 n8n 到 ComfyUI 的内部网络是通的。

n8n 工作流导入：六步操作

速查表「n8n Workflow Import」的标准流程：

1. 打开 http://localhost:5678
2. 点击侧边栏 "Workflows"
3. 点击 "Import from File"
4. 选择工作流 JSON 文件
5. 点击 "Save"
6. 点击 "Active" 开关启用工作流

导入后 Webhook 路径即生效（如 comfyui-status 对应上文自检工作流）。一个与部署相关的配置细节：compose 文件中 WEBHOOK_URL=http://localhost:5678（docker-compose.yml#L27）保证了 n8n 编辑器里生成的 Webhook URL 正确指向本机；若日后放到反向代理后面，需按 README 的说明修改该变量。

Docker 维护命令与紧急重置

速查表「Quick Commands」收录的容器维护命令：

# See all running containers
docker ps

# Stop all containers
docker stop $(docker ps -q)

# Remove all containers
docker rm $(docker ps -aq)

# Clean up Docker
docker system prune -a

对应的 compose 级命令（README 的 Commands 一节）是 docker compose up -d / docker compose down / docker compose logs -f / docker compose ps，四者与上文启动脚本的各动作一一对应。

紧急重置（Emergency Reset）

速查表明确警告：这会删除所有数据并从头开始。

Windows：

.\start.ps1 -Stop
docker compose down -v
.\start.ps1

Mac/Linux：

./start.sh --stop
docker compose down -v
./start.sh

关键在于 docker compose down -v 的 -v 参数——它会连同命名卷一起删除。执行前请先完成下一节的备份。

常见问题速查表

问题	解决方案
Docker 未运行	打开 Docker Desktop，等待鲸鱼图标就绪
端口被占用	先执行 stop 命令，再重新启动
Permission denied	Windows：以管理员身份运行；Mac：chmod +x start.sh
无法连接	等待 2 分钟，确认 Docker 正在运行
磁盘空间不足	删除旧文件，执行 docker system prune -a

每个问题在 ai-stack/TROUBLESHOOTING.md 中都有展开的「现象 + 修复步骤」版本（共 10 个问题，含 Windows 执行策略 Set-ExecutionPolicy RemoteSigned、GPU 未检测、下载缓慢等场景），排障时建议以速查表为索引、以该文档为详细手册。两个高频根因值得记住：

• n8n 连不上 ComfyUI：工作流内必须用 Docker 内部网络地址 http://comfyui:8188，而不是 localhost——预置工作流中的 URL 正是这么写的；
• 端口冲突：修改 ai-stack/docker-compose.yml 中 ports 的宿主机端口映射（"NEW_PORT:INTERNAL_PORT" 形式）。

为 ComfyUI 添加模型

速查表「Adding Models to ComfyUI」的三步：

1. 下载模型文件（.safetensors 或 .ckpt）；
2. 放入正确目录：
   • Checkpoints： shared/comfyui/models/checkpoints/
   • LoRAs： shared/comfyui/models/loras/
   • VAE： shared/comfyui/models/vae/
3. 重启 ComfyUI（或刷新浏览器）。

启动脚本还会自动创建 controlnet、upscale_models、embeddings、clip 四个模型子目录（start.sh#L174-L188），README 中给出了全部六类模型的目录对照表。由于模型目录是宿主机挂载卷，放入文件后刷新 ComfyUI 即可被 CheckpointLoaderSimple 等节点识别。仓库预置出图工作流默认加载 v1-5-pruned-emaonly.safetensors（Stable Diffusion 1.5），因此第一个要下载的 checkpoint 就是它；其他模型来源可参考 Hugging Face、Civitai 等公开模型站（速查表中列出了对应站点名称，具体地址请自行搜索，本文不附外部链接）。

备份、安全提醒与启动前检查

备份

速查表列出的关键备份对象：

data/n8n/           ← 你的工作流
shared/workflows/   ← 共享工作流文件
.env                ← 你的配置

快速备份命令：

# Windows
xcopy /E /I data backup\data
xcopy /E /I shared backup\shared

# Mac/Linux
cp -r data backup/data
cp -r shared backup/shared

ai-stack/.env 并非仓库内置文件，而是按需创建的本地配置。README 的 Configuration 一节给出了其推荐内容：TZ 时区（默认 America/Los_Angeles，compose 中以 ${TZ:-America/Los_Angeles} 引用）、可选的 n8n Basic Auth（N8N_BASIC_AUTH_ACTIVE / USER / PASSWORD）以及 Agent Zero 用到的 OPENAI_API_KEY、ANTHROPIC_API_KEY。

安全提醒（速查表原文要点）

• 默认仅 localhost 可访问，可安全用于本地；
• 未经安全加固（反向代理 + Basic Auth）不要暴露到公网；
• 保持 Docker 版本更新；不要外泄 .env 文件；启用认证时使用强密码。

启动前检查清单（System Check）

• [ ] Docker Desktop 已安装
• [ ] Docker Desktop 正在运行（鲸鱼图标可见）
• [ ] 磁盘剩余空间至少 10 GB
• [ ] 网络连接正常
• [ ] 当前终端位于 ai-stack 目录内

成功判定指标（Success Indicators）

• 任务栏/菜单栏出现鲸鱼图标；
• 终端打印 "🎉 AI Stack is running!"；
• 三个 URL（5678 / 50080 / 8188）均能在浏览器打开；
• n8n 显示欢迎页、ComfyUI 显示节点界面、Agent Zero 显示聊天界面。

学习资源

速查表按服务列出了延伸学习的入口（此处仅保留资源名称，不附外部链接）：n8n 官方文档与社区论坛；ComfyUI 的 GitHub 仓库、Wiki 与 Reddit 社区；Agent Zero 的 GitHub 仓库 README。仓库内配套的阅读路径为：ai-stack/QUICK-START.md（三步上手）→ ai-stack/EASY-INSTALL.md（新手图文安装）→ ai-stack/SUMMARY.md（体系概览）→ ai-stack/README.md（完整文档）→ ai-stack/INDEX.md（总索引）。

速查表使用建议：何时查哪份文档

CHEAT-SHEET 的定位是「打印出来贴在手边」的一页式索引。结合 ai-stack/INDEX.md 的分层指引，日常检索路径可以固化为：

场景	去哪查
"某个命令怎么敲？"	本文（即 ai-stack/CHEAT-SHEET.md）
"装不上 / 起不来？"	ai-stack/TROUBLESHOOTING.md
"想理解整个栈怎么工作？"	ai-stack/SUMMARY.md → ai-stack/README.md
"要改端口 / 镜像 / 挂载？"	ai-stack/docker-compose.yml
"怎么让 n8n 自动出图？"	ai-stack/workflows/comfyui-image-generation.json 与 ai-stack/workflows/comfyui-simple-test.json

需要强调的是适用前提：本文所有命令与路径均基于当前仓库 ai-stack/ 目录的实际文件，假设你已安装 Docker Desktop（或 Linux 环境下的 Docker Engine + Compose v2），且命令都在解压后的 ai-stack 目录内执行；GPU 加速仅对 NVIDIA 显卡 + NVIDIA Container Toolkit 有效，Mac 环境会自动回退 CPU 模式。按这套速查 + 源码对照的方式操作，即可在不离开终端与浏览器的情况下完成 AI Stack 的日常运维、API 联调与故障恢复。