1. 文档说明

1.1 适用环境

系统版本：Debian（兼容 Debian 10/11/12 及以上版本，本文以 Debian 12 为例）

权限要求：root 用户（或具备 sudo 权限的用户）

依赖环境：Java 17（Jenkins 稳定版必需，Debian 12 及以上推荐此版本；Debian 12 以下推荐 Java 17）

目标：完成 Jenkins 官方稳定版安装、端口配置、用户名修改，确保服务正常运行，可正常访问使用。

1.2 前置说明

1.  禁止直接编辑 Jenkins 系统服务文件（/lib/systemd/system/jenkins.service），系统会提示“This file is managed by systemd(1). Do NOT edit this file manually!”，如需修改配置，需通过 systemctl edit jenkins 命令操作。

2.  全程命令可直接复制粘贴执行，避免手动输入导致错误；执行过程中若出现权限提示，确认当前为 root 用户即可。

3.  参考官方仓库：https://pkg.jenkins.io/debian-stable/，确保安装包为官方稳定版，避免第三方包带来的安全风险。

2. 部署前准备

2.1 切换 root 用户（可选，若已为 root 可跳过）

执行以下命令切换至 root 用户，避免后续操作权限不足：

bash sudo -i

2.2 更新系统软件包

更新本地软件包索引，确保系统软件处于最新状态，避免依赖冲突：

bash apt update && apt upgrade -y

2.3 安装依赖工具

安装 wget（用于下载 Jenkins 密钥）和 fontconfig（Java 依赖）：

bash apt install -y wget fontconfig

3. 安装 Java 环境（Jenkins 必需）

3.1 安装 OpenJDK 17

Jenkins 稳定版需依赖 Java 17 运行环境，执行以下命令安装：

bash apt install -y openjdk-17-jre

说明：Debian 12 及以上版本直接安装 openjdk-17-jre；Debian 12 以下版本可替换为 openjdk-17-jre（需确认软件源支持）。

3.2 验证 Java 安装成功

执行以下命令查看 Java 版本，确认安装成功：

bash java -version

成功提示（版本号可略有差异，只要包含 17 即可）：

bash openjdk version "17.0.9" 2023-10-17 OpenJDK Runtime Environment (build 17.0.9+9-Debian-1deb12u1) OpenJDK 64-Bit Server VM (build 17.0.9+9-Debian-1deb12u1, mixed mode, sharing)

注意：禁止使用 java -v 命令（会报错），正确命令为 java -version。

4. 安装 Jenkins

4.1 导入 Jenkins 官方密钥

下载并导入 Jenkins 官方密钥，确保软件包验证通过：

bash wget -O /etc/apt/keyrings/jenkins-keyring.asc https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key

4.2 添加 Jenkins 软件源

将 Jenkins 官方软件源添加到系统，便于后续安装和升级：

bash echo "deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/" | tee /etc/apt/sources.list.d/jenkins.list > /dev/null

4.3 安装 Jenkins

更新软件包索引后，执行安装命令：

bash apt update apt install -y jenkins

4.4 启动 Jenkins 并设置开机自启

安装完成后，启动 Jenkins 服务，并设置开机自启（确保服务器重启后 Jenkins 自动运行）：

bash systemctl start jenkins systemctl enable jenkins

4.5 验证 Jenkins 服务状态

执行以下命令，查看 Jenkins 服务是否正常运行：

bash systemctl status jenkins

成功提示：显示“active (running)”，说明 Jenkins 服务已正常启动。

5. Jenkins 基础配置

5.1 查看初始管理员密码

Jenkins 安装完成后，会生成初始管理员密码，用于首次登录：

bash cat /var/lib/jenkins/secrets/initialAdminPassword

复制输出的一串随机字符（如：a1b2c3d4e5f6g7h8i9j0），后续登录需使用。

5.2 访问 Jenkins 网页界面

1.  打开浏览器，输入访问地址：http://服务器IP:8080（默认端口为 8080）

2.  粘贴步骤 5.1 中获取的初始管理员密码，点击“继续”。

3.  首次登录后，选择“安装推荐的插件”（新手推荐），等待插件安装完成（约 5-10 分钟，取决于网络速度）。

4.  插件安装完成后，创建管理员账号（设置用户名、密码、邮箱），完成 Jenkins 初始化。

6. 常用配置修改（端口、用户名）

6.1 修改 Jenkins 端口号（推荐）

使用 vi 直接编辑 Jenkins 配置（端口等），需编辑 自定义配置文件（推荐）或服务配置文件（不推荐），具体步骤如下：

方法1：vi 编辑自定义配置文件（推荐，安全无风险） 该文件是通过 systemctl edit jenkins 生成的，专门用于修改 Jenkins 服务配置，操作如下：

1. 执行 vi 命令打开自定义配置文件：

   vi /etc/systemd/system/jenkins.service.d/override.conf

2. 按 i 进入编辑模式，添加端口配置（替换 8081 为自定义端口）：

   Environment="JENKINS_PORT=8889"

3. [Service] 说明：若需修改其他配置（如运行用户），可在此文件中添加对应配置项。

4. 保存退出：按 Esc 退出编辑模式，输入 :wq 回车保存；若文件为空且无需编辑，输入 :q! 强制退出。

5. 重新加载配置并重启 Jenkins，使修改生效： systemctl daemon-reload systemctl restart jenkins

   # 1. 重载 systemd 配置（解决警告）
   sudo systemctl daemon-reload
   
   # 2. 启动 Jenkins
   sudo systemctl start jenkins
   
   # 3. 设置开机自启
   sudo systemctl enable jenkins
   
   # 4. 验证 Jenkins 状态（查看是否正常运行）
   sudo systemctl status jenkins
   

     

6.2 修改 Jenkins 登录用户名

推荐通过网页界面修改（安全、简单），操作如下：

1. 登录 Jenkins 网页，点击右上角的当前用户名（如 admin）。

1. 在下拉菜单中选择“设置（Configure）”。

1. 在“Full name”处修改显示名称，在“Password”处可修改登录密码（可选）。

1. 点击页面底部的“Save”保存修改，修改立即生效。

说明：不推荐修改 Jenkins 运行的系统用户（如 jenkins 用户），若有特殊需求，可联系运维人员操作。

7. 常见问题排查

7.1 Java 版本错误

报错：Jenkins 启动失败，日志提示“Java version is too low”。

解决：卸载低版本 Java，重新安装 openjdk-17-jre，命令如下：

bash apt remove -y openjdk-* apt install -y openjdk-17-jre

7.2 端口冲突

报错：Jenkins 启动失败，日志提示“Address already in use”。

解决：执行以下命令查看端口占用情况，关闭占用端口的服务，或修改 Jenkins 端口：

bash # 查看 8080 端口占用情况（替换为你的端口） netstat -tulpn | grep 8080 # 关闭占用端口的服务（如进程 ID 为 1234） kill -9 1234 # 或修改 Jenkins 端口（参考 6.1 步骤）

7.3 密钥导入失败

报错：执行 wget 下载密钥时提示“Connection refused”或“404 Not Found”。

解决：检查服务器网络是否正常，确保能访问外网，重新执行密钥下载命令：

bash wget -O /etc/apt/keyrings/jenkins-keyring.asc https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key

7.4 Jenkins 服务启动失败

解决：查看 Jenkins 日志，定位失败原因：

bash journalctl -u jenkins

根据日志提示修复（如权限不足、Java 未安装等），修复后重启服务：

bash systemctl restart jenkins

8. 后续操作建议

1.  定期更新 Jenkins 及插件：登录网页 → 系统管理 → 插件管理 → 检查更新，确保安全性和功能完整性。

2.  备份 Jenkins 配置：定期备份 /var/lib/jenkins 目录（Jenkins 所有配置、插件、数据均存储在此）。

3.  配置防火墙：若服务器开启防火墙，需开放 Jenkins 端口（如 8081），允许外部访问。

4.  参考官方文档：https://www.jenkins.io/doc/，了解更多高级配置和使用方法。

9. 文档版本

版本：V1.0

更新时间：2026-04-11

适用场景：Debian 系统 Jenkins 稳定版部署，适配新手及运维人员使用。