Jenkins + Gitee 自动化部署 Vue 项目完整指南

前言

本文将从零开始，手把手教你搭建一套完整的自动化部署系统。当你把代码推送到 dev 分支时，Jenkins 会自动拉取代码、安装依赖、构建项目，并部署到你的服务器。整个过程无需人工干预。

本文的所有配置和代码都经过实际验证，并记录了我在搭建过程中遇到的坑和解决方案。

一、环境准备

1.1 你需要准备什么

• 一台 Linux 服务器（本文使用 CentOS 7，阿里云服务器）

• 一个 Gitee 仓库（私有或公开均可）

• 一个 Vue 项目（其他前端项目原理相同）

1.2 架构说明

开发者推送代码 → Gitee Webhook → Jenkins → 拉取代码 → 构建 → 部署到服务器

二、Jenkins 安装与基础配置

2.1 使用 Docker 安装 Jenkins

1. 安装 Docker：在宝塔面板的"软件商店"中搜索并安装 Docker。

2. 创建 Jenkins 容器：在docker中搜索jenkins然后安装

3. 镜像选择 ：导航中的本地镜选择 jenkins/jenkins:lts（长期支持版）。

4. 创建容器

   • 容器名称：jenkins（随便起）

   • 端口映射：主机 8081 映射容器 8080（jenkins内部监听的端口是8080，所以后面这里我改成8080才行）

   • 目录挂载：主机 /www/jenkins_home 映射容器 /var/jenkins_home

   • 环境变量：JAVA_OPTS=-Xms256m -Xmx1024m

2.2 遇到的问题与处理

问题现象	原因分析	解决方法
容器启动后立即暂停，日志报错 Permission denied	挂载的目录 /www/jenkins_home 权限不足，容器内 Jenkins 用户（UID 1000）无法写入。	修复权限 ： sudo chown -R 1000:1000 /www/jenkins_home sudo chmod -R 755 /www/jenkins_home 或者： 选择/www/jenkins_home右键，修改权限
外网无法访问 http://公网IP:8081	三重防火墙 均需开放端口： 1. 云服务商安全组 2. 宝塔面板安全	1. 阿里云 ：控制台 → 安全组 → 入方向添加 8081。 2. 宝塔 ：安全 → 添加端口规则 8081。 3. 系统防火墙 ：
端口映射	jenkins内部监听的端口是8080	我的方案是8081/8080

2.3 安装必要插件

进入 Jenkins → 系统管理 → 插件管理 → 可选插件，安装以下插件：

插件名称	用途
NodeJS Plugin	提供 Node.js 环境
Publish Over SSH	SSH 传输文件到服务器
Generic Webhook Trigger	接收 Gitee Webhook 请求
Git Plugin	拉取代码（通常已安装）

三、配置 Jenkins 全局工具

3.1 配置 Node.js

进入 系统管理 → 全局工具配置 → 找到 NodeJS 区域：

• 点击 Add NodeJS

• Name ：jhf-nodejs（可自定义，后续 Pipeline 中需保持一致）

• 勾选 Install automatically

• Version ：选择 NodeJS 16.x.x 或更高版本

3.2 配置 SSH 部署（关键步骤）

进入 系统管理 → 系统配置 → 找到 Publish over SSH 区域。

3.2.1 生成 SSH 密钥对

# 在 Jenkins 服务器上生成密钥
ssh-keygen -t rsa -b 4096 -f ~/jenkins_deploy_key -N ""

3.2.2 将公钥添加到目标服务器

# 将公钥复制到目标服务器
ssh-copy-id -i ~/jenkins_deploy_key.pub root@你的服务器IP

3.2.3 将私钥添加到 Jenkins

由于 Jenkins 运行在 Docker 容器中，需要将私钥复制到容器内：

# 复制私钥到容器
docker cp ~/jenkins_deploy_key my-jenkins:/tmp/id_rsa

# 进入容器配置
docker exec -it my-jenkins bash

# 在容器内执行
mkdir -p /var/jenkins_home/.ssh
cp /tmp/id_rsa /var/jenkins_home/.ssh/id_rsa
chmod 700 /var/jenkins_home/.ssh
chmod 600 /var/jenkins_home/.ssh/id_rsa
chown -R jenkins:jenkins /var/jenkins_home/.ssh

# 添加服务器指纹
ssh-keyscan -H 你的服务器IP >> /var/jenkins_home/.ssh/known_hosts

# 测试连接
ssh -i /var/jenkins_home/.ssh/id_rsa root@你的服务器IP "echo '连接成功'"

# 退出容器
exit

3.2.4 在 Jenkins 界面配置 SSH Server

在 Publish over SSH 配置中：

• Key ：填写容器内私钥路径 /var/jenkins_home/.ssh/id_rsa

• 点击 Add 添加服务器：

  • Name ：jhf-server（后续 Pipeline 中使用）

  • Hostname：你的服务器 IP

  • Username ：root

  • Remote Directory ：/www/wwwroot（基础路径）

  • 点击 Advanced ，确保 Use password authentication 未勾选

点击 Test Configuration ，确认显示 Success。

四、添加 Gitee 凭证（私有仓库需要）

如果仓库是私有的，需要添加 Gitee 账号凭证：

1. 进入 系统管理 → Manage Credentials → 全局 → Add Credentials

2. 选择 Username with password

3. 填写：

   • Username：Gitee 登录名

   • Password：Gitee 密码

   • ID ：gitee-credentials（后续 Pipeline 中使用）

---

五、创建 Jenkins 流水线任务

5.1 新建任务

1. 点击 Jenkins 首页 新建任务

2. 输入任务名：test-vue-app

3. 选择 流水线（Pipeline），点击确定

5.2 配置构建触发器

在任务配置页面，找到 构建触发器

☑ Generic Webhook Trigger
   Token: test-vue-app-token
   ☑ Print post content  (可选，用于调试)

注意：

• 不要添加任何 Post content parameters

• 不要添加任何 Optional filter

• 分支过滤交给 Gitee 的 Webhook 配置

5.3 配置流水线脚本

向下滚动到 流水线 区域，选择 Pipeline script，粘贴以下代码：

pipeline {
    agent any
    
    tools {
        nodejs 'jhf-nodejs'  // 必须与全局工具配置中的名称一致
    }
    
    environment {
        // ========== 请修改为你的实际配置 ==========
        GIT_URL = 'https://gitee.com/你的用户名/你的项目.git'
        GIT_BRANCH = 'dev'
        SSH_SERVER = 'jhf-server'  // Publish over SSH 中配置的服务器名称
        REMOTE_DIR = '/my-font-project/test-vue-app'  // 相对路径，会拼接到全局 Remote Directory
        // ============================================
    }
    
    stages {
        stage('1. 拉取代码') {
            steps {
                echo "正在从 ${GIT_BRANCH} 分支拉取代码..."
                git branch: "${GIT_BRANCH}", 
                    url: "${GIT_URL}", 
                    credentialsId: 'gitee-credentials'  // 公开仓库可删除此行
            }
        }
        
        stage('2. 安装依赖') {
            steps {
                echo "正在安装项目依赖..."
                sh 'npm install --registry=https://registry.npmmirror.com'
            }
        }
        
        stage('3. 构建项目') {
            steps {
                echo "正在构建项目..."
                sh 'npm run build'
            }
        }
        
        stage('4. 部署到服务器') {
            steps {
                echo "正在部署到服务器 ${SSH_SERVER}..."
                sshPublisher(
                    publishers: [
                        sshPublisherDesc(
                            configName: "${SSH_SERVER}",
                            transfers: [
                                sshTransfer(
                                    sourceFiles: 'dist/**',
                                    removePrefix: 'dist',
                                    remoteDirectory: 'my-font-project/test-vue-app',
                                    execCommand: """
                                        echo "=========================================="
                                        echo "✅ 部署完成！"
                                        echo "=========================================="
                                        ls -la /www/wwwroot${REMOTE_DIR}
                                    """
                                )
                            ]
                        )
                    ]
                )
            }
        }
    }
    
    post {
        success {
            echo '🎉 恭喜！构建和部署全部成功！'
        }
        failure {
            echo '❌ 抱歉，构建或部署失败了，请查看控制台日志。'
        }
    }
}

5.4 保存配置

点击页面底部 保存 按钮。

六、配置 Gitee Webhook

6.1 获取 Webhook URL

http://你的服务器IP:8081/generic-webhook-trigger/invoke?token=test-vue-app-token

6.2 在 Gitee 添加 Webhook

1. 进入 Gitee 仓库 → 管理 → WebHooks → 添加 webhook

2. 填写：

   • URL：上面的地址

   • 触发条件 ：勾选 Push

   • 监听分支 ：dev（关键！分支过滤在这里配置）

3. 点击 添加

6.3 测试 Webhook

点击刚添加的 webhook 旁边的 测试 按钮，应返回 200 OK。

七、验证自动化部署

7.1 手动触发测试

在 Jenkins 任务页面点击 立即构建，查看控制台输出，确认构建成功。

7.2 服务器验证

ssh root@你的服务器IP
ls -la /www/wwwroot/my-font-project/test-vue-app/

7.3 自动触发测试

# 在本地项目目录
git checkout dev
echo "// test auto deploy" >> src/main.js
git add .
git commit -m "test: 测试自动部署"
git push origin dev

观察 Jenkins，5-10 秒后应自动开始构建。

八、踩坑记录与解决方案

坑 1：Publish over SSH 连接失败

现象 ：Auth fail for methods 'publickey,...'

原因：Jenkins 运行在 Docker 容器中，私钥文件需要放在容器内，且权限必须正确。

解决：

docker cp 私钥文件 my-jenkins:/tmp/
docker exec -it my-jenkins bash
chmod 600 /var/jenkins_home/.ssh/id_rsa
chown jenkins:jenkins /var/jenkins_home/.ssh/id_rsa

坑 2：Webhook 配置了 Optional filter 导致不触发

现象：Gitee 测试返回 200，但 Jenkins 不构建

原因：Optional filter 配置错误，过滤掉了所有请求

解决：保持 Post content parameters 和 Optional filter 为空白，分支过滤在 Gitee 的 Webhook 配置中完成。

坑 3：部署路径错误

现象：文件传输到了错误的位置

原因：混淆了全局 Remote Directory 和流水线中的 remoteDirectory

解决：

• 全局配置：/www/wwwroot（基础路径）

• 流水线 remoteDirectory：my-font-project/test-vue-app（相对路径）

• 最终路径 = /www/wwwroot/my-font-project/test-vue-app

坑 4：Node.js 名称不匹配

现象 ：No tool named 'xxx' found

解决 ：确保流水线中的 nodejs 'jhf-nodejs' 与全局工具配置中的 Name 完全一致。

---

九、常见问题 FAQ

Q1：如何只监听特定分支？

在 Gitee Webhook 配置中填写 监听分支，不要在 Jenkins 中配置过滤。

Q2：如何查看构建日志？

进入任务 → 点击构建号 → 控制台输出

Q3：构建失败如何排查？

1. 查看控制台输出中的红色错误信息

2. 常见原因：npm install 失败、npm run build 脚本错误、部署目录权限不足

Q4：如何更新部署后的文件？

每次推送代码到 dev 分支，会自动覆盖旧文件。如果需要保留某些文件，可以在 execCommand 中添加备份逻辑。

---

十、总结

通过以上步骤，我们完成了：

1. ✅ Jenkins 的安装与配置

2. ✅ SSH 远程部署配置

3. ✅ Node.js 环境配置

4. ✅ Gitee Webhook 配置

5. ✅ 完整的流水线脚本

6. ✅ 自动化部署验证

现在，当你推送代码到 dev 分支时，Jenkins 会自动完成打包和部署。这套流程可以扩展到其他前端项目，甚至后端项目，只需修改构建命令即可。

---

附录：完整配置速查

配置项	值
Jenkins 访问地址	http://服务器IP:8081
Jenkins 容器名	my-jenkins
Node.js 工具名	jhf-nodejs
SSH Server 名称	jhf-server
全局 Remote Directory	/www/wwwroot
Gitee 仓库	https://gitee.com/用户名/项目.git
监听分支	dev
Webhook Token	test-vue-app-token
部署路径	/www/wwwroot/my-font-project/test-vue-app

---

希望这篇文章能帮助其他开发者顺利搭建自己的自动化部署系统。如果有任何问题，欢迎交流讨论！

本回答由 AI 生成，内容仅供参考，请仔细甄别。