ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

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

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 ZeroAI 代理运行时、ComfyUI图像生成三个服务打包成一条命令启动的本地栈核心文件为文件职责ai-stack/docker-compose.yml定义三个服务、端口映射、健康检查、GPU 资源预留ai-stack/start.shLinux/macOS 启动脚本环境检查、建目录、拉镜像、起容器ai-stack/start.ps1Windows PowerShell 启动脚本参数与 start.sh 一一对应排障文档中出现的所有✗错误提示都来自这两个脚本的报错输出函数start.sh中的 print_error打印✗前缀和start.ps1中的 Write-Error。因此只要对照报错文本就能精确反推脚本停在了哪一步检查上。启动前脚本会依次执行四级前置检查这构成了排障的基本坐标系以 start.sh 为例docker --version—— 检测 Docker 是否安装Windows 脚本对应 start.ps1docker info—— 检测 Docker 守护进程是否在运行start.shdocker compose version—— 检测 Compose 插件是否可用start.shnvidia-smi --query-gpuname—— 可选的 GPU 探测仅打印提示不阻断流程start.sh。检查通过后脚本创建data/与shared/目录结构、依次docker pull三个镜像最后执行docker compose up -d并sleep 10后打印状态与访问地址start.sh。理解了这条执行链下面每个故障的触发点都能对号入座。三个服务的默认端口与容器名来自 docker-compose.yml是后文状态排查的判断依据服务容器名宿主端口访问地址n8nai-stack-n8n5678http://localhost:5678Agent Zeroai-stack-agent-zero50080http://localhost:50080ComfyUIai-stack-comfyui8188http://localhost:8188十类常见故障逐一解析故障 1Docker 未安装Docker is not installed现象启动脚本输出✗ Docker is not installed or not in PATH原理start.sh用command -v docker判断 Docker 是否存在不存在则打印错误并exit 1start.shWindows 脚本则是docker --version进入 try/catch 后捕获异常start.ps1Windows 侧的报错文案正是文档中的 Docker is not installed or not in PATH。修复步骤继承自 TROUBLESHOOTING.md从 Docker 官方下载页安装 Docker DesktopWindows 与 Mac 均为同一官方安装包重启计算机——这一步不可省略Docker Desktop 的 WSL 后端/虚拟引擎需要重启后才进入 PATH重新运行.\start.ps1或./start.sh。故障 2Docker 守护进程未运行Docker daemon is not running现象✗ Docker daemon is not running原理docker info需要与守护进程通信未启动时返回失败脚本据此报错start.sh、start.ps1。注意区分Docker 已安装但没运行是比故障 1 更常见的情况。修复步骤寻找 Docker 鲸鱼图标——Windows 在系统托盘右下角Mac 在菜单栏右上角若看不到图标从应用列表启动 Docker Desktop等待约 30 秒鲸鱼图标稳定后重新运行启动脚本。故障 3macOS 上 Permission denied现象执行./start.sh时报Permission denied。原理脚本首行是#!/bin/bashshebangstart.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:5678docker-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 downstart.sh会释放容器占用的端口。补充如果 5678 是长期被占用的服务可以按 ai-stack/README.md 的说明修改 docker-compose.yml 中 n8n 的 ports 映射为新端口:5678形式并同步调整WEBHOOK_URL。故障 5Windows 下 PowerShell 窗口一闪而过现象双击start.ps1后 PowerShell 窗口一秒内打开又关闭看不到任何报错。原理脚本开头设置了$ErrorActionPreference Stopstart.ps1任何命令失败都会立即抛异常并以非零码退出若执行策略ExecutionPolicy禁止运行本地脚本窗口会在打印错误前就被关闭。修复步骤以管理员身份打开 PowerShell开始菜单输入 PowerShell右键 Windows PowerShell选择 Run as administrator询问时点 Yes执行Set-ExecutionPolicy RemoteSigned输入Y回车确认重新运行.\start.ps1此时窗口会停留并完整显示报错信息。故障 6无法访问 localhost:5678Cannot connect现象浏览器提示 This site cant be reached 或 Connection refused。修复步骤先等待 2 分钟——这一点有源码依据n8n 容器健康检查的start_period为 30 秒docker-compose.ymlComfyUI 更慢start_period为 60 秒docker-compose.yml叠加启动脚本自身的sleep 10start.sh前 1~2 分钟服务尚未就绪属正常现象确认 Docker 正在运行鲸鱼图标检查栈状态# Windows .\start.ps1 -Status# Mac ./start.sh --status两者内部都是docker compose psstart.sh。三个容器ai-stack-n8n、ai-stack-agent-zero、ai-stack-comfyui都应显示Up若任何容器显示Exited或Error先停止.\start.ps1 -Stop或./start.sh --stop再重新启动.\start.ps1或./start.sh。故障 7磁盘空间不足No space left on device现象Error: No space left on device修复步骤清理磁盘删除无用文件、清空回收站/废纸篓至少保留 10 GB 可用空间三个镜像加上 ComfyUI 模型下载首装体积可观清理 Docker 悬空资源docker system prune -a按提示输入y确认。该命令会移除停止的容器、未使用的网络和悬空镜像是释放 Docker 存储最直接的手段重新运行启动脚本。故障 8镜像拉取非常缓慢现象Pulling images...阶段超过 30 分钟。说明与应对先确认网络连通性首次下载体积约 5~10 GB耐心等待——Docker 会缓存已下载的层第二次启动会明显更快本地已有镜像时可跳过拉取# 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:latestdocker-compose.yml而 Windows 脚本拉取的是yanwk/comfyui-boot:lateststart.ps1。若在 Windows 上用-NoPull跳过下载后容器起不来可先手动执行docker pull aidockorg/comfyui-cuda:latest补齐与 Compose 文件一致的镜像。故障 9有 GPU 却提示 GPU not detected现象ℹ No NVIDIA GPU detected原理脚本通过nvidia-smi --query-gpuname探测 GPUstart.sh探测失败仅打印该蓝色ℹ提示不会中断启动。Compose 侧的 GPU 支持依赖 NVIDIA 驱动容器设备预留docker-compose.yml 中deploy.resources.reservations.devices声明driver: nvidia, count: all, capabilities: [gpu]缺少 NVIDIA Container Toolkit 时该预留会失败。修复步骤WindowsNVIDIA 显卡依次完成 ① 安装/更新 NVIDIA 显卡驱动NVIDIA 官方下载页② 安装 NVIDIA Container Toolkit③ 重启 Docker Desktop④ 重新运行启动脚本。验证命令来自 README.mddocker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smiMacDocker 环境不支持 NVIDIA GPU栈会自动落入 CPU 模式速度较慢但功能完整没有 NVIDIA 显卡显式指定 CPU 模式运行即可# Windows .\start.ps1 -CPU# Mac ./start.sh --cpu源码细节-CPU/--cpu会让脚本在 ComfyUI 无 GPU 可用时打印 Starting in CPU mode 并导出COMFYUI_ARGS--cpustart.sh、start.ps1。从源码结构看Compose 文件里另有一个被注释掉的comfyui-cpu服务变体镜像frdel/comfyui-docker:latestCLI_ARGS追加--cpu挂在cpu-onlyprofile 下docker-compose.yml其CLI_ARGS为写死值、并未引用COMFYUI_ARGS变量。可以推断--cpu标志主要控制脚本层面的行为与提示若需要彻底切换到 CPU 镜像还需手动启用该注释块中的服务定义。故障 10一切看似正常但就是不能用——核选项当状态显示正常、端口也不冲突但流程仍跑不通时执行一次彻底重置Windows# 停止全部服务 .\start.ps1 -Stop # 删除所有容器和数据 docker compose down -v # 全新启动 .\start.ps1Mac# 停止全部服务 ./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.ymldown -v不会自动删除其中的文件——如果你希望完全干净需自行清理这些目录下的内容。系统性自检清单执行完上述针对性修复后仍无果时按 TROUBLESHOOTING.md 的基础检查表逐项核对是否已安装 Docker DesktopDocker Desktop 是否正在运行看到鲸鱼图标是否有稳定的网络连接磁盘是否有至少 10 GB 可用空间安装 Docker 后是否重启过计算机当前终端是否位于ai-stack目录脚本依赖当前目录解析 compose 文件获取日志与求助技巧查看日志的命令在两个平台上一致内部均为docker compose logs -fstart.sh、start.ps1# Windows .\start.ps1 -Logs# Mac ./start.sh --logs出现红色错误信息时截图保存后再求助比文字转述更容易定位。按文档建议求助时请提供四要素操作系统Windows 10/11、Mac 等你正在尝试做什么精确的错误信息截图你已经尝试过的操作。快速命令速查表继承自 TROUBLESHOOTING.md 的完整命令对照操作WindowsMac/Linux启动.\start.ps1./start.sh停止.\start.ps1 -Stop./start.sh --stop查看状态.\start.ps1 -Status./start.sh --status查看日志.\start.ps1 -Logs./start.sh --logsCPU 模式.\start.ps1 -CPU./start.sh --cpu跳过镜像下载.\start.ps1 -NoPull./start.sh --no-pull此外熟悉 Docker Compose 的读者也可以绕过脚本直接操作来自 README.mddocker compose up -d # 启动 docker compose down # 停止 docker compose logs -f # 查看日志 docker compose ps # 状态 docker compose restart n8n # 重启单个服务start.sh还支持短参数形式start.sh-nno-pull、-ccpu、-sstop、-llogs--help可查看完整帮助。相关文档与源码入口排障之外的配套文档同目录内按 INDEX.md 导航ai-stack/QUICK-START.md三步上手指南ai-stack/EASY-INSTALL.mdWindows/Mac 分步安装ai-stack/UBUNTU-INSTALL.mdUbuntu/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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表