在 MacOS 上使用 docker 部署 n8n 2.x

这份文档以本机部署为目标：使用 Docker Compose 启动 n8n，并通过 launchd 实现“登录后自动启动”。

前置条件

macOS 已安装 Docker Desktop
Docker Desktop 已开启 “Start Docker Desktop when you log in”
有一个部署目录（示例使用 /Users/qinhua/Documents/n8n）

目录结构

建议目录结构如下：

# /Users/qinhua/Documents/n8n/
docker-compose.yml
run.sh
n8n_data/

其中：

docker-compose.yml：docker compose 配置文件
run.sh：启动脚本（会等待 Docker 就绪后再启动）
n8n_data/：持久化数据目录（n8n 配置、凭据、SQLite 等）

Docker Compose 配置

进入 n8n 部署目录：

cd /Users/qinhua/Documents/n8n

在目录下创建 docker-compose.yml 文件，并写入如下内容：

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    ports:
      - "5678:5678"
    user: "${UID:-1000}:${GID:-1000}" # 以指定用户运行（默认 1000:1000）
    # 环境变量文档：https://docs.n8n.io/hosting/configuration/environment-variables
    environment:
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - N8N_HOST=localhost
      - N8N_EDITOR_BASE_URL=http://localhost:5678
      - WEBHOOK_URL=http://localhost:5678
      - N8N_EDITOR_BASE_URL=http://localhost:5678 # 编辑器基础URL
      - WEBHOOK_URL=http://localhost:5678 # 外部回调URL
      - N8N_RELEASE_TYPE=stable # 使用稳定版本
      - N8N_BLOCK_ENV_ACCESS_IN_NODE=false # 允许节点访问环境变量
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false # 强制设置文件权限
      - NODE_FUNCTION_ALLOW_BUILTIN=* # 允许所有内置模块
      - N8N_GIT_NODE_ENABLE_HOOKS=true # 允许git节点执行钩子
      - NODES_EXCLUDE=[] # 排除指定节点
      - GENERIC_TIMEZONE=Asia/Shanghai
      - TZ=Asia/Shanghai
    volumes:
      - ./n8n_data:/home/node/.n8n
      - ./n8n_files:/home/node/.n8n-files
    restart: unless-stopped

启动/停止：

启动：docker compose up -d
查看状态：docker compose ps
查看日志：docker compose logs -f --tail=200
停止：docker compose down

启动后访问：http://localhost:5678

升级镜像：

cd /Users/qinhua/Documents/n8n && docker compose pull && docker compose up -d`

可选：外网访问与安全配置

如果只在本机使用，保持 N8N_HOST=localhost、WEBHOOK_URL=http://localhost:5678/ 即可。

如果需要在局域网或通过域名访问，需要把以下几个值改为你的实际访问地址（否则 Webhook URL 会生成错误）：

N8N_HOST
N8N_EDITOR_BASE_URL
WEBHOOK_URL

同时建议设置加密 key，避免重启/迁移后凭据无法解密：

N8N_ENCRYPTION_KEY：自行生成一个随机长字符串并妥善保存

如果你会把 n8n 暴露到非可信网络，建议至少启用基础认证（或放在反向代理后做认证）：

N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=...
N8N_BASIC_AUTH_PASSWORD=...

不建议把上述敏感信息直接写进 docker-compose.yml 并提交到仓库。可以使用 .env：

services:
  n8n:
    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE}
      - N8N_BASIC_AUTH_USER=${N8N_BASIC_AUTH_USER}
      - N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD}

启动脚本 `run.sh`

/Users/qinhua/Documents/n8n/run.sh 用于在系统启动或登录后等待 Docker Desktop 就绪，再执行 docker compose up -d。

建议脚本具备可执行权限：

chmod +x /Users/qinhua/Documents/n8n/run.sh

脚本示例（与你当前的逻辑一致）：

#!/bin/bash
set -euo pipefail
cd /Users/qinhua/Documents/n8n
for _ in $(seq 1 60); do
  if docker info >/dev/null 2>&1; then
    docker compose up -d
    exit 0
  fi
  sleep 5
done
exit 1

如果你后续可能移动目录，建议把脚本中的固定 cd 改为进入脚本所在目录：

#!/bin/bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$SCRIPT_DIR"
for _ in $(seq 1 60); do
  if docker info >/dev/null 2>&1; then
    docker compose up -d
    exit 0
  fi
  sleep 5
done
exit 1

配置自启动（launchd）

macOS 没有 systemctl，推荐使用 launchd 的 LaunchAgent 实现“用户登录后自启动”。

1) 创建 plist

保存为：/Users/qinhua/Library/LaunchAgents/com.qinhua.n8n.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.qinhua.n8n</string>
    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>/Users/qinhua/Documents/n8n/run.sh</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/qinhua/Documents/n8n</string>
    <key>RunAtLoad</key>
    <true/>

      <key>StandardOutPath</key>
      <string>/Users/qinhua/Library/Logs/n8n-launchd.out.log</string>
      <key>StandardErrorPath</key>
      <string>/Users/qinhua/Library/Logs/n8n-launchd.err.log</string>
  </dict>
</plist>

校验配置文件：

plutil -lint /Users/qinhua/Library/LaunchAgents/com.qinhua.n8n.plist

2) 加载并启用

launchctl bootout "gui/$(id -u)" /Users/qinhua/Library/LaunchAgents/com.qinhua.n8n.plist 2>/dev/null || true
launchctl bootstrap "gui/$(id -u)" /Users/qinhua/Library/LaunchAgents/com.qinhua.n8n.plist
launchctl enable "gui/$(id -u)/com.qinhua.n8n"
launchctl kickstart -k "gui/$(id -u)/com.qinhua.n8n"

卸载（不再自启动）：

launchctl bootout "gui/$(id -u)" /Users/qinhua/Library/LaunchAgents/com.qinhua.n8n.plist

3) 验证与日志

查看任务状态：

launchctl print "gui/$(id -u)/com.qinhua.n8n" | head -n 80

查看脚本日志：

tail -n 200 /Users/qinhua/Library/Logs/n8n-launchd.out.log
tail -n 200 /Users/qinhua/Library/Logs/n8n-launchd.err.log

常见问题：

Docker 未就绪：脚本会最多等待 5 分钟，超时可通过日志确认
端口冲突：lsof -nP -iTCP:5678 -sTCP:LISTEN
容器未启动：cd /Users/qinhua/Documents/n8n && docker compose ps 与 docker compose logs -f

备份与迁移

核心是备份数据目录 n8n_data/：

停止服务：cd /Users/qinhua/Documents/n8n && docker compose down
打包备份：cd /Users/qinhua/Documents/n8n && tar -czf n8n_data_$(date +%Y%m%d).tar.gz n8n_data