n8n 全方位安装指南：从本地部署到云端运行一、引言 n8n 简介：强大的工作流自动化工具 ⚙️ n8n 是一款开源、可

一、引言

n8n 简介：强大的工作流自动化工具 ⚙️ n8n 是一款开源、可扩展的工作流自动化平台，它赋予技术团队通过直观的可视化界面与灵活的代码相结合的方式，构建复杂自动化流程的能力。它拥有超过 600 种集成和强大的原生 AI 功能，并采用对用户友好的 fair-code 许可证，确保您在享受自动化便利的同时，完全掌控自己的数据和部署方式。其独特基于节点的设计，带来了极高的灵活性，能够连接几乎任何应用或服务。
为何选择自托管 n8n？ 💡 自托管 n8n 的优势：

🔒 数据控制与隐私：您完全掌控工作流数据和凭据，无需担心第三方平台的限制或安全风险。
💰 成本效益：对于具备一定技术基础的用户，自托管在长期来看可能比云服务更经济，尤其对于需要持续运行或高频执行的工作流。
🛠️ 灵活性与定制：您可以自由扩展服务器资源，安装丰富的社区节点，甚至进行深度定制，不受云平台套餐的限制。
🆓 无限制：自托管版本通常没有云版本中常见的执行次数、工作流数量等限制，让您可以尽情发挥创造力。

本指南目标读者与范围 🎯 本指南旨在为对 n8n 感兴趣的初学者提供一份全面而详尽的安装教程。内容将覆盖从快速体验到本地开发环境搭建，再到生产环境的云端部署。目标是对 n8n 充满好奇，并具备一定基础技术知识（例如命令行操作、了解 Docker 概念）的用户。我将详细介绍使用 npm、Docker Desktop、OrbStack（针对 macOS）进行本地安装，以及在云服务器上进行部署的详细步骤和最佳实践。二、准备工作：安装 n8n 的先决条件 🛠️ 在开始安装 n8n 之前，请务必确保您的系统满足以下基本要求：
硬件与软件要求 ⚙️ 根据不同的安装方式和预期负载，推荐配置会有所不同，但以下是基本要求：表 1: n8n 系统要求暂时无法在飞书文档外展示此内容
基础技术知识 🧠

💻 命令行基础：熟悉使用终端或命令提示符执行基本命令（如 cd, ls, mkdir, nano 或其他文本编辑器）。
🐳 Docker 基础（推荐）：理解 Docker 镜像、容器、卷（Volume）和端口映射的基本概念，能够运行基本的 Docker 命令。
🌐 网络基础（云部署）：了解 IP 地址、DNS、端口和防火墙的基本概念。
☁️ 服务器管理基础（云部署）：了解如何通过 SSH 连接服务器、安装软件、管理用户和文件权限。虽然 n8n 本身旨在简化自动化，但自托管安装过程，尤其是云部署，确实需要一定的技术背景知识。官方文档也强调，自托管推荐给有经验的用户，错误的配置可能导致数据丢失、安全问题或服务中断。请务必认真对待每一步骤。三、本地安装：在您的计算机上运行 n8n 🏠 本地安装适用于学习、开发、测试工作流，或者运行一些不需要持续在线的个人自动化任务。以下介绍几种常见的本地安装方法。

使用 npm 全局安装 📦 如果您希望在本地持久化使用 n8n，并且熟悉 Node.js 生态系统，可以使用 npm 进行全局安装。

前提条件：已安装 Node.js (v18 或更高版本) 和 npm (9)。可以通过运行 node -v 和 npm -v 来检查。
安装命令：

npm install -g n8n

-g 标志表示全局安装，允许您在任何目录下运行 n8n 命令。
有时可能会遇到权限问题，根据您的系统可能需要使用 sudo (Linux/macOS)。
如果遇到 node-gyp 编译错误（尤其是在 Windows 上），请确保安装了 C++ 构建工具（Visual Studio 的 "Desktop development with C++" workload）。
在某些情况下，添加 --ignore-scripts 或 --omit=dev 标志可能有助于解决安装问题。
启动 n8n：

n8n

或者

n8n start

启动后，在浏览器中打开 http://localhost:5678。

💾 数据持久性：使用 npm 全局安装时，n8n 的数据（工作流、凭证等）默认存储在用户主目录下的 .n8n 文件夹中（例如 Linux/macOS 的 ~/.n8n）。数据是持久化的。
🏃 后台运行与进程管理：直接在终端运行 n8n 会在前台运行，关闭终端会导致 n8n 停止。为了让 n8n 在后台稳定运行，并能在系统重启后自动启动，建议使用进程管理器，如 PM2 或 systemd。
使用 PM2 (推荐):

npm install -g pm2
pm2 start n8n --name n8n
pm2 startup # 根据提示执行输出的命令
pm2 save

常用 PM2 命令:

pm2 list
pm2 stop n8n
pm2 restart n8n
pm2 logs n8n

使用 systemd (Linux)：需要创建 systemd 服务文件（例如 /etc/systemd/system/n8n.service），配置好用户、执行路径、环境变量等，然后使用 systemctl enable --now n8n.service 启动并设置开机自启。
Tunnel (开发测试)：如果需要在本地测试需要公网访问的 Webhook (如 GitHub)，可以使用 --tunnel 选项启动 n8n，它会创建一个临时公网 URL 指向您的本地实例。注意：这不安全，请勿用于生产环境。

n8n start --tunnel

使用 Docker (docker run) 🐳 Docker 是目前推荐的运行 n8n 的方式，它提供了隔离、可重复和易于管理的环境。docker run 命令适用于快速启动单个 n8n 容器。前提条件：已安装 Docker Desktop (Windows/macOS) 或 Docker Engine (Linux)。

Windows: 从 Docker 官网下载安装 Docker Desktop，建议启用 WSL2 后端。
macOS: 可以通过 Homebrew 安装: brew install --cask docker。
Linux (Ubuntu/Debian):

sudo apt update && sudo apt upgrade -y
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common docker.io # 或按照 Docker 官方文档安装 docker-ce
sudo systemctl enable --now docker
docker --version # 验证安装

运行 n8n 容器：

推荐：使用命名卷实现数据持久化：

创建 Docker 命名卷 (只需执行一次):

docker volume create n8n_data

运行 n8n 容器，并将卷挂载到 n8n 的数据目录 /home/node/.n8n：

docker run -d --name n8n \
-p 5678:5678 \
-v n8n_data:/home/node/.n8n \
n8nio/n8n

-d: 在后台分离模式运行容器。
--name n8n: 为容器指定一个名称，方便管理。
-p 5678:5678: 将主机的 5678 端口映射到容器的 5678 端口。
-v n8n_data:/home/node/.n8n: 将名为 n8n_data 的 Docker 卷挂载到容器内的 /home/node/.n8n 目录。这是关键，确保工作流、凭证等数据得以持久保存。
n8nio/n8n: 指定要使用的 n8n 官方 Docker 镜像。Docker 会自动拉取最新版本 (latest tag)。启动后，在浏览器中打开 http://localhost:5678。 ⚙️ 配置环境变量：可以通过 -e 标志在 docker run 命令中设置环境变量，例如启用基础认证：

docker run -d --name n8n \
-p 5678:5678 \
-v n8n_data:/home/node/.n8n \
-e N8N_BASIC_AUTH_ACTIVE=true \
-e N8N_BASIC_AUTH_USER=admin \
-e N8N_BASIC_AUTH_PASSWORD=yoursecretpassword \
-e GENERIC_TIMEZONE=UTC \
n8nio/n8n

也可以将环境变量写入一个文件（例如 .env 文件），然后使用 --env-file 标志加载。 🐳 容器管理：

docker ps # 查看正在运行的容器
docker stop n8n # 停止容器
docker start n8n # 启动已停止的容器
docker logs n8n # 查看容器日志
docker rm n8n # 移除容器 (需先停止)
docker exec -it n8n sh # 进入容器内部 (用于调试或手动安装社区节点)

使用 Docker Compose (推荐，含 OrbStack 示例) 🏗️ Docker Compose 是一个用于定义和运行多容器 Docker 应用程序的工具。即使只运行 n8n 单个服务，使用 Compose 也能更好地管理配置和卷，并且方便未来扩展（例如添加数据库服务）。对于 macOS 用户，OrbStack 提供了与 Docker Desktop 类似的功能，提供更优的性能和集成。前提条件：

已安装 Docker (Docker Desktop, Docker Engine, 或 OrbStack)。Docker Compose 通常随 Docker Desktop 一起安装。如果单独安装 Docker Engine，可能需要额外安装 Docker Compose 插件。
OrbStack (macOS): 可以通过 Homebrew 安装: brew install --cask orbstack。首次启动 OrbStack 需要管理员权限完成设置。设置步骤： 3.1 创建项目目录：在您希望存放 n8n 配置的地方创建一个新文件夹，并在终端中进入该目录。

mkdir my-n8n-project
cd my-n8n-project

3.2 创建 .env 文件：在项目目录中创建一个名为 .env 的文件，用于存放敏感信息和配置变量。这有助于将配置与 docker-compose.yml 文件分离。

#.env file
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=yoursecretpassword
GENERIC_TIMEZONE=UTC # 或者您的时区
N8N_HOST=n8n.agentic.orb.local # OrbStack 用户可以取消注释并使用自己的域名

稍后可以添加其他变量，如 N8N_ENCRYPTION_KEY

3.3 创建 docker-compose.yml 文件：在同一目录中创建 docker-compose.yml 文件

version: '3.7'
services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    environment:
      - N8N_HOST=${N8N_HOST:-localhost}
      - N8N_PORT=${N8N_PORT:-5678}
      - N8N_PROTOCOL=${N8N_PROTOCOL:-http}
      - NODE_ENV=production
      # 可以添加其他环境变量，例如数据库配置等
  
volumes:
  n8n_data:
    name: n8n_data

关键部分解释：

services: 定义运行的容器服务。
image: 指定使用的 Docker 镜像。
restart: 定义容器重启策略。
ports: 端口映射。
environment: 设置容器内的环境变量。
volumes: 定义数据卷挂载，n8n_data:/home/node/.n8n 将名为 n8n_data 的 Docker 卷挂载到容器内 n8n 的数据目录，实现持久化。 OrbStack 注意事项： OrbStack 可以为 docker-compose 服务自动创建 .orb.local 域名（如 n8n.agentic.orb.local 示例），如果配置了此功能，可以在 .env 文件中设置 N8N_HOST 并相应修改 WEBHOOK_URL，通过该域名访问。否则，http://localhost:5678 始终有效。

运行 n8n：在包含 docker-compose.yml 文件的目录下，运行：

docker compose up -d

-d 表示在后台运行。启动后，在浏览器中打开 http://localhost:5678 （或 OrbStack 的特定域名，如 n8n.agentic.orb.local）。 2. 管理：

docker compose down # 停止并移除容器，但保留卷
docker compose logs n8n # 查看日志
docker compose up -d # 启动服务

使用 Docker Compose 相较于单一的 docker run 命令，极大地简化了配置管理（通过 .env 文件）和未来添加其他服务（如数据库、反向代理）的过程。它将配置与服务定义清晰分离，促进了更佳的实践，即使仅在本地使用，如果预期未来可能扩展或迁移到云端，这也是一个更优的起点。OrbStack 则为 macOS 用户提供了运行此类 Docker 环境的流畅体验。本地安装方法对比 📊 选择哪种本地安装方法取决于您的具体需求和技术背景。表 2: 本地 n8n 安装方法对比暂时无法在飞书文档外展示此内容最适合的方法取决于用户的目标和技术舒适度。npm 安装可行，但需要额外工作来确保稳定运行（如使用 PM2）。Docker（无论是 run 还是 compose）提供了最健壮和可复现的环境，其中 compose 在组织结构和可扩展性方面更胜一筹，是为未来增长或云部署做准备的更佳选择。四、云端部署：在线自托管 n8n ☁️ 将 n8n 部署到云端服务器，可以让您随时随地访问工作流，并利用云服务提供的高可用性和可扩展性。

云端自托管基础 🚀 为何选择云端自托管？

🌐 可访问性：从任何地方通过互联网访问您的 n8n 实例。
💪 可靠性与扩展性：云服务商通常提供比本地计算机更高的稳定性和按需扩展资源的能力。
🤝 集成：便于与托管在同一云平台的其他服务（如数据库、存储、API 网关）集成。 🛠️ 通用方法：通常涉及租用云服务器（VPS 或 VM 实例），在服务器上安装 Docker，运行 n8n 容器，并通过反向代理和 HTTPS 进行安全加固。 🔑 关键安全提示：云端部署必须进行安全加固，这是不可协商的。自托管意味着您承担了安全管理员的责任。核心要素包括 HTTPS 加密和身份验证，后续将详细说明。

常用方法：在云服务器 (VPS) 上使用 Docker 🐳☁️ 这是最常见且相对直接的云端部署方式，适合熟悉基本服务器管理的用户。步骤详解：
选择云服务商和服务器：
常见选项包括阿里云, 腾讯云, 华为云, DigitalOcean, Hostinger, Hetzner, AWS EC2, Google Cloud Compute Engine, Azure VM 等。
选择一个操作系统，Ubuntu LTS (长期支持版) 是常用选择，并且许多示例都基于它。
根据预期负载选择服务器规格，确保满足最低硬件要求（参考表 1）。
服务器初始设置 (安全加固) 🛡️:
创建非 root 用户：创建一个具有 sudo 权限的普通用户，避免直接使用 root 用户操作。
配置 SSH 密钥认证：禁用密码登录，仅允许通过 SSH 密钥访问服务器，提高安全性。
设置防火墙：配置防火墙（如 Ubuntu 的 ufw），仅开放必要的端口，通常包括 SSH (默认 22)、HTTP (80) 和 HTTPS (443)。 Ubuntu ufw 示例

sudo ufw allow ssh # 或者指定端口号 sudo ufw allow 22/tcp
sudo ufw allow http # 或者 sudo ufw allow 80/tcp
sudo ufw allow https # 或者 sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

（可选）安装其他安全工具，如 Fail2ban（防止暴力破解）和 UFW（简化的防火墙管理）。
定期更新系统软件包：确保安装了最新的安全补丁和更新。

sudo apt update && sudo apt upgrade -y

安装 Docker 和 Docker Compose：
按照前文中适用于 Linux 的步骤安装 Docker Engine 和 Docker Compose 插件。
(可选) 将您的用户添加到 docker 组，避免每次都输入 sudo：sudo usermod -aG docker $USER (需要重新登录或新开 Shell 才生效)。
DNS 设置 🌐:
在您的 DNS 提供商处，将您计划用于访问 n8n 的域名或子域名（例如 n8n.yourdomain.com）指向您云服务器的公共 IP 地址。通常需要添加一条 A 记录。
准备 n8n 配置 (推荐 Docker Compose) ⚙️:
创建项目目录：在服务器上为 n8n 创建一个目录，例如 mkdir ~/n8n-docker && cd ~/n8n-docker。
创建 .env 文件：

- 包含必要的环境变量：

N8N_HOST=n8n.yourdomain.com (替换为您的域名) WEBHOOK_URL=n8n.yourdomain.com/ (使用 HTTPS) N8N_PROTOCOL=https N8N_BASIC_AUTH_ACTIVE=true N8N_BASIC_AUTH_USER=your_admin_user N8N_BASIC_AUTH_PASSWORD=your_strong_password GENERIC_TIMEZONE=UTC (或您的时区) N8N_ENCRYPTION_KEY: 极其重要！必须设置一个强随机字符串作为加密密钥，用于加密数据库中的凭证信息。务必妥善保管此密钥，迁移或恢复时需要用到。可以使用 openssl rand -hex 32 等命令生成。 6. 示例 .env 文件： ~/n8n-docker/.env

DATA_FOLDER=./n8n-data # 定义数据存储的基础路径 (用于卷映射)
N8N_HOST=n8n.yourdomain.com
WEBHOOK_URL=https://n8n.yourdomain.com/
N8N_PROTOCOL=https
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=aVeryStrongPassword123!
GENERIC_TIMEZONE=Europe/Berlin # 请替换为您的时区
# 使用 openssl rand -hex 32 生成一个强密钥
N8N_ENCRYPTION_KEY=your_very_long_and_random_encryption_key_here

创建 docker-compose.yml 文件：
定义 n8n 服务，并强烈建议包含一个反向代理服务（如 Caddy, Nginx, Traefik）。反向代理负责处理来自互联网的请求，管理 SSL 证书，并将流量安全地转发给 n8n 容器。
示例 (使用 Caddy 作为反向代理)：Caddy 以其自动 HTTPS 功能而闻名。 ~/n8n-docker/docker-compose.yml

version: '3.7'
services:
  caddy:
    image: caddy:latest # 使用官方 Caddy 镜像
    restart: unless-stopped
    ports:
      - "80:80" # HTTP 端口，Caddy 会自动重定向到 HTTPS
      - "443:443" # HTTPS 端口
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile # 挂载 Caddy 配置文件
      - caddy_data:/data # 持久化 Caddy 数据 (包括 SSL 证书)
      - caddy_config:/config
    environment:
      - N8N_HOST=${N8N_HOST} # 将域名传递给 Caddyfile (如果需要)
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    environment:
      - N8N_HOST=${N8N_HOST}
      - N8N_PORT=5678
      - N8N_PROTOCOL=${N8N_PROTOCOL}
      - NODE_ENV=production
      - WEBHOOK_URL=${WEBHOOK_URL}
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE}
      - N8N_BASIC_AUTH_USER=${N8N_BASIC_AUTH_USER}
      - N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      # 如果需要连接数据库，在此添加数据库相关环境变量
    volumes:
      - n8n_data:/home/node/.n8n
      - ${DATA_FOLDER}/local_files:/files # 可选：映射本地文件存储
    # 注意：n8n 服务不需要暴露 ports，因为 Caddy 会处理外部流量
volumes:
  n8n_data:
  caddy_data:
  caddy_config:

创建 Caddyfile (与 docker-compose.yml 同目录)： ~/n8n-docker/Caddyfile

{$N8N_HOST} { # 从环境变量获取域名
  reverse_proxy n8n:5678 # 将请求代理到名为 'n8n' 的服务 (docker compose 网络)
  encode zstd gzip
  # Caddy 会自动处理 HTTPS (Let's Encrypt)
}

示例 (使用 Nginx 作为反向代理)：需要手动配置 Nginx 并使用 Certbot 获取证书。Compose 文件会类似，但包含 nginx 服务，并需要挂载 Nginx 配置文件和 Certbot 数据。
示例 (使用 Traefik 作为反向代理)：Traefik 通过 Docker 标签进行配置，也支持自动 HTTPS。
反向代理与 HTTPS/SSL 设置 🔒:
为何需要反向代理？接收公网流量 (通常在 80/443 端口)，处理 SSL/TLS 加解密，并将请求转发到内部运行的 n8n 服务 (监听 5678 端口)。这增加了安全性和灵活性。
为何必须使用 HTTPS？加密浏览器和服务器之间的通信，保护登录凭证、API 密钥和工作流数据在传输过程中不被窃取。现代浏览器也会对非 HTTPS 站点显示不安全警告。
实现：
Caddy: 如上例所示，通常只需在 Caddyfile 中指定域名，Caddy 会自动从 Let's Encrypt 获取并续订 SSL 证书。
Nginx/Certbot: 需要在 Nginx 配置文件中设置 server 块来监听 80 和 443 端口，配置 proxy_pass 指向 http://n8n:5678，然后使用 Certbot 工具 (sudo certbot --nginx -d n8n.yourdomain.com) 获取证书并自动配置 Nginx 进行 SSL。需要设置定时任务自动续订证书 (sudo certbot renew --quiet --post-hook "systemctl restart nginx" 或类似命令)。
Traefik: 通过在 docker-compose.yml 中为 n8n 服务添加特定的 labels 来配置路由和 Let's Encrypt。
运行 n8n：在包含 docker-compose.yml 的目录中运行：

docker compose up -d

访问与验证 ✅:

在浏览器中打开 n8n.yourdomain.com (注意是 https)。
检查浏览器地址栏是否有挂锁图标，表示连接是安全的。
使用您在 .env 文件中设置的用户名和密码登录。在云端自托管 n8n 意味着您需要承担起安全管理的责任。虽然 Docker 部署相对简单，但这并不能免除您配置防火墙、强制 HTTPS、设置强认证和保护加密密钥等关键步骤。忽略这些步骤会将您的实例和数据置于风险之中。

高级选项：容器平台 (简述) 🚀☁️ 除了在单个 VPS 上运行 Docker，还有更高级的平台可以托管 n8n 容器：

平台示例：阿里云容器服务, 腾讯云容器服务, 华为云容器引擎, Google Cloud Run, Google Kubernetes Engine (GKE), AWS ECS/EKS, Azure Container Instances/AKS, Heroku, Railway, Render, Fly.io 等。
优势：这些平台通常提供更高级的功能，如自动扩展、托管基础设施、与其他云服务的深度集成。
挑战：
- 复杂性：Kubernetes (GKE/EKS/AKS) 功能强大，但学习曲线陡峭，配置复杂，对于简单的 n8n 部署来说往往是过度设计。
- 兼容性与限制：Serverless 平台（如 Cloud Run）可能与 n8n 的某些特性（如需要持久连接或特定后台进程）存在兼容性问题，官方目前并未完全支持 Serverless 环境。部署到这些平台可能需要额外的架构调整（如使用队列）或遇到预期之外的问题。
- 成本：虽然某些平台提供免费层或按需付费模式，但复杂设置或持续运行的实例可能会产生意想不到的费用。
适用场景：这些高级平台更适合有特定扩展需求、已有相关平台使用经验，或者需要深度集成特定云生态系统的用户。对于大多数初学者或标准自托管需求，从简单的 VPS + Docker Compose 开始通常是更稳妥、更易于管理的选择。如果对特定平台感兴趣，建议查阅官方文档或专门的部署指南。在选择部署平台时，需要权衡其提供的便利性、高级功能与引入的复杂性、潜在成本和兼容性风险。对于许多 n8n 自托管用户，特别是初学者，直接跳到 Kubernetes 这样的复杂平台可能弊大于利。五、验证您的安装 ✅ 成功安装并启动 n8n 后，需要进行基本验证。首次启动：访问 n8n 界面 🌐 打开您的网页浏览器。根据您的安装方式，导航到相应的 URL：
本地安装 (npm, Docker): http://localhost:5678
云端部署 (配置了 HTTPS): n8n.yourdomain.com (替换为您的域名) 设置所有者账户 👤 首次访问 n8n 时，您会看到一个设置所有者账户的界面。按照屏幕提示输入您的邮箱地址、姓名和密码。
密码要求：至少 8 个字符，包含至少一个数字和一个大写字母。点击 "Next" 或类似按钮完成账户创建。这个账户拥有实例的最高管理权限。之后，系统可能会提示您是否开始付费功能的试用，您可以选择跳过。简单工作流测试 ▶️ 进入 n8n 编辑器界面后，创建一个非常简单的工作流来验证核心功能是否正常工作。

点击 "+" 或 "Add workflow" 创建新工作流。
添加一个 "Manual" (手动触发) 节点作为开始。
从手动节点连接出一个 "Set" 节点。在 Set 节点中，可以设置一个简单的键值对，例如 name = test。
再连接一个 "NoOp" (No Operation) 节点，表示工作流结束。
点击编辑器右上角的 "Test workflow" 或 "Execute workflow" 按钮手动执行一次。
检查每个节点是否都成功执行（显示绿色对勾），并且 Set 节点是否输出了您设置的数据。完成这些步骤后，您的 n8n 实例就基本安装并验证成功了。六、基本管理和后续步骤 ⚙️ 成功安装 n8n 只是第一步，了解如何管理和维护您的实例同样重要。保持 n8n 更新 🔄 定期更新 n8n 至关重要，可以获取新功能、错误修复和重要的安全补丁。n8n 频繁发布新版本，通常分为 latest (稳定版，推荐生产使用) 和 next (最新测试版，可能不稳定)。更新步骤： npm 全局安装:
(如果使用 PM2/systemd) 停止 n8n 服务：pm2 stop n8n 或 sudo systemctl stop n8n.service。
运行更新命令：npm update -g n8n (更新到最新的 latest 版本)。
更新到 next 版本：npm install -g n8n@next。
更新到特定版本：npm install -g n8n@<version_number>。
(如果使用 PM2/systemd) 重启 n8n 服务：pm2 restart n8n 或 sudo systemctl start n8n.service。 Docker (docker run):
停止当前运行的 n8n 容器：docker stop n8n。
移除旧的 n8n 容器：docker rm n8n。
拉取最新的 n8n 镜像：docker pull docker.n8n.io/n8nio/n8n:latest。
关键：使用与之前完全相同的 docker run 命令重新启动容器，确保 -v 卷映射参数保持不变，以使用现有的数据卷。示例，确保 -v 参数与首次运行时一致 docker run -d --name n8n
-p 5678:5678
-v n8n_data:/home/node/.n8n
#... 其他环境变量... docker.n8n.io/n8nio/n8n:latest Docker Compose:
进入包含 docker-compose.yml 文件的目录。
拉取 n8n 服务的最新镜像：docker compose pull n8n。
重新创建并启动服务 (Compose 会自动使用新镜像并保留卷)：docker compose up -d。
(如果使用了自定义 Dockerfile) 可能需要添加 --build 标志：docker compose up -d --build。更新过程的核心在于正确管理数据持久性。对于 Docker 用户，无论是 docker run 还是 docker compose，必须确保更新后启动的容器连接到包含先前数据的同一个命名卷或绑定挂载路径。如果在更新后未使用正确的 -v 或 volumes 配置启动新容器，将导致数据丢失，相当于重新开始。理解数据持久性 (回顾) 💾 n8n 的核心数据（工作流定义、执行历史、凭证、用户设置等）默认存储在特定位置：

Docker 容器内: /home/node/.n8n
npm 全局安装: 用户主目录下的 .n8n 文件夹 (如 ~/.n8n) 对于 Docker 安装，使用卷 (Volume) 是实现数据持久化的关键。通过 docker run 的 -v 标志或 docker-compose.yml 中的 volumes: 部分，将容器内的 /home/node/.n8n 目录映射到 Docker 管理的命名卷或主机上的特定目录（绑定挂载）。这确保了即使容器被删除或重新创建（例如在更新期间），数据也能保留下来。初始安全检查清单 🛡️ 部署完成后，务必进行基本的安全检查：
🔑 启用身份验证：确保您已配置了访问控制。
- 基础认证 (Basic Auth)：最低要求，通过设置 N8N_BASIC_AUTH_ACTIVE=true 及相关用户/密码变量启用。
- 用户管理 (推荐)：如果有多人使用，应配置 SMTP 并启用 n8n 的用户管理功能，允许邀请用户、设置不同角色。
🔒 强制 HTTPS (云部署)：确保通过反向代理配置了有效的 SSL 证书，所有访问都通过 https:// 进行，加密传输数据。
🔑 保护加密密钥 (N8N_ENCRYPTION_KEY)：
- 必须设置：对于任何非临时性的自托管实例，都应设置此环境变量。
- 妥善保管：将此密钥备份在安全的地方。如果丢失，您将无法解密存储的凭证，也难以进行实例迁移。
🛑 后续安全措施：考虑实施更高级的安全措施，如限制特定节点（如 Execute Command, SSH）、禁用社区节点安装、进行安全审计、配置更严格的防火墙规则等。关键环境变量 ⚙️ 环境变量是配置自托管 n8n 实例的主要方式。了解常用变量对于管理实例至关重要。表 3: 常用 n8n 环境变量暂时无法在飞书文档外展示此内容掌握这些环境变量是有效管理自托管 n8n 实例的基础。它们控制着从基本访问、数据库连接到安全设置的方方面面。从一开始就理解最常见的变量及其用途至关重要。七、解决常见安装问题 🛠️ 在安装和配置 n8n 过程中可能会遇到一些问题。以下是一些常见问题及其解决方法： Docker 相关问题 🐳
错误：Conflict. The container name "/n8n" is already in use...
- 原因：已存在一个名为 n8n 的容器。
- 解决：在尝试重新运行 docker run 或 docker compose up 之前，先停止并移除同名容器：

docker stop n8n
docker rm n8n

权限错误 (绑定挂载)：
- 原因：在 Linux 上使用绑定挂载 (-v /host/path:/container/path) 时，容器内的 n8n 进程（通常以非 root 用户运行，如 UID 1000）可能没有写入主机目录的权限。
- 解决：
  - 更改主机目录的所有权以匹配容器内的用户 ID (通常是 1000 或 1002)：sudo chown -R 1000:1000 /host/path。
  - 或者，优先使用 Docker 命名卷 (-v volume_name:/container/path)，Docker 会自动处理权限。
端口冲突错误：
- 原因：主机上的 5678 端口已被其他应用程序占用。
- 解决：
  - 找出并停止占用该端口的其他服务。
  - 或者，在运行 n8n 时将容器的 5678 端口映射到主机上的其他可用端口，例如 -p 5679:5678，然后通过 http://localhost:5679 访问。 npm/Node.js 相关问题 📦
node-gyp 构建错误 (尤其在 Windows 上)：
- 原因：缺少编译 C++ 插件所需的构建工具。n8n 的某些依赖项可能需要原生编译。
- 解决：
  - 确保已通过 Visual Studio Installer 安装了 Visual Studio (推荐 2022 或更新版本)，并且勾选了 "Desktop development with C++" 工作负载。
  - 安装后重启计算机。
  - 尝试清理 npm 缓存：npm cache clean --force。
  - 确保 Node.js 和 Python (node-gyp 可能依赖) 版本兼容。
  - 以管理员身份运行终端。
错误：Cannot find module ''
- 原因：在 Code 节点中使用 require('') 时，该模块未安装在 n8n 的运行环境中。
- 解决：
  - npm 安装：在与全局 n8n 相同的环境中安装该模块：npm install -g 。
  - Docker 安装：需要构建一个自定义 Docker 镜像。创建一个 Dockerfile，以官方 n8nio/n8n 镜像为基础，然后添加 RUN npm install -g 指令来安装所需的模块，最后在 docker-compose.yml 或 docker run 命令中使用这个自定义镜像。
版本不兼容：
- 原因：使用的 Node.js 版本过低或与 n8n 版本不兼容。
- 解决：确保 Node.js 版本至少为 v18。如果需要管理多个 Node.js 版本，建议使用 NVM (Node Version Manager)。网络/访问问题 🌐
无法访问 localhost:5678 (本地安装)：
- 检查：
  - 确认 n8n 进程或容器正在运行 (pm2 status n8n, docker ps)。
  - 检查主机防火墙是否阻止了 5678 端口的入站连接。
  - 查看 n8n 日志 (pm2 logs n8n, docker logs n8n) 是否有启动错误。
无法访问 n8n.yourdomain.com (云部署)：
- 检查：
  - DNS 解析：确认域名已正确指向服务器 IP 地址 (可以使用 ping n8n.yourdomain.com 或 nslookup n8n.yourdomain.com 检查)。DNS 更改可能需要时间传播。
  - 服务器防火墙：确认服务器防火墙允许 80 (HTTP) 和 443 (HTTPS) 端口的入站流量。
  - 反向代理配置：检查反向代理（Nginx, Caddy, Traefik）的配置文件是否正确，日志中是否有错误。确保代理正确将流量转发到 n8n 容器的 5678 端口。
  - n8n 容器状态：确认 n8n 容器正在运行 (docker ps) 并且没有错误 (docker logs n8n)。
SSL 证书错误 (浏览器显示不安全)：
- 检查：
  - 确认 Certbot (如果使用) 已成功获取并安装证书。
  - 检查证书是否过期，以及自动续订任务是否正常工作。
  - 检查反向代理的 SSL 配置是否正确。
  - 确保始终使用 https:// 访问。
Chrome 浏览器提示 "危险网站" 或类似警告：
- 原因：Google 的安全浏览机制可能会将使用 n8n 作为子域名的网站（如 n8n.yourdomain.com）标记为潜在的仿冒网站。
- 解决：更改为您 n8n 实例的子域名，避免使用 n8n 本身。例如，使用 workflows.yourdomain.com 或 automation.yourdomain.com。配置问题 ⚙️
环境变量不生效：
- 检查：
  - 仔细核对 .env 文件或 docker run -e 标志中的变量名拼写、语法和值是否正确。
  - 对于 Docker Compose，确保 .env 文件与 docker-compose.yml 在同一目录下。
  - 修改环境变量后，需要重启 n8n 容器/进程才能生效 (docker compose down && docker compose up -d, docker restart n8n, pm2 restart n8n)。
更新或重启后数据丢失：
- 原因：几乎总是因为 Docker 卷映射配置不正确或丢失。
- 解决：
  - 验证卷映射：确保 docker run 的 -v 参数或 docker-compose.yml 的 volumes: 配置始终将外部卷/目录正确映射到容器内的 /home/node/.n8n。
  - 检查数据目录：确认映射的主机卷或目录中确实存在 database.sqlite 等 n8n 数据文件。如果该目录为空，说明之前的映射可能有问题，或者数据从未正确保存。
  - 切勿映射到错误路径：不要将卷映射到 /home/node/server.js 或其他应用程序代码路径。获取帮助的渠道 🆘 如果遇到本指南未涵盖的问题，可以寻求以下帮助：
官方文档 (docs.n8n.io)：提供全面的配置、使用和 API 参考。
社区论坛 (community.n8n.io)：非常活跃的社区，可以在此提问、搜索类似问题和解决方案。在提问前建议先搜索。
GitHub Issues (github.com/n8n-io/n8n/issues)：主要用于报告 Bug。建议先在论坛确认是否为已知问题或配置错误。希望这份详尽的指南能帮助您顺利地自托管 n8n！祝您自动化之旅愉快！

本文使用 mdnice 排版

END -