n8n-workflows 的 ai-stack 在 Ubuntu 上怎么装 Docker 并用 start.sh 一键启动？

n8n-workflows 仓库里的 ai-stack 目录是一套可一键部署的本地 AI 自动化栈：通过 docker compose 同时运行 n8n（端口 5678）、Agent Zero（端口 50080）和 ComfyUI（端口 8188）三个容器。本文面向 Ubuntu 用户，目标是在一台新机器上装好 Docker，然后进入 ai-stack 目录用 start.sh 把这三个服务一次性拉起来，并在浏览器里确认全部可访问。

按 UBUNTU-INSTALL.md 的说明，环境要求如下：

模式	系统	内存	磁盘	GPU
最低配置（CPU 模式）	Ubuntu 20.04 或更新	8 GB	20 GB 可用空间	任意现代 CPU
推荐配置（GPU 模式）	Ubuntu 20.04 或更新	16 GB	50 GB 可用空间	NVIDIA GPU，6 GB 以上显存，已装 NVIDIA 驱动

没有 NVIDIA GPU 不是阻塞项：start.sh 会用 nvidia-smi 自动探测，检测不到时提示可以走 CPU 模式。

第一步：检查并安装 Docker

打开终端（文档建议 Ctrl + Alt + T），先确认 Docker 是否已装：

docker --version

如果输出了版本号，跳过本步；否则按下面的顺序执行。这些命令使用 sudo，会向系统添加 Docker 官方软件源并安装 docker-ce、docker-ce-cli、containerd.io 和 docker-compose-plugin 包，最后把当前用户加入 docker 组，使之后运行 docker 命令不再需要 sudo：

# Update package list
sudo apt update

# Install required packages
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package list again
sudo apt update

# Install Docker
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add your user to docker group (so you don't need sudo)
sudo usermod -aG docker $USER

# Apply the new group membership
newgrp docker

装完后用这两条命令验证，两者都应输出版本号：

docker --version
docker compose version

start.sh 启动时会依次检查 Docker 是否安装、daemon 是否在运行、docker compose 是否可用，任一检查失败脚本都会直接报错退出，所以这三项都要通过。

第二步：获取项目并进入 ai-stack 目录

# Install git if you don't have it
sudo apt install -y git

# Clone the repository
git clone https://gitcode.com/GitHub_Trending/n8nworkflo/n8n-workflows.git

# Go to the ai-stack folder
cd n8n-workflows/ai-stack

克隆地址请按你实际可用的镜像源替换（UBUNTU-INSTALL.md 原文给出的克隆命令指向 GitHub 地址，该文档同时提供了一个用 wget 下载 ZIP 包的 Option B，可对照原文选用）。本文以 git clone 为主路径，后续所有命令都在 n8n-workflows/ai-stack 目录下执行。

第三步：用 start.sh 一键启动

chmod +x start.sh
./start.sh

结合 start.sh 脚本源码和文档说明，执行时它会依次做这些事：

1. 检查 Docker 安装、Docker daemon 运行状态和 Docker Compose 是否可用；
2. 用 nvidia-smi 检测 NVIDIA GPU，未检测到时提示可用 --cpu 参数走 CPU 模式；
3. 创建 data/n8n、data/agent-zero 以及 shared/comfyui/models、shared/comfyui/output 等目录结构；
4. 拉取三个镜像：n8nio/n8n:latest、frdel/agent-zero-run:latest、aidockorg/comfyui-cuda:latest。文档说明首次拉取大约需要 5–10 分钟，首次下载量约 5–10 GB；
5. 执行 docker compose up -d 启动容器，等待约 10 秒后打印 docker compose ps 的状态表。

启动成功时终端会输出：

🎉 AI Stack is running!

随后脚本会打印三个访问地址和常用命令，并提示共享目录位置（./shared，ComfyUI 模型目录为 ./shared/comfyui/models）。

第四步：验证三个服务都已起来

在终端运行状态检查：

./start.sh --status

它等价于 docker compose ps。按 TROUBLESHOOTING.md 的说明，应能看到三个容器（ai-stack-n8n、ai-stack-agent-zero、ai-stack-comfyui）均显示 "Up"；若有容器显示 "Exited" 或 "Error"，先 ./start.sh --stop 再重新 ./start.sh，仍不行时用 ./start.sh --logs 查看容器日志。

然后在浏览器中依次打开：

服务	地址	预期
n8n	http://localhost:5678	显示欢迎页（welcome screen）
ComfyUI	http://localhost:8188	显示 ComfyUI 界面
Agent Zero	http://localhost:50080	显示聊天界面

UBUNTU-INSTALL.md 末尾的 Success Checklist 即以此为准：三个 URL 均能打开、n8n 显示欢迎页、ComfyUI 显示界面、Agent Zero 显示聊天框。另外 docker-compose.yml 中 n8n 与 ComfyUI 配置了 healthcheck（分别探测容器内 /healthz 和 /system_stats），docker compose ps 中的健康状态也反映这两项检查的结果。

日常操作命令

启动之后的常规操作都在 ai-stack 目录下用 start.sh 完成（参数已核对脚本源码，--help 可查看全部选项）：

./start.sh               # 启动
./start.sh --stop        # 停止（执行 docker compose down）
./start.sh --logs        # 查看容器日志
./start.sh --status      # 查看状态（执行 docker compose ps）
./start.sh --cpu         # 强制 ComfyUI 走 CPU 模式
./start.sh --no-pull     # 启动时跳过镜像拉取，镜像已存在时使用

Ubuntu 下的常见问题排查

以下现象和解法均来自 UBUNTU-INSTALL.md 的 Ubuntu-Specific Troubleshooting 一节。

运行 docker 报 "Permission denied"

当前用户尚未加入 docker 组，重新执行组配置并让会话生效：

sudo usermod -aG docker $USER
newgrp docker
./start.sh

文档同时说明，也可以退出登录后重新登录来应用新的组身份。

报 "Cannot connect to Docker daemon"

Docker 服务未运行，启动并设为开机自启，再用 status 确认：

sudo systemctl start docker
sudo systemctl enable docker
sudo systemctl status docker

报 "Port already in use"

先用 lsof 找出占用端口的进程，再决定如何处理。kill -9 PID 中的 PID 需替换为上一条命令查到的实际进程号，kill -9 会强制终止该进程，执行前先确认 PID 对应的确实是你要停掉的服务：

sudo lsof -i :5678
sudo lsof -i :8188
sudo lsof -i :50080

# Kill the process (replace PID with actual number)
sudo kill -9 PID

磁盘空间不足

先查看空间，再按文档给出的方式清理。注意 docker system prune -a 会移除未被使用的 Docker 资源，执行前确认没有还需要保留的悬空镜像或未使用容器：

df -h
docker system prune -a
sudo apt clean
sudo apt autoremove

NVIDIA GPU 未被检测

有 GPU 但脚本提示未检测到时，文档给出的处理顺序是安装驱动、安装 NVIDIA Container Toolkit、重启 Docker，最后用容器实测：

sudo ubuntu-drivers autoinstall

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt update
sudo apt install -y nvidia-container-toolkit

sudo systemctl restart docker

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

最后一条命令能打印 GPU 信息，说明容器内可用 GPU。

可选配置与完整重置

如果要从局域网内其他电脑访问这三个服务，文档把防火墙放行列为可选项：

sudo ufw allow 5678/tcp
sudo ufw allow 8188/tcp
sudo ufw allow 50080/tcp
sudo ufw status

文档另给了一条"完整重置"路径。它会删除全部本地数据（data/ 和 shared/ 下的工作流、凭据、模型与生成结果），仅在确认放弃现有数据时使用：

./start.sh --stop
docker compose down -v
rm -rf data/ shared/
./start.sh

下一步

栈起来后，README.md 给出的第一个验证动作是导入随仓库自带的测试工作流 ai-stack/workflows/comfyui-simple-test.json：在 n8n 中导入并激活后访问 http://localhost:5678/webhook/comfyui-status，应返回 ComfyUI 的 system stats，以此确认 n8n 与 ComfyUI 之间的连通性。日常命令速查见 ai-stack/CHEAT-SHEET.md，遇到栈本身的问题（镜像拉取慢、GPU 未识别、端口冲突等）可继续查阅 ai-stack/TROUBLESHOOTING.md。