hello-agents 附录实践基于 Docker 的 n8n 本地安装、启动与基础操作指南【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents本篇是 hello-agents 教程Additional-Chapter附录文档的成文版围绕 n8n 本地安装指南 展开完整讲解如何用 Docker 在本地一键部署 n8n 工作流平台从安装 Docker Desktop、拉取并启动 n8n 容器到理解每一条命令参数的作用最后上手 n8n 工作流的三个核心基础功能。读完本篇你将能够独立在 Windows/macOS/Linux 上部署一个带数据持久化的本地 n8n 环境并顺利接入教程第五章的 n8n 智能体实战案例。为什么要在本地安装 n8n在 hello-agents 的 docs/README.md 中教程将 Agent 构建分为两派一派是 Dify、Coze、n8n 这类软件工程类流程驱动平台LLM 作为数据处理后端另一派是 AI 原生的 Agent。n8n 正是前者中最具代表性的通用工作流自动化平台也是教程 第五章 基于低代码平台的智能体搭建 中平台四的主角。第五章 5.5 节明确了 n8n 的核心概念——节点Node与工作流Workflow节点是工作流中执行具体操作的最小单元分为触发节点工作流的起点如收到新 Gmail 邮件时与常规节点执行具体数据处理工作流则由多个节点连接而成数据以结构化 JSON 格式在节点间传递。5.5.2 节搭建智能邮件助手案例中教程原文写道关于n8n的环境配置和最基础的使用在项目的Additional-Chapter文件夹下制作了文档——本文档就是该指引指向的环境配置部分其目标是让读者在进入 AI Agent 节点、知识库、Gmail 集成等高级玩法之前先拥有一个稳定可用的本地 n8n 运行环境。之所以选择 Docker 而非 npm 全局安装npm install n8n -g原文给出的理由很直接Docker 方式最稳定并且最利于持续探索 n8n 的使用。镜像把 n8n 及其全部依赖封闭在容器内版本可复现、升级简单、与宿主机环境零冲突这对一个会频繁更新节点与知识库的探索型学习环境尤为关键。第一步安装 Docker Desktop打开 Docker 官网docker.com根据当前终端设备选择对应的安装包下载。原文档以Windows作为演示平台。安装完成后建议切换 Docker 的镜像/数据存放磁盘路径。因为容器镜像体积通常较大Windows 用户尤其应尽量避免把数据放在 C 盘Docker Desktop 可在 设置 → Resources 中调整镜像存储位置。安装并启动 Docker Desktop确认命令行中docker命令可用如docker version能正常输出说明守护进程已就绪。第二步创建数据卷并启动 n8n 容器打开终端Windows 下为 PowerShell/CMDmacOS/Linux 下为 Terminal执行原文档给出的两条核心命令见 N8N_INSTALL_GUIDE.mddocker volume create n8n_data docker run -d --restart unless-stopped --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n n8nio/n8n这两条命令是整个部署的精髓逐参数拆解如下命令/参数作用说明docker volume create n8n_data创建一个名为n8n_data的命名数据卷named volume用于持久化保存 n8n 的工作流、凭据、环境变量等数据与容器生命周期解耦docker run基于指定镜像创建一个新容器并启动-d后台detached模式运行容器在后台持续提供服务不占用当前终端--restart unless-stopped重启策略宿主机或 Docker 重启后自动拉起容器只有手动docker stop后才不再自动启动--name n8n为容器指定名称n8n便于后续docker logs n8n、docker stop n8n等管理操作-p 5678:5678端口映射宿主机的 5678 端口 → 容器的 5678 端口n8n Web UI 的默认监听端口-v n8n_data:/home/node/.n8n将命名卷n8n_data挂载到容器内 n8n 的数据目录/home/node/.n8n。n8n 镜像内以node用户运行该目录是它的家目录数据区工作流定义、执行历史、加密密钥等均落在此处n8nio/n8n官方 n8n 镜像。首次执行时 Docker 会自动拉取该镜像体积较大请耐心等待这里有两个值得注意的设计点数据卷与容器的生命周期分离直接把数据写在容器文件系统里容器删除后数据即丢失。通过-v n8n_data:/home/node/.n8n挂载命名卷即使未来docker rm重建容器只要把同一个卷重新挂载回去所有工作流与配置都能原样恢复——这正是最利于持续探索的底层保障。端口映射是左端可改的-p 5678:5678左侧是宿主机端口如果本机 5678 已被占用可改为例如-p 8080:5678此时访问地址相应变为http://localhost:8080右侧必须保持 5678因为这是 n8n 进程在容器内的监听端口。注意n8n_data卷与容器内的/home/node/.n8n目录必须一一对应。如果更换镜像版本或使用非官方镜像建议先确认目标镜像内 n8n 数据目录路径是否一致再执行挂载以免出现数据挂丢了的假象。第三步验证容器运行并访问 Web UI执行完docker run后在 Docker Desktop 的容器列表中可以看到名为n8n的容器处于运行状态上方截图对应原文档中Docker 里面看到 n8n 运行啦的描述。也可以在命令行用以下命令复核# 查看容器状态STATUS 应显示 Up docker ps # 查看启动日志确认 n8n 完成初始化并监听 5678 端口 docker logs n8n --tail 50接下来进入 Web 界面。原文档给出的方式是**直接点击 Docker 客户端中容器的端口映射链接5678:5678**即可跳转在 macOS/Linux 或习惯浏览器的场景下等价做法是在浏览器打开http://localhost:5678首次访问时n8n 会引导你完成初始化创建 Owner 账号。登录成功后即可看到工作流列表页面页面中提供打开新项目/创建工作流的入口第四步认识 n8n 的三大基础功能原文档指出初学阶段主要用到的功能有三个见 N8N_INSTALL_GUIDE.md创建工作流打开新项目、添加节点、以及在工作流画布上连接与执行节点。其中添加节点是最核心的操作在工作流画布中点击添加新节点按钮或双击画布空白处在弹出的搜索框中搜索目标节点如Gmail、OpenAI、AI Agent、Simple Vector Store等选择自己有需要的节点添加即可随后在右侧面板配置参数并用连线把节点按数据流顺序连接起来。这套节点 连线的操作范式正是第五章 5.5.2 案例接收邮件 → AI Agent 思考/决策/调用工具 → 自动回复邮件中所有搭建动作的底层语法Code节点定义知识源、Simple Vector Store节点构建内存知识库、AI Agent节点整合 LLM/记忆/工具、Gmail节点收发邮件——无一不是添加节点 配置 连线的组合。日常维护与常见问题基于上述命令的参数设计这里补充几条实用的日常维护操作均可在只读查看/运行层面完成不涉及修改仓库内容# 查看 n8n 日志排查节点执行报错 docker logs n8n --tail 100 # 停止 / 启动 / 重启容器--restart unless-stopped 保证重启策略生效 docker stop n8n docker start n8n # 确认数据卷仍然存在数据都在这里面 docker volume ls # 升级 n8n 版本重新拉取新镜像并替换容器 # 先 docker stop n8n 与 docker rm n8n再用相同参数重新 docker run # 只要继续挂载 n8n_data 卷工作流与配置即完整保留常见排查思路浏览器打不开http://localhost:5678先用docker ps确认容器是否在运行、端口列是否显示0.0.0.0:5678-5678/tcp再看docker logs n8n是否完成启动若端口冲突按前文改用-p 8080:5678重新创建容器。C 盘空间告急回到第一步在 Docker Desktop 中把镜像存储迁移到大容量磁盘同时可用docker system prune清理无用镜像与构建缓存。数据丢失检查重建容器时是否挂载了同一个n8n_data卷-v n8n_data:/home/node/.n8n。只要卷还在、挂载路径不变数据就会跟随卷恢复。小结与后续学习路径本附录用两条命令完成了一个带持久化数据卷、自动重启策略、端口映射齐全的生产级 n8n 本地环境这也是 hello-agents 教程推荐 n8n 的部署方式。环境就绪后建议按以下路径继续阅读 第五章 5.5 节学习节点/工作流概念并动手搭建智能邮件助手案例含私有知识库构建与 AI Agent 节点配置若后续进入教程第十章的 MCP 协议实践需要以 JavaScript/TypeScript 编写的 MCP 服务器可配合同目录下的 Node.js 和 npx 安装教程 补齐 Node.js 运行环境结合code/目录下各章代码对照本章的容器化部署思路理解低代码流程驱动与代码驱动两类 Agent 构建路径的差异与互补。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
