Mac 系统 Jenkins Agent 服务配置指南

本文档说明如何在 macOS 上配置 Jenkins Agent 服务，实现自动启动并防止息屏/休眠导致连接断开。通过 LaunchDaemon 和 caffeinate 命令确保服务稳定运行。

1. 核心原理

1.1 LaunchDaemon vs LaunchAgent

macOS 提供两种自动启动机制：

特性	LaunchDaemon	LaunchAgent
运行权限	root	当前用户
启动时机	系统启动时	用户登录时
配置位置	/Library/LaunchDaemons/	~/Library/LaunchAgents/
息屏影响	不受影响	可能断开
适用场景	系统级服务	用户级应用

Jenkins Agent 应使用 LaunchDaemon 以确保服务稳定运行且不受用户会话影响。

1.2 防休眠机制

使用 caffeinate 命令包裹 Jenkins Agent 进程，防止系统休眠导致网络断开：

caffeinate -s java -jar agent.jar [options]

参数说明：

• -s: 防止系统休眠（但允许屏幕息屏）
• 进程存活期间持续生效

2. 前置要求

1. Java 环境：已安装 JDK（Jenkins Agent 需要）
2. Jenkins 凭据：从 Jenkins Master 获取 Agent 连接信息
3. 管理员权限：配置 LaunchDaemon 需要 sudo 权限
4. 工作目录：准备 Jenkins 工作目录（如 /Users/xhm/jenkins）

3. 配置步骤

3.1 第一步：创建 Plist 配置文件

创建 org.jenkins.agent.plist 文件（建议先在用户目录创建，测试后再移动）：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- 服务唯一标识 -->
    <key>Label</key>
    <string>org.jenkins.agent</string>

    <!-- 使用 caffeinate 防休眠 -->
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/caffeinate</string>
        <string>-s</string>
        <string>/usr/bin/java</string>
        <string>-jar</string>
        <string>/Users/xhm/jenkins/agent.jar</string>
        <string>-url</string>
        <string>http://your-jenkins-server:8080/</string>
        <string>-secret</string>
        <string>YOUR_SECRET_KEY</string>
        <string>-name</string>
        <string>YOUR_AGENT_NAME</string>
        <string>-workDir</string>
        <string>/Users/xhm/jenkins</string>
    </array>

    <!-- 运行用户（保持与文件所有者一致）-->
    <key>UserName</key>
    <string>xhm</string>

    <!-- 工作目录 -->
    <key>WorkingDirectory</key>
    <string>/Users/xhm/jenkins</string>

    <!-- 自动启动 -->
    <key>RunAtLoad</key>
    <true/>

    <!-- 崩溃后自动重启 -->
    <key>KeepAlive</key>
    <true/>

    <!-- 标准输出日志 -->
    <key>StandardOutPath</key>
    <string>/Users/xhm/jenkins/jenkins-agent.log</string>

    <!-- 错误输出日志 -->
    <key>StandardErrorPath</key>
    <string>/Users/xhm/jenkins/jenkins-agent-error.log</string>

    <!-- 环境变量（可选）-->
    <key>EnvironmentVariables</key>
    <dict>
        <key>JAVA_HOME</key>
        <string>/path/to/your/jdk</string>
    </dict>
</dict>
</plist>

3.2 第二步：部署配置文件

将配置文件复制到系统目录并设置正确的权限：

# 复制配置文件到系统目录
sudo cp ~/org.jenkins.agent.plist /Library/LaunchDaemons/

# 设置文件所有者和所属组
sudo chown root:wheel /Library/LaunchDaemons/org.jenkins.agent.plist

# 设置文件权限
sudo chmod 644 /Library/LaunchDaemons/org.jenkins.agent.plist

权限配置详解

1. 设置所有者和组（chown）

sudo chown root:wheel /Library/LaunchDaemons/org.jenkins.agent.plist

• 作用：将文件的所有者改为 root，所属组改为 wheel
• 含义：
  • root 是系统超级用户，拥有最高权限
  • wheel 是 macOS 中传统的管理员组（继承自 Unix 系统）
• 为什么需要：系统级 LaunchDaemons 必须由 root 拥有，以确保安全性和系统启动时的可靠加载

2. 设置文件权限（chmod）

sudo chmod 644 /Library/LaunchDaemons/org.jenkins.agent.plist

• 作用：设置文件的权限模式为 644
• 权限分解：
  • 6 (所有者 root): 读(4) + 写(2) = 6 → 可读写
  • 4 (组 wheel): 只读(4) → 仅可读
  • 4 (其他用户): 只读(4) → 仅可读
• 为什么需要：
  • launchd 需要读取这些文件来管理服务
  • 普通用户不应能修改系统服务配置，防止安全风险
  • 遵循最小权限原则，是 macOS 系统服务的标准配置方式

3.3 第三步：加载并启动服务

# 加载服务
sudo launchctl load /Library/LaunchDaemons/org.jenkins.agent.plist

# 验证服务状态
launchctl list | grep jenkins

3.4 第四步：验证运行状态

# 查看服务列表
launchctl list | grep org.jenkins.agent

# 查看日志
tail -f /Users/xhm/jenkins/jenkins-agent.log

# 确认 caffeinate 进程存在
ps aux | grep caffeinate | grep jenkins

4. 服务管理

4.1 常用命令

# 停止服务
sudo launchctl unload /Library/LaunchDaemons/org.jenkins.agent.plist

# 启动服务
sudo launchctl load /Library/LaunchDaemons/org.jenkins.agent.plist

# 重启服务（先停止再启动）
sudo launchctl unload /Library/LaunchDaemons/org.jenkins.agent.plist
sudo launchctl load /Library/LaunchDaemons/org.jenkins.agent.plist

# 查看服务状态
launchctl list | grep jenkins

# 查看实时日志
tail -f /Users/xhm/jenkins/jenkins-agent.log

# 查看错误日志
tail -f /Users/xhm/jenkins/jenkins-agent-error.log

4.2 常见问题

4.2.1 息屏后仍然断开

检查清单：

1. 确认使用了 caffeinate：

   ps aux | grep caffeinate | grep jenkins

2. 检查网络配置（防止 Wi-Fi 休眠）：

   • 系统偏好设置 → 电池 → 电源适配器
   • 取消勾选"当显示器关闭时，防止电脑自动进入睡眠"

3. 验证 caffeinate 参数：

   # 确保配置中使用了 -s 参数
   grep -A10 ProgramArguments /Library/LaunchDaemons/org.jenkins.agent.plist

4.2.2 权限问题

症状：日志文件无法写入或工作目录访问失败

解决方法：

# 确保工作目录存在且有正确权限
mkdir -p /Users/xhm/jenkins
chown xhm:staff /Users/xhm/jenkins
chmod 755 /Users/xhm/jenkins

# 确保日志文件可写
touch /Users/xhm/jenkins/jenkins-agent.log
chown xhm:staff /Users/xhm/jenkins/jenkins-agent.log

5. 参考资源

• Apple LaunchDaemon 官方文档
• caffeinate 命令手册
• Jenkins Agent 配置指南