n8n 项目部署

一、功能概览

二、部署方案选择

建议：一开始就用 PostgreSQL。官方文档指出 SQLite 适合试用，日后切换数据库并不能顺畅带走数据。

三、环境要求

• Linux 服务器（也可在 macOS 或 Windows 的 Docker 环境中试用）
• Docker Engine 与 Docker Compose 插件
• 内存：个人使用 1GB 起步，建议 2GB 以上；工作流多、数据量大时适当增加
• 域名并解析到服务器（接收外部 Webhook 或公网访问时必须）
• 端口：n8n 默认监听 5678，生产环境建议只在本机监听，由反向代理对外提供 443

四、Docker Compose + PostgreSQL 部署（推荐）

4.1 创建目录

mkdir -p ~/n8n && cd ~/n8n

4.2 生成加密密钥

openssl rand -hex 32

把输出保存好，作为 N8N_ENCRYPTION_KEY。

这个密钥极其重要：n8n 用它加密所有已保存的凭据。密钥丢失或更换后，已保存的凭据将全部无法解密。请保存到密码管理器，并与数据库备份分开存放。

4.3 编写 .env

# .env
POSTGRES_USER=n8n
POSTGRES_PASSWORD=请替换为强密码
POSTGRES_DB=n8n

N8N_ENCRYPTION_KEY=填入上一步生成的密钥
N8N_HOST=你的域名
WEBHOOK_URL=https://你的域名/
GENERIC_TIMEZONE=Asia/Shanghai

提醒：

• WEBHOOK_URL 末尾要带斜杠，且必须是外部实际访问的完整地址。写错的后果是工作流能保存却收不到任何外部回调，而且没有明显报错。
• .env 含有密钥，务必加入 .gitignore，不要提交到代码仓库。

4.4 编写 docker-compose.yml

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - db-storage:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
      DB_POSTGRESDB_USER: ${POSTGRES_USER}
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
      N8N_HOST: ${N8N_HOST}
      N8N_PROTOCOL: https
      N8N_PORT: 5678
      WEBHOOK_URL: ${WEBHOOK_URL}
      N8N_PROXY_HOPS: 1
      GENERIC_TIMEZONE: ${GENERIC_TIMEZONE}
      TZ: ${GENERIC_TIMEZONE}
      EXECUTIONS_DATA_PRUNE: "true"
      EXECUTIONS_DATA_MAX_AGE: 336
    volumes:
      - n8n-storage:/home/node/.n8n

volumes:
  db-storage:
  n8n-storage:

说明：

• 端口只绑定 127.0.0.1，由反向代理接入，避免把 5678 直接暴露到公网。
• N8N_PROXY_HOPS: 1 表示前面有一层反向代理，使 n8n 正确识别客户端地址和协议。
• EXECUTIONS_DATA_PRUNE 与 EXECUTIONS_DATA_MAX_AGE 用于自动清理历史执行记录（单位为小时，示例为保留 14 天），防止数据库无限增长。
• 镜像地址是镜像仓库路径，不是网页链接。生产环境建议把标签固定为具体版本号，升级时手动修改。
• 如果只是在局域网用 IP 通过 HTTP 访问试用，需要把协议改为 http，并将 N8N_SECURE_COOKIE 设为 false，否则登录后会话无法保持。正式环境应使用 HTTPS，并保持安全 Cookie 开启。

4.5 启动

docker compose up -d
docker compose ps
docker compose logs -f n8n

4.6 配置反向代理（Caddy 示例）

在服务器上单独运行 Caddy（或把它加入同一个 Compose），Caddyfile 内容：

你的域名 {
    encode zstd gzip
    reverse_proxy 127.0.0.1:5678
}

使用 Nginx 时请注意：

• 必须开启 WebSocket 升级支持，否则编辑器的实时执行状态会异常。
• 适当调大请求体大小限制和超时时间，以便接收较大的 Webhook 数据。

4.7 首次初始化

浏览器访问你的域名，首次进入会引导创建所有者账号（邮箱、姓名、强密码）。之后在设置中可邀请其他用户。

五、关键环境变量速查

六、队列模式（可选，用于扩展）

当出现长时间运行的工作流阻塞其他任务、突发 Webhook 请求被丢弃，或单进程处理不过来时，可切换到队列模式。

原理：主进程负责编辑器、接收 Webhook 和调度，实际的工作流执行交给多个工作进程，通过 Redis 队列分发。

要点：

1. 必须使用 PostgreSQL，不能使用 SQLite。
2. 增加 Redis 服务，并在主进程和工作进程中配置：

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379

3. 新增一个或多个工作进程服务，使用同一镜像，启动命令设为 worker：

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    command: worker
    depends_on:
      - postgres
      - redis
    environment:
      # 与主进程保持完全一致的数据库、加密密钥与队列配置
      EXECUTIONS_MODE: queue
      QUEUE_BULL_REDIS_HOST: redis
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
      # 其余 DB_* 变量同主进程
    volumes:
      - n8n-storage:/home/node/.n8n

4. 主进程、所有工作进程以及 Webhook 处理进程必须使用相同的 N8N_ENCRYPTION_KEY，否则无法解密凭据。
5. 主进程保持单副本；扩容主要靠增加工作进程数量。
6. 单主进程的队列模式在自托管下没有许可限制；多主进程等更高级的架构可能涉及企业许可，请查阅官方说明。

七、安全加固

1. 保护编辑器：不要把未经保护的 5678 端口暴露到公网，使用 HTTPS 与强密码，启用账号的二步验证（若版本支持），必要时在代理层限制来源 IP。
2. 审慎处理 Webhook：Webhook 地址一旦公开就可能被任何人调用，建议给 Webhook 节点配置认证（如请求头令牌或基础认证），并在工作流内校验来源。
3. 最小权限凭据：给第三方服务生成专用的、只授予必要权限的密钥，不要使用主账号密钥。
4. 谨慎使用高风险节点：执行命令、读写文件等节点能影响服务器本身，团队多人使用时应限制谁能创建和编辑工作流。
5. 容器隔离：不要给 n8n 容器挂载不必要的宿主机目录，更不要挂载 Docker 套接字。
6. 社区节点风险：社区节点由第三方开发，安装前先审查来源和代码，生产环境谨慎启用。
7. 及时升级：关注官方发布说明和安全公告，及时更新。

八、备份与恢复

8.1 必须备份的内容

8.2 数据库备份

docker compose exec -T postgres pg_dump -U n8n n8n | gzip > n8n-db-$(date +%F).sql.gz

8.3 工作流与凭据导出（辅助手段）

docker compose exec n8n n8n export:workflow --all --output=/home/node/.n8n/backup-workflows.json
docker compose exec n8n n8n export:credentials --all --output=/home/node/.n8n/backup-credentials.json

导出的凭据文件仍默认保持加密状态，但同样属于敏感文件，请妥善保管。导出文件可作为额外保险，但不能替代数据库备份。

8.4 恢复与演练

1. 部署同版本的 n8n 与 PostgreSQL。
2. 导入数据库备份。
3. 使用原来的加密密钥启动 n8n。
4. 登录检查：凭据能否正常使用、Webhook 地址是否正确生成、定时工作流是否按时触发。

建议定期做一次完整的恢复演练。遵循 3-2-1 原则：3 份副本、2 种介质、1 份异地，备份文件要加密保存。

九、升级与维护

cd ~/n8n
# 升级前先备份数据库
docker compose pull
docker compose up -d
docker image prune

建议：

• 升级前阅读官方发布说明，大版本更新可能带有破坏性变更，应先在测试环境验证。
• 固定镜像版本，不要让 latest 在无意中自动升级。
• 数据库大版本升级需要单独规划迁移。
• 定期检查磁盘占用，确认执行记录清理已生效。
• 监控容器健康状态和日志，为关键工作流配置失败告警。

十、常见问题排查

十一、命令速查

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart n8n

# 日志
docker compose logs -f n8n

# 生成加密密钥
openssl rand -hex 32

# 数据库备份
docker compose exec -T postgres pg_dump -U n8n n8n | gzip > n8n-db-$(date +%F).sql.gz

# 升级
docker compose pull && docker compose up -d