用 n8n 自建自动化：GitHub Push 后自动部署到服务器-技术分享-MACS Dev Hub

前言

作为 Java 开发者，我们都经历过这样的流程：本地 git push，然后手动登录服务器，git pull，重启应用。偶尔做一次还行，一天做十次就让人抓狂了。

传统的 CI/CD 方案当然很好，但 Jenkins 太重，GitHub Actions 又离不开 GitHub 生态。有没有一种轻量级、可视化、跨平台的自动化方案？

答案是 n8n——一个开源的工作流自动化工具。本文将在 Windows 11 + WSL2 环境下，带你从零搭建 n8n，实现“GitHub Push 后自动部署到服务器”的完整自动化流程。

本文属于 MACS Dev Hub“现代架构与编码解决方案”系列。前文介绍了 WSL2 + Docker 配置 Java 开发环境，本文将在该环境基础上继续实践。

一、n8n 是什么？为什么用它做 CI/CD？

1.1 n8n 简介

n8n 是一个开源的工作流自动化工具，支持连接超过 400 种应用和服务（GitHub、Slack、HTTP、数据库等），通过可视化界面拖拽节点即可构建自动化流程。与 Zapier、Make 等商业产品不同，n8n 可以完全自托管，数据不出自己的服务器。

截至 2026 年，n8n 的用户量持续增长，自托管方案日趋成熟。自托管的 n8n 与官方云服务在功能上并无本质差异，只是基础设施（服务器、备份、更新）需要自己管理。

1.2 n8n vs 传统 CI/CD 工具

维度	n8n	GitHub Actions	Jenkins
学习曲线	低（可视化拖拽）	中（YAML 配置）	高（插件生态复杂）
部署成本	Docker 一键启动	免费（但绑定 GitHub）	较重，需单独服务器
灵活性	高（400+ 节点，支持 HTTP/Webhook）	中（受 GitHub 生态限制）	极高（但维护成本高）
适用范围	通用自动化（不限 CI/CD）	仅限 GitHub 仓库	DevOps 全场景
适用场景	轻量级部署、个人项目、小团队	深度 GitHub 用户	大型企业、复杂流水线

结论：n8n 不适合替代企业级 CI/CD，但对于个人项目、小团队、快速原型部署来说，它是完美的轻量级替代方案。

1.3 核心架构：我们需要哪几个节点？

本次自动化流程涉及以下节点：

Webhook 节点（触发器）——监听 GitHub 的 Push 事件
HTTP Request 节点——拉取 GitHub 仓库最新代码
SSH 节点——远程登录部署服务器执行命令
IF 节点——过滤非目标分支（仅 master/main）

完整的工作流程如下图所示：

二、环境准备

2.1 前置条件

本文假设你已具备以下条件（基于前两篇文章配置的环境）：

Windows 11 + WSL2 + Docker Desktop 已安装
一台目标部署服务器（可以是另一台 VPS，或本地虚拟机，需开启 SSH）
GitHub 仓库（含需要自动部署的 Java/Spring Boot 项目）

2.2 部署方式对比

n8n 自托管有多种方式，下面是 2026 年的主流方案对比：

部署方式	难度	成本	适用场景
Docker Compose（推荐）	低	约 $4-5/月（VPS）	生产环境、数据持久化
npm 本地安装	中	免费	开发测试
n8n Cloud	极低	按执行次数计费	不想维护服务器
托管平台（PikaPods 等）	低	约 $5-10/月	不想自己配置数据库

本文选择 Docker Compose 方案，数据持久化、方便升级、与 WSL2 环境完美兼容。

2.3 准备工作

在开始部署前，先确认以下几项：

目标服务器的 SSH 连接信息：

IP 地址 / 域名
SSH 端口（默认 22）
用户名（建议使用非 root 用户，如 deploy）
私钥或密码

准备工作目录（在 WSL2 内执行）：

mkdir -p ~/docker/n8n
cd ~/docker/n8n

为什么要在 WSL2 内部部署？
根据前文的性能测试，在 WSL2 内部文件系统（~/ 目录）操作文件性能接近原生 Linux。虽然 n8n 本身不涉及大量文件 I/O，但保持统一环境有助于后续维护。

三、部署 n8n（Docker Compose 方案）

3.1 创建 docker-compose.yml

在 ~/docker/n8n/ 目录下创建 docker-compose.yml：

version: '3.8'

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - WEBHOOK_URL=http://localhost:5678/
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files
    networks:
      - n8n_network

networks:
  n8n_network:
    driver: bridge

volumes:
  n8n_data:

配置说明：

volumes 中的 n8n_data 持久化存储工作流和凭证，容器删除后数据不丢失
WEBHOOK_URL 决定了 GitHub 回调的地址，如果是公网 VPS，需要改为 http://你的公网IP:5678/
N8N_ENCRYPTION_KEY 用于加密凭证，建议在 .env 文件中配置

3.2 创建环境变量文件

在相同目录下创建 .env 文件：

# 生成一个随机密钥（可通过 openssl rand -hex 16 生成）
N8N_ENCRYPTION_KEY=你的随机32位密钥

生成随机密钥的快捷命令：

openssl rand -hex 16

3.3 启动 n8n

docker-compose up -d

查看启动日志：

docker-compose logs -f

首次启动需要拉取镜像（约 600MB），等待片刻。启动成功后，通过浏览器访问 http://localhost:5678（WSL2 内可直接访问，或通过 Windows 浏览器访问 WSL2 的 IP）。

注意：如果你的 n8n 部署在云服务器上，首次访问时会要求创建管理员账户和设置密码，这是正常的初始化流程。

3.4 部署验证

打开浏览器访问 http://localhost:5678，看到 n8n 的 Web 界面即表示部署成功。创建管理员账户后即可进入工作流编辑界面。

四、构建 GitHub → 部署自动化工作流

本节建议打开 n8n Web 界面，边看边操作。

4.1 第一步：创建 Webhook 触发器

在 n8n 仪表板点击 “New Workflow”。
点击 “Add first step…”，搜索 Webhook 节点。
选择 Webhook 节点，配置如下：

HTTP Method：POST
Path：github-webhook（可自定义）
Authentication：None（后续可以加验证）
Response Mode：Last Response
Response Data：All Entries

点击 “Execute Node” 激活 Webhook 节点，页面会显示一个 Webhook URL，类似：

   http://localhost:5678/webhook/github-webhook

复制这个 URL，稍后要配置到 GitHub 仓库。

4.2 第二步：配置 GitHub Webhook

打开你的 GitHub 仓库 → Settings → Webhooks → Add webhook。
将上一步复制的 URL 粘贴到 Payload URL。
Content type 选择 application/json。
Secret 可选（留空或自定义，开启后可验证请求合法性）。
在 Which events would you like to trigger this webhook? 选择 “Just the push event”。
点击 “Add webhook” 保存。

配置完成后，每次 git push 到该仓库，GitHub 都会发送一个 POST 请求到 n8n Webhook 节点。

4.3 第三步：添加分支过滤（IF 节点）

我们可能只想在 main 或 master 分支上触发部署，而不是每个 feature 分支。

在 Webhook 节点后添加一个 IF 节点：

点击 Webhook 节点右侧的 + 号，搜索 IF。
在 IF 节点的 Conditions 中配置：

左侧选择：{{ $json.ref }}
操作符选择：Equals
右侧输入：refs/heads/main（如果是 master 分支则写 refs/heads/master）

4.4 第四步：拉取仓库最新代码（HTTP Request 节点）

GitHub Webhook 的 payload 中包含仓库的 clone URL 和分支信息。我们可以利用这些信息，通过 HTTP Request 节点在部署服务器上拉取代码。

实际上，更稳妥的做法是通过 SSH 节点直接登录服务器执行 git pull，而不是用 n8n 拉取后再传输。因此，这一节我们跳过代码拉取环节，直接进入 SSH 部署。

建议：在目标服务器上先配置好 SSH 公钥，让服务器能够无密码拉取 GitHub 仓库。这样 SSH 节点只需执行 cd /path/to/project && git pull && docker-compose restart 即可完成部署。

4.5 第五步：SSH 远程执行部署命令

这是整个自动化的核心环节。n8n 的 SSH 节点允许在工作流中执行远程服务器命令。

在 IF 节点后添加 SSH 节点：

搜索并选择 SSH 节点。
配置 SSH 连接凭据：

点击 “Create New” 创建 SSH 凭据
填写：主机地址、端口（默认 22）、用户名
认证方式选择 Private Key（推荐）或 Password
粘贴部署服务器的 SSH 私钥内容

配置执行命令：

Command 字段输入需要远程执行的部署脚本，例如：

   cd /home/deploy/my-java-app && \
   git pull origin main && \
   docker-compose down && \
   docker-compose up -d --build

Working Directory 可选，留空则使用默认目录
勾选 “Execute Once” 执行一次命令

设置 Timeout 为适当值（如 300 秒），避免长时间部署导致超时。

4.6 第六步：处理响应和错误

建议在 SSH 节点后添加一个 NoOp 或 Respond to Webhook 节点，将执行结果返回给调用方（可选）。也可以添加 Error Trigger 节点，在 SSH 命令执行失败时发送通知（如企业微信、钉钉、邮件）。

五、完整工作流 YAML 代码

如果你不想手动拖拽配置，可以直接导入以下工作流 JSON（保存为 .json 文件，在 n8n 界面选择 Import from File）：

{
  "name": "GitHub Push Auto Deploy",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "github-webhook",
        "responseMode": "responseNode",
        "options": {}
      },
      "id": "webhook-node",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1.1,
      "position": [250, 300]
    },
    {
      "parameters": {
        "conditions": {
          "string": [
            {
              "value1": "={{ $json.ref }}",
              "operation": "equals",
              "value2": "refs/heads/main"
            }
          ]
        }
      },
      "id": "if-node",
      "name": "Check Branch",
      "type": "n8n-nodes-base.if",
      "typeVersion": 1,
      "position": [450, 300]
    },
    {
      "parameters": {
        "host": "your-server-ip",
        "port": 22,
        "username": "deploy",
        "authentication": "privateKey",
        "privateKey": "",
        "command": "cd /home/deploy/app && git pull origin main && docker-compose down && docker-compose up -d --build"
      },
      "id": "ssh-node",
      "name": "SSH Deploy",
      "type": "n8n-nodes-base.ssh",
      "typeVersion": 1,
      "position": [650, 300]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{ "node": "Check Branch", "type": "main", "index": 0 }]]
    },
    "Check Branch": {
      "main": [[{ "node": "SSH Deploy", "type": "main", "index": 0 }]]
    }
  }
}

注意：导入前需要手动配置 SSH 凭据。

六、安全注意事项

6.1 暴露 Webhook 的安全风险

n8n 的 Webhook URL 一旦被恶意攻击者获取，可能被用于触发任意工作流。针对这个问题，2026 年初 n8n 官方披露了一个安全漏洞（GHSA-mqpr-49jj-32rc），攻击者可以伪造未签名请求触发工作流。

建议的安全措施：

使用 Webhook Secret：在 GitHub Webhook 设置中配置 Secret，并在 n8n Webhook 节点中开启签名验证
限制 IP 范围：如果 n8n 部署在公网，建议仅允许 GitHub 的官方 IP 范围访问
启用 HTTPS：在生产环境中务必配置 Nginx 反向代理 + SSL 证书
设置复杂路径：避免使用简单的 /webhook 路径，可加上随机字符串

6.2 SSH 凭据保护

SSH 私钥是敏感信息，n8n 会将其加密存储（依赖 N8N_ENCRYPTION_KEY）。务必妥善保管该密钥，不要泄露。

七、常见问题与排查

问题	可能原因	解决方法
Webhook 收到 404	URL 路径不匹配	检查 Webhook 节点的 Path 配置和 GitHub 中填写的 URL
Webhook 收到 500	n8n 内部错误	查看 `docker-compose logs n8n`
SSH 连接失败	公钥/私钥配置错误	先在本地用 `ssh -i private_key user@host` 测试
SSH 命令执行超时	部署时间过长	增加 SSH 节点的 Timeout 值
`git pull` 报权限错误	服务器 SSH 密钥未配置	在目标服务器上配置 GitHub 部署密钥
n8n 无法访问外网（WSL2）	DNS 或网络配置	检查 `/etc/resolv.conf`，或重启 WSL2

八、扩展方向

本文实现了基础的“GitHub Push → SSH 部署”流程。你还可以根据实际需求扩展：

构建前测试：在工作流中增加 HTTP Request 节点触发 GitHub Actions 运行单元测试，通过后再部署
多环境部署：通过 IF 节点区分分支（main/staging/dev），分别部署到不同服务器
部署通知：在 SSH 节点后增加企业微信/钉钉/Slack 节点，部署成功后自动发送通知
版本回滚：增加 Code 节点解析 payload 中的 commit ID，支持一键回滚

n8n 的灵活性远超传统 CI/CD 工具——它不仅能做部署，还能串联通知、数据库更新、文件管理等跨系统自动化任务。

九、总结

本文从零开始，在 WSL2 + Docker 环境下完成了 n8n 的部署，并构建了一条完整的 GitHub Push 自动部署工作流。

核心要点回顾：

n8n 是开源、自托管的自动化工具，适合轻量级 CI/CD 场景
Docker Compose 是推荐的部署方式，数据持久化、易于维护
Webhook 节点作为触发器，配合 IF 节点实现分支过滤
SSH 节点远程执行部署命令，是整个自动化的执行核心
部署到公网时务必注意 Webhook 安全防护

比起手动 SSH 登录部署，这套方案能节省 80% 以上的重复操作时间。如果你的项目还在用“手动作业”，不妨花 30 分钟配置 n8n，把精力留在更重要的代码上。

本文实测环境：Windows 11 + WSL2 + Docker Desktop + n8n 1.x + Ubuntu 24.04 部署服务器。更多自动化实战文章，欢迎访问 MACS Dev Hub。如果你在配置中遇到问题，欢迎在评论区留言交流。

n8n 自托管部署教程、GitHub Webhook 自动部署、n8n SSH 远程执行命令、开源 CI/CD 轻量级方案、Docker Compose 搭建 n8n、n8n GitHub push 触发工作流、Windows WSL2 n8n 配置、Java Spring Boot 自动部署方案 2026

用 n8n 自建自动化：GitHub Push 后自动部署到服务器

前言