n8n

n8n 本地部署：Windows 使用 Docker Compose

这是一份面向完全没有 Docker 经验的教程。我们会从下载 Docker Desktop 开始，创建项目文件夹，写入 compose.yaml，启动 n8n，再处理网络、端口、权限和数据备份问题。

0. 先理解四个词

Docker Desktop 是 Windows/macOS 上的安装程序；Docker Engine 是真正运行容器的引擎；Docker Compose 用一个 YAML 文件描述服务；容器是 n8n 的运行实例，volume 是保存 n8n 数据的持久化空间。小白只需要安装 Docker Desktop，不要在 Windows 的 WSL 里再单独安装第二套 Docker。

1. 下载 Docker Desktop

请只从 Docker 官方网站下载。Windows 普通 Intel/AMD 电脑选择 Windows x86_64；Mac 先在“关于本机”查看芯片，Apple M 系列选择 Apple silicon，Intel 选择 Intel。下载完成后不要从第三方网盘获取安装包。

2. Windows 的安装与验证

# 以管理员身份打开 PowerShell
wsl --install
wsl --update
wsl --set-default-version 2

# 重新打开普通 PowerShell 后验证
wsl --status
wsl -l -v
docker version
docker compose version
docker run --rm hello-world

Windows 需要 WSL 2、硬件虚拟化和 Linux containers；Mac 需要 Docker.app 正在运行。验证命令必须看到 Docker 版本信息，并且 hello-world 能成功运行。

3. 创建项目目录

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$HOME\n8n-local\local-files", "$HOME\n8n-local\backups"
Set-Location "$HOME\n8n-local"

# macOS Terminal
mkdir -p "$HOME/n8n-local/local-files" "$HOME/n8n-local/backups"
cd "$HOME/n8n-local"

Windows 推荐目录为 C:\Users\你的用户名\n8n-local，macOS 推荐目录为 /Users/你的用户名/n8n-local。以后所有命令都要在这个目录中执行。

4. 创建配置文件

在 n8n-local 中创建 .env 文件，内容至少包括 N8N_ENCRYPTION_KEY 和 GENERIC_TIMEZONE=Asia/Shanghai。再创建 compose.yaml，使用 n8n_data volume 保存数据，使用 ./local-files:/files 映射本机文件。

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:stable
    container_name: n8n
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - N8N_ENCRYPTION_KEY=请替换为一串长期保存的随机密钥
      - GENERIC_TIMEZONE=Asia/Shanghai
      - TZ=Asia/Shanghai
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_RESTRICT_FILE_ACCESS_TO=/files
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files

volumes:
  n8n_data:

5. 启动 n8n

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 n8n

看到状态为 Up 后访问 http://localhost:5678。

6. 首次登录与测试

第一次打开网页时创建 n8n owner 账户。随后建立 Manual Trigger → Set → Execute 的最小工作流，确认编辑器、执行和数据保存都正常。

7. 常见问题

如果 docker 不是命令，说明 Docker Desktop 没启动或 PATH 尚未刷新；如果 Cannot connect to the Docker daemon，先启动 Docker Desktop；如果 port is already allocated，把 127.0.0.1:5678:5678 改为 127.0.0.1:5679:5678；如果镜像拉取超时，检查 Docker Desktop 的代理、VPN、DNS 和公司网络；如果 Windows WSL 失败，执行 wsl --update、wsl --shutdown 后重启 Docker Desktop；如果凭据无法解密，恢复原来的 N8N_ENCRYPTION_KEY。

8. 备份与升级

备份 n8n_data、.env 和 compose.yaml。升级前先停止并备份，再执行 docker compose pull 和 docker compose up -d。不要随意执行 docker compose down -v，因为它会删除 volume。