跳到主要内容

Jenkins Agent Linux 系统服务安装指南

· 阅读需 6 分钟
XingHunm
XingHunm
Tech Enthusiast

本文档详细介绍如何在 Linux 系统上将 Jenkins Agent 配置为 systemd 系统服务，实现开机自动启动。涵盖 Java 17 安装、服务配置、故障排查等完整流程。

1. 前置条件​

  • Linux 系统（支持 systemd）
  • sudo 权限
  • 网络连接（用于下载 Java）
  • Jenkins 服务端的 URL 和 Secret

2. 安装步骤​

2.1 步骤 1: 安装 Java 17​

Jenkins Agent 需要 Java 17 或更高版本。检查系统中的 Java 版本：

java -version

如果系统没有 Java 或版本低于 17，需要安装 Java 17。

方法 1: 从 Adoptium 下载安装（推荐）​

# 创建临时目录
cd ~
mkdir -p java-install
cd java-install

# 下载 OpenJDK 17
wget https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.10%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.10_7.tar.gz

# 解压
tar -xzf OpenJDK17U-jdk_x64_linux_hotspot_17.0.10_7.tar.gz

# 安装到系统目录
sudo mv jdk-17.0.10+7 /usr/local/jdk-17

# 验证安装
/usr/local/jdk-17/bin/java -version

2.2 步骤 2: 准备 Agent 文件​

  1. 创建工作目录
mkdir -p /home/xhm/jenkins
cd /home/xhm/jenkins
  1. 下载 agent.jar

从 Jenkins 服务端下载 agent.jar 文件，或使用已有的 agent.jar，确保文件位于：

/home/xhm/jenkins/agent.jar

2.3 步骤 3: 创建服务文件​

创建 systemd 服务文件 /home/xhm/jenkins/jenkins-agent.service：

sudo nano /home/xhm/jenkins/jenkins-agent.service

服务文件内容如下（请根据实际情况修改相关参数）：

[Unit]
Description=Jenkins Agent Service
After=network.target
Wants=network.target

[Service]
Type=simple
User=xhm
Group=xhm
WorkingDirectory=/home/xhm/jenkins
ExecStart=/usr/local/jdk-17/bin/java -jar /home/xhm/jenkins/agent.jar -url http://192.168.20.35:11080/ -secret 9e96e61eba4156e1076d77375aaefde46f99721cec6dcdsafascddaa8091d721b05 -name "linux-agent" -webSocket -workDir "/home/xhm/jenkins"
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=jenkins-agent

# Environment variables (if needed)
Environment=JAVA_HOME=/usr/local/jdk-17
Environment=PATH=/usr/local/jdk-17/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/xhm/jenkins

[Install]
WantedBy=multi-user.target

配置说明​

服务文件参数详解​
参数说明示例
Type服务类型simple (简单类型)
User/Group运行用户/组xhm/xhm
WorkingDirectory工作目录/home/xhm/jenkins
ExecStart启动命令Java 启动 agent.jar 的命令
Restart重启策略always (总是重启)
RestartSec重启延迟10 (10 秒)
Agent 参数说明​
参数说明必需
-urlJenkins 服务端 URL是
-secretAgent 连接密钥是
-nameAgent 名称否
-webSocket使用 WebSocket 连接否
-workDirAgent 工作目录否
安全设置​

服务文件中包含以下安全设置：

  • NoNewPrivileges=true: 禁止获取新权限
  • PrivateTmp=true: 使用私有临时目录
  • ProtectSystem=strict: 保护系统目录
  • ProtectHome=read-only: 保护家目录为只读
  • ReadWritePaths: 指定可写路径

2.4 步骤 4: 安装并启用服务​

  1. 复制服务文件到 systemd 目录
sudo cp /home/xhm/jenkins/jenkins-agent.service /etc/systemd/system/
  1. 重新加载 systemd 配置
sudo systemctl daemon-reload
  1. 启用开机自启动
sudo systemctl enable jenkins-agent.service
  1. 启动服务
sudo systemctl start jenkins-agent.service

2.5 步骤 5: 验证服务​

  1. 检查服务状态
sudo systemctl status jenkins-agent

正常运行的输出应该显示：

● jenkins-agent.service - Jenkins Agent Service
   Loaded: loaded (/etc/systemd/system/jenkins-agent.service; enabled)
   Active: active (running) since ...
  1. 查看服务日志
# 查看实时日志
sudo journalctl -u jenkins-agent -f

# 查看最近50条日志
sudo journalctl -u jenkins-agent -n 50

# 查看今天的日志
sudo journalctl -u jenkins-agent --since today

3. 服务管理​

3.1 常用命令​

# 启动服务
sudo systemctl start jenkins-agent

# 停止服务
sudo systemctl stop jenkins-agent

# 重启服务
sudo systemctl restart jenkins-agent

# 查看服务状态
sudo systemctl status jenkins-agent

# 查看服务日志
sudo journalctl -u jenkins-agent -f

# 启用开机自启动
sudo systemctl enable jenkins-agent

# 禁用开机自启动
sudo systemctl disable jenkins-agent

# 检查服务是否开机自启
sudo systemctl is-enabled jenkins-agent

3.2 服务自动重启​

服务配置中已设置 Restart=always，当服务异常退出时会在 10 秒后自动重启。

4. 故障排查​

4.1 问题 1: 服务无法启动​

症状: systemctl status 显示 failed 或 inactive (dead)

排查步骤:

  1. 查看详细日志：

    sudo journalctl -u jenkins-agent -n 100 --no-pager

  2. 检查 Java 路径是否正确：

    ls -la /usr/local/jdk-17/bin/java

  3. 检查 agent.jar 是否存在：

    ls -la /home/xhm/jenkins/agent.jar

  4. 检查工作目录权限：

    ls -ld /home/xhm/jenkins

4.2 问题 2: Java 版本不匹配​

症状: 日志中出现 UnsupportedClassVersionError

错误示例:

java.lang.UnsupportedClassVersionError: class file version 61.0 ...
this version of the Java Runtime only recognizes class file versions up to 55.0

解决方案:

  • class file version 61.0 表示需要 Java 17
  • 55.0 表示当前 Java 版本是 11
  • 需要安装 Java 17 或更高版本（参考步骤 1）

4.3 问题 3: 无法连接到 Jenkins​

症状: 日志中显示连接失败

排查步骤:

  1. 检查网络连接：

    ping 192.168.20.35
    curl -I http://192.168.20.35:18080/

  2. 验证 URL 和 Secret 是否正确

  3. 检查防火墙设置：

    sudo ufw status

  4. 查看详细错误信息：

    sudo journalctl -u jenkins-agent -f

4.4 问题 4: 权限问题​

症状: 日志中显示 Permission denied

解决方案:

  1. 检查文件所有权：

    sudo chown -R xhm:xhm /home/xhm/jenkins

  2. 检查文件权限：

    chmod 644 /home/xhm/jenkins/agent.jar

4.5 问题 5: 服务频繁重启​

症状: 服务状态显示 activating (auto-restart)

排查步骤:

  1. 查看详细错误日志
  2. 检查 Java 路径和 agent.jar 路径是否正确
  3. 检查工作目录是否可写
  4. 检查 Jenkins 服务端是否可访问

5. 总结​

完成以上步骤后，Jenkins Agent 已配置为系统服务，具备以下特性：

✅ 开机自动启动 ✅ 服务异常时自动重启 ✅ 日志记录到 systemd journal ✅ 安全配置限制权限 ✅ 易于管理和监控

如遇到问题，请参考故障排查章节或查看详细日志。