搞了两天终于搞明白了——Jenkins 接 Git 自动构建，就该这么玩

Jenkins 是个啥，先简单说一下

Jenkins 本质上是个自动化调度平台，你可以把它理解成一个"管家"，代码一推送，它就自动拉代码、跑测试、打包、部署，全套走完，不需要人盯着。

它跟 Git 集成的核心逻辑是这样的：

1. 1. 你在 GitHub/GitLab 上配置一个 Webhook
2. 2. 代码一 push，GitHub 就给 Jenkins 发一个 HTTP 请求
3. 3. Jenkins 收到请求，触发对应的构建任务
4. 4. 构建任务里你可以写任何操作：拉代码、编译、测试、部署……

整个链路就这样，说起来简单，真配起来细节很多。

安装 Jenkins，这步别急

我用的是 Ubuntu 22.04，先记一下基础环境：

OS: Ubuntu 22.04 LTS
Java: OpenJDK 17
Jenkins: 2.440.x (LTS)

Jenkins 是 Java 写的，所以 Java 得先装好。我之前装过 11，后来发现新版 Jenkins 已经要求 17 了，所以建议直接上 17。

sudo apt-get update
sudo apt-get install -y openjdk-17-jdk

装完验证一下：

java -version
# openjdk version "17.0.x" ...

然后装 Jenkins 本体：

# 导入 Jenkins 的 GPG key
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | \
  sudo tee /usr/share/keyrings/jenkins-keyring.asc > /dev/null

# 添加 Jenkins apt 源
echo deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
  https://pkg.jenkins.io/debian-stable binary/ | \
  sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

sudo apt-get update
sudo apt-get install -y jenkins

装完启动：

sudo systemctl start jenkins
sudo systemctl enable jenkins
sudo systemctl status jenkins

看到 active (running) 就说明起来了。然后浏览器访问 http://你的服务器IP:8080，会让你输初始密码。

初始密码在这里：

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

复制进去，然后会让你选择安装插件。这里我建议选"推荐插件"，会帮你把常用的都装好，省事。然后创建管理员账号，基本配置就完了。

有一个小坑：如果你的服务器在云上，记得放行 8080 端口的安全组规则，不然浏览器访问不到，然后你就开始怀疑是不是 Jenkins 没装好，其实根本没到那步……

装 Git 插件

Jenkins 本身不自带 Git 支持，需要装插件。进管理界面之后：

Manage Jenkins → Manage Plugins → Available plugins

搜索 Git，找到 Git plugin，勾上装就完了。装完不用重启，大部分插件热加载就行。

顺手也可以装一下 GitHub Integration Plugin，后面配 Webhook 会用到。

另外服务器上也要确保 git 命令行工具是安装了的：

sudo apt-get install -y git
git --version

Jenkins 调用 Git 其实走的是系统的 git 命令，如果没装，构建的时候会报错找不到 git。这个我在一台新机器上翻过车，检查了半天 Jenkins 配置，结果是系统根本没装 git……

创建构建任务，把仓库关联上

Jenkins 首页点 "New Item"（新建任务），输入任务名，选 "Freestyle project"（自由风格项目）。

当然你也可以选 Pipeline，但初学的话，Freestyle 更直观，配置都在 UI 上，点点就完了。Pipeline 那个后面说。

进到任务配置页：

源代码管理 → 选 Git

然后填仓库地址。这里有个问题——如果是私有仓库，你需要配 Credentials（凭据）。公开仓库可以跳过这步。

私有仓库配凭据的方式有两种：

• • 用户名 + 密码（GitHub 现在不支持密码了，要用 Personal Access Token 代替密码）
• • SSH 密钥

我更推荐 SSH 密钥，稳定，不容易过期。流程是这样的：

在 Jenkins 服务器上生成密钥对：

sudo -u jenkins ssh-keygen -t ed25519 -C "jenkins@your-server"
# 一路回车，不要设密码

把公钥（/var/lib/jenkins/.ssh/id_ed25519.pub 的内容）添加到 GitHub 的 Deploy Keys 里。

把私钥内容添加到 Jenkins 的 Credentials 里：Manage Jenkins → Credentials → Global → Add Credentials，类型选 SSH Username with private key，粘贴私钥内容保存。

然后回到任务配置页，Credentials 下拉框里选刚才添加的那条。

仓库 URL 用 SSH 格式：git@github.com:your-username/your-repo.git

Branch 那里默认是 */master，如果你的主分支叫 main，改成 */main。

配置 Webhook，这是最关键的一步

Webhook 的意思是：当代码仓库发生某个事件（比如 push），仓库平台主动通知 Jenkins。这样 Jenkins 不用轮询，实时响应。

在 Jenkins 这边：

任务配置页 → 构建触发器 → 勾选 "GitHub hook trigger for GITScm polling"

保存。

在 GitHub 那边：

进你的代码仓库 → Settings → Webhooks → Add webhook

• • Payload URL：http://你的Jenkins地址:8080/github-webhook/ 注意后面那个斜杠别漏了，漏了就 404
• • Content type：选 application/json
• • 触发事件：选 Just the push event 就够了
• • 勾上 Active

点 Add webhook 保存。

保存之后，GitHub 会立刻发一个 ping 请求给 Jenkins，如果看到绿色的对勾，说明通了。如果是红色报错，大概率是两种情况：

1. 1. Jenkins 地址填错了，或者端口没放行
2. 2. Jenkins 服务器有防火墙拦截

公网服务器一般都没问题，如果是内网机器，就得用内网穿透工具，比如 frp 或者 ngrok，把内网的 Jenkins 暴露到公网，GitHub 才能访问到。这个坑我在本地测试环境就踩过，花了一下午搞 frp 配置，绕了一大圈。

加上构建步骤，让它真正干活

光触发还不够，还得告诉 Jenkins 触发之后做什么。

任务配置页 → Build Steps → Add build step → Execute shell

比如最简单的，就是拉完代码之后重启一个服务：

#!/bin/bash
echo "开始部署..."
cd /var/www/myapp

# 安装依赖（如果是 Node.js 项目）
npm install --production

# 重启应用
pm2 restart myapp

echo "部署完成"

或者你是 Java 项目，可能长这样：

cd $WORKSPACE
mvn clean package -DskipTests
cp target/myapp.jar /opt/deploy/
systemctl restart myapp

$WORKSPACE 是 Jenkins 内置变量，指向当前 Job 的工作目录，代码就拉在这里面。

说说 Jenkinsfile，更专业的玩法

上面那种 Freestyle + Execute shell 的方式能用，但配置都在 Jenkins UI 里，迁移麻烦，也没法版本控制。

更推荐的做法是在代码仓库根目录放一个 Jenkinsfile，把整个 CI/CD 流程都定义在里面，跟着代码一起走。

新建任务的时候选 Pipeline，配置里选 Pipeline script from SCM，Jenkins 就会从代码仓库里自动读取 Jenkinsfile。

一个典型的 Jenkinsfile 大概是这样：

pipeline {
    agent any

    environment {
        APP_NAME = 'myapp'
        DEPLOY_PATH = '/var/www/myapp'
    }

    stages {
        stage('拉取代码') {
            steps {
                checkout scm
            }
        }

        stage('安装依赖') {
            steps {
                sh 'npm install --production'
            }
        }

        stage('运行测试') {
            steps {
                sh 'npm test'
            }
            post {
                failure {
                    echo '测试失败，停止部署'
                }
            }
        }

        stage('部署') {
            steps {
                sh """
                    cp -r . ${DEPLOY_PATH}
                    pm2 restart ${APP_NAME}
                """
            }
        }
    }

    post {
        success {
            echo '部署成功！'
        }
        failure {
            echo '流水线执行失败，请检查日志'
        }
    }
}

Groovy 语法，刚开始看会有点陌生，但上手之后非常顺手。每个 stage 对应一个阶段，失败会在控制台清楚地标出哪个阶段挂了，排查问题方便很多。

测试整个流程

配置完了，来验证一下。

找一个无关紧要的文件，比如 README.md，随便改一行，然后：

git add .
git commit -m "test: 测试 Jenkins 自动构建"
git push origin main

然后切到 Jenkins 界面，看对应的 Job，应该马上就有新的构建记录出现了。点进去看构建日志，能看到完整的执行过程。

如果没有触发，排查顺序：

1. 1. 先去 GitHub Webhook 那里看发送历史，有没有发出去，有没有收到响应
2. 2. 再看 Jenkins 这边的 System Log，有没有收到请求
3. 3. 检查任务配置里的触发器有没有勾上

大部分问题都出在网络连通性和配置遗漏上，耐心排查，基本都能找到。

生产环境还要注意安全

上面说的都是功能层面，如果是生产环境跑 Jenkins，安全这块不能忽视。

访问控制要做好。 Jenkins 默认装完之后，如果不配置权限，内网里任何人打开页面都能操作。进 Manage Jenkins → Security → Authorization，建议用 Matrix-based security，给不同角色配不同权限。

Jenkins 的端口别直接暴露公网。 最好在前面加个 Nginx 做反向代理，同时配上 HTTPS。暴露在公网的 Jenkins 如果没加防护，会被各种扫描器盯上，说不定哪天就被跑进去了。

Nginx 配置大概这样：

server {
    listen 80;
    server_name jenkins.your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name jenkins.your-domain.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

敏感信息别硬编码在 Jenkinsfile 里。 数据库密码、API Key 这类东西，放到 Jenkins 的 Credentials 管理里，在 Jenkinsfile 里用变量引用：

withCredentials([string(credentialsId: 'db-password', variable: 'DB_PASS')]) {
    sh 'echo $DB_PASS'  // 实际日志里会显示 ****，不会泄露
}

定期备份 Jenkins。 Jenkins 的配置都在 /var/lib/jenkins/ 目录下，把这个目录定期备份就行，万一机器挂了，换台机器装上 Jenkins 再把目录还原，基本能恢复。

总结

整个流程捋一下：

装 Jenkins → 装 Git 插件 → 创建 Job 关联仓库 → 配 Webhook → 写构建步骤 → 验证测试

这条链路打通之后，开发 push 代码，Jenkins 自动跑，出问题控制台有日志，不用再人肉盯着了。我们团队用了这套之后，部署频次从"每天憋一次大版本"变成了"随时可以发布"，开发那边也更有信心提交代码了。

当然这篇只是讲了基础集成，Jenkins 能做的远不止这些——多分支 Pipeline、Blue Ocean 可视化界面、与 Docker/K8s 集成、钉钉/企业微信通知……后面有机会再一块写。

如果你在配置过程中遇到问题，欢迎在评论区留言，我看到了都会回复。觉得有用的话帮忙转发一下，让更多同行少走弯路。