n8n-workflows ai-stack 本地 AI 自动化栈排障指南：从 Docker 环境、端口占用到 GPU 检测的十类故障全解

n8n-workflows ai-stack 本地 AI 自动化栈排障指南：从 Docker 环境、端口占用到 GPU 检测的十类故障全解

【免费下载链接】n8n-workflowsall of the workflows of n8n i could find (also from the site itself)项目地址: https://gitcode.com/GitHub_Trending/n8nworkflo/n8n-workflows

本文基于 ai-stack/TROUBLESHOOTING.md 整理，面向使用 ai-stack 一键部署 n8n + Agent Zero + ComfyUI 组合的开发者，系统讲解启动脚本每一步前置检查的报错来源、十类典型故障的判定与修复命令，并结合 start.sh、start.ps1 与 docker-compose.yml 的源码实现说明每条错误信息的触发机制，帮助你在服务起不来、端口冲突、GPU 未识别等场景下快速定位并恢复本地 AI 自动化栈。

故障链条：这些报错是从哪里来的

ai-stack 子目录把 n8n（流程编排）、Agent Zero（AI 代理运行时）、ComfyUI（图像生成）三个服务打包成一条命令启动的本地栈，核心文件为：

排障文档中出现的所有✗错误提示，都来自这两个脚本的报错输出函数：start.sh中的 print_error（打印✗前缀）和start.ps1中的 Write-Error。因此，只要对照报错文本，就能精确反推脚本停在了哪一步检查上。

启动前脚本会依次执行四级前置检查，这构成了排障的基本坐标系（以 start.sh 为例）：

1. docker --version—— 检测 Docker 是否安装（Windows 脚本对应 start.ps1）；
2. docker info—— 检测 Docker 守护进程是否在运行（start.sh）；
3. docker compose version—— 检测 Compose 插件是否可用（start.sh）；
4. nvidia-smi --query-gpu=name—— 可选的 GPU 探测，仅打印提示不阻断流程（start.sh）。

检查通过后，脚本创建data/与shared/目录结构、依次docker pull三个镜像，最后执行docker compose up -d并sleep 10后打印状态与访问地址（start.sh）。理解了这条执行链，下面每个故障的触发点都能对号入座。

三个服务的默认端口与容器名（来自 docker-compose.yml），是后文状态排查的判断依据：

十类常见故障逐一解析

故障 1：Docker 未安装（"Docker is not installed"）

现象：启动脚本输出

✗ Docker is not installed or not in PATH

原理：start.sh用command -v docker判断 Docker 是否存在，不存在则打印错误并exit 1（start.sh）；Windows 脚本则是docker --version进入 try/catch 后捕获异常（start.ps1），Windows 侧的报错文案正是文档中的 "Docker is not installed or not in PATH"。

修复步骤（继承自 TROUBLESHOOTING.md）：

1. 从 Docker 官方下载页安装 Docker Desktop（Windows 与 Mac 均为同一官方安装包）；
2. 重启计算机——这一步不可省略，Docker Desktop 的 WSL 后端/虚拟引擎需要重启后才进入 PATH；
3. 重新运行.\start.ps1或./start.sh。

故障 2：Docker 守护进程未运行（"Docker daemon is not running"）

现象：

✗ Docker daemon is not running

原理：docker info需要与守护进程通信，未启动时返回失败，脚本据此报错（start.sh、start.ps1）。注意区分：Docker 已安装但没运行，是比故障 1 更常见的情况。

修复步骤：

1. 寻找 Docker 鲸鱼图标——Windows 在系统托盘（右下角），Mac 在菜单栏（右上角）；
2. 若看不到图标：从应用列表启动 Docker Desktop，等待约 30 秒；
3. 鲸鱼图标稳定后重新运行启动脚本。

故障 3：macOS 上 "Permission denied"

现象：执行./start.sh时报Permission denied。

原理：脚本首行是#!/bin/bashshebang（start.sh），直接执行要求文件具备可执行位；从压缩包解出的脚本通常丢失该权限位。

修复步骤：

cd <项目根目录>/ai-stack chmod +x start.sh ./start.sh

每行输入后按回车。chmod +x之后即可在当前目录直接运行。

故障 4：端口 5678 已被占用（"Port already in use"）

现象：

Error: Port 5678 is already in use

原理：n8n 的端口映射写死为"5678:5678"（docker-compose.yml），一旦宿主机 5678 被占用，docker compose up -d即失败。占用的来源通常是：之前未完全停掉的旧栈、另一个 n8n 实例，或其他监听 5678 的程序。

修复方案（按优先级）：

• 方案一：停止占用程序——关闭浏览器及其他后台程序后重试（文档给出的保守做法）；
• 方案二：重启计算机——重启后先打开 Docker Desktop 再试；
• 方案三：停掉旧栈再启动：

# Windows .\start.ps1 -Stop

# Mac ./start.sh --stop

然后重新执行.\start.ps1/./start.sh。-Stop/--stop内部对应docker compose down（start.sh），会释放容器占用的端口。

补充：如果 5678 是长期被占用的服务，可以按 ai-stack/README.md 的说明修改 docker-compose.yml 中 n8n 的 ports 映射为"新端口:5678"形式，并同步调整WEBHOOK_URL。

故障 5：Windows 下 PowerShell 窗口一闪而过

现象：双击start.ps1后 PowerShell 窗口一秒内打开又关闭，看不到任何报错。

原理：脚本开头设置了$ErrorActionPreference = "Stop"（start.ps1），任何命令失败都会立即抛异常并以非零码退出；若执行策略（ExecutionPolicy）禁止运行本地脚本，窗口会在打印错误前就被关闭。

修复步骤：

1. 以管理员身份打开 PowerShell：开始菜单输入 "PowerShell"，右键 "Windows PowerShell"，选择 "Run as administrator"，询问时点 "Yes"；
2. 执行：

Set-ExecutionPolicy RemoteSigned

3. 输入Y回车确认；
4. 重新运行.\start.ps1，此时窗口会停留并完整显示报错信息。

故障 6：无法访问 localhost:5678（"Cannot connect"）

现象：浏览器提示 "This site can't be reached" 或 "Connection refused"。

修复步骤：

1. 先等待 2 分钟——这一点有源码依据：n8n 容器健康检查的start_period为 30 秒（docker-compose.yml），ComfyUI 更慢，start_period为 60 秒（docker-compose.yml），叠加启动脚本自身的sleep 10（start.sh），前 1~2 分钟服务尚未就绪属正常现象；
2. 确认 Docker 正在运行（鲸鱼图标）；
3. 检查栈状态：

# Windows .\start.ps1 -Status

# Mac ./start.sh --status

两者内部都是docker compose ps（start.sh）。

4. 三个容器ai-stack-n8n、ai-stack-agent-zero、ai-stack-comfyui都应显示Up；
5. 若任何容器显示Exited或Error：先停止（.\start.ps1 -Stop或./start.sh --stop），再重新启动（.\start.ps1或./start.sh）。

故障 7：磁盘空间不足（"No space left on device"）

现象：

Error: No space left on device

修复步骤：

1. 清理磁盘：删除无用文件、清空回收站/废纸篓，至少保留 10 GB 可用空间（三个镜像加上 ComfyUI 模型下载，首装体积可观）；
2. 清理 Docker 悬空资源：

docker system prune -a

按提示输入y确认。该命令会移除停止的容器、未使用的网络和悬空镜像，是释放 Docker 存储最直接的手段；

3. 重新运行启动脚本。

故障 8：镜像拉取非常缓慢

现象：Pulling images...阶段超过 30 分钟。

说明与应对：

1. 先确认网络连通性；
2. 首次下载体积约 5~10 GB，耐心等待——Docker 会缓存已下载的层，第二次启动会明显更快；
3. 本地已有镜像时可跳过拉取：

# Windows .\start.ps1 -NoPull

# Mac ./start.sh --no-pull

源码细节：拉取逻辑在 start.sh 与 start.ps1 中，由--no-pull/-NoPull参数控制（参数解析见 start.sh）。从源码结构看有一个值得注意的差异：start.sh与docker-compose.yml使用的 ComfyUI 镜像为aidockorg/comfyui-cuda:latest（docker-compose.yml），而 Windows 脚本拉取的是yanwk/comfyui-boot:latest（start.ps1）。若在 Windows 上用-NoPull跳过下载后容器起不来，可先手动执行docker pull aidockorg/comfyui-cuda:latest补齐与 Compose 文件一致的镜像。

故障 9：有 GPU 却提示 "GPU not detected"

现象：

ℹ No NVIDIA GPU detected

原理：脚本通过nvidia-smi --query-gpu=name探测 GPU（start.sh），探测失败仅打印该蓝色ℹ提示，不会中断启动。Compose 侧的 GPU 支持依赖 NVIDIA 驱动容器设备预留（docker-compose.yml 中deploy.resources.reservations.devices声明driver: nvidia, count: all, capabilities: [gpu]），缺少 NVIDIA Container Toolkit 时该预留会失败。

修复步骤：

• Windows（NVIDIA 显卡）：依次完成 ① 安装/更新 NVIDIA 显卡驱动（NVIDIA 官方下载页）；② 安装 NVIDIA Container Toolkit；③ 重启 Docker Desktop；④ 重新运行启动脚本。验证命令（来自 README.md）：

docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

• Mac：Docker 环境不支持 NVIDIA GPU，栈会自动落入 CPU 模式，速度较慢但功能完整；
• 没有 NVIDIA 显卡：显式指定 CPU 模式运行即可：

# Windows .\start.ps1 -CPU

# Mac ./start.sh --cpu

源码细节：-CPU/--cpu会让脚本在 ComfyUI 无 GPU 可用时打印 "Starting in CPU mode" 并导出COMFYUI_ARGS="--cpu"（start.sh、start.ps1）。从源码结构看，Compose 文件里另有一个被注释掉的comfyui-cpu服务变体（镜像frdel/comfyui-docker:latest，CLI_ARGS追加--cpu，挂在cpu-onlyprofile 下，docker-compose.yml），其CLI_ARGS为写死值、并未引用COMFYUI_ARGS变量。可以推断：--cpu标志主要控制脚本层面的行为与提示；若需要彻底切换到 CPU 镜像，还需手动启用该注释块中的服务定义。

故障 10：一切看似正常但就是不能用——"核选项"

当状态显示正常、端口也不冲突，但流程仍跑不通时，执行一次彻底重置：

Windows：

# 停止全部服务 .\start.ps1 -Stop # 删除所有容器和数据 docker compose down -v # 全新启动 .\start.ps1

Mac：

# 停止全部服务 ./start.sh --stop # 删除所有容器和数据 docker compose down -v # 全新启动 ./start.sh

警告：这会清空数据、从零开始。一个由 Compose 文件结构可以确认的细节：-v会删除 docker-compose.yml 中声明的命名卷（n8n-data、agent-zero-data等），但./data/n8n、./data/agent-zero、./shared是宿主目录绑定挂载（docker-compose.yml），down -v不会自动删除其中的文件——如果你希望"完全干净"，需自行清理这些目录下的内容。

系统性自检清单

执行完上述针对性修复后仍无果时，按 TROUBLESHOOTING.md 的基础检查表逐项核对：

• 是否已安装 Docker Desktop？
• Docker Desktop 是否正在运行（看到鲸鱼图标）？
• 是否有稳定的网络连接？
• 磁盘是否有至少 10 GB 可用空间？
• 安装 Docker 后是否重启过计算机？
• 当前终端是否位于ai-stack目录（脚本依赖当前目录解析 compose 文件）？

获取日志与求助技巧

查看日志的命令在两个平台上一致，内部均为docker compose logs -f（start.sh、start.ps1）：

# Windows .\start.ps1 -Logs

# Mac ./start.sh --logs

出现红色错误信息时，截图保存后再求助，比文字转述更容易定位。按文档建议，求助时请提供四要素：

1. 操作系统（Windows 10/11、Mac 等）；
2. 你正在尝试做什么；
3. 精确的错误信息（截图）；
4. 你已经尝试过的操作。

快速命令速查表

继承自 TROUBLESHOOTING.md 的完整命令对照：

此外，熟悉 Docker Compose 的读者也可以绕过脚本直接操作（来自 README.md）：

docker compose up -d # 启动 docker compose down # 停止 docker compose logs -f # 查看日志 docker compose ps # 状态 docker compose restart n8n # 重启单个服务

start.sh还支持短参数形式（start.sh）：-n（no-pull）、-c（cpu）、-s（stop）、-l（logs），--help可查看完整帮助。

相关文档与源码入口

排障之外的配套文档（同目录内，按 INDEX.md 导航）：

• ai-stack/QUICK-START.md：三步上手指南
• ai-stack/EASY-INSTALL.md：Windows/Mac 分步安装
• ai-stack/UBUNTU-INSTALL.md：Ubuntu/Linux 安装
• ai-stack/CHEAT-SHEET.md：日常操作速查
• ai-stack/SUMMARY.md：栈总览与学习路径
• ai-stack/README.md：完整文档，含 ComfyUI API 参考与内置工作流（ai-stack/workflows/comfyui-image-generation.json、ai-stack/workflows/comfyui-simple-test.json）的调用示例

排查"服务起来但功能不通"类问题时，README 中的"n8n 连不上 ComfyUI"一节值得回看：容器间必须使用 Docker 内网名comfyui（如http://comfyui:8188）而非localhost，这是跨服务调用失败的高频原因，属于排障文档未展开但 Compose 网络配置（docker-compose.yml）能够印证的实现细节。

【免费下载链接】n8n-workflowsall of the workflows of n8n i could find (also from the site itself)项目地址: https://gitcode.com/GitHub_Trending/n8nworkflo/n8n-workflows