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

本文基于 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（图像生成）三个服务打包成一条命令启动的本地栈，核心文件为：

文件	职责
ai-stack/docker-compose.yml	定义三个服务、端口映射、健康检查、GPU 资源预留
ai-stack/start.sh	Linux/macOS 启动脚本：环境检查、建目录、拉镜像、起容器
ai-stack/start.ps1	Windows PowerShell 启动脚本，参数与 start.sh 一一对应

排障文档中出现的所有 ✗ 错误提示，都来自这两个脚本的报错输出函数：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），是后文状态排查的判断依据：

服务	容器名	宿主端口	访问地址
n8n	ai-stack-n8n	5678	http://localhost:5678
Agent Zero	ai-stack-agent-zero	50080	http://localhost:50080
ComfyUI	ai-stack-comfyui	8188	http://localhost:8188

十类常见故障逐一解析

故障 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/bash shebang（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-only profile 下，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 的完整命令对照：

操作	Windows	Mac/Linux
启动	.\start.ps1	./start.sh
停止	.\start.ps1 -Stop	./start.sh --stop
查看状态	.\start.ps1 -Status	./start.sh --status
查看日志	.\start.ps1 -Logs	./start.sh --logs
CPU 模式	.\start.ps1 -CPU	./start.sh --cpu
跳过镜像下载	.\start.ps1 -NoPull	./start.sh --no-pull

此外，熟悉 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）能够印证的实现细节。