Jenkins 使用 NSSM 实现 Windows 节点自启动

一、文档概述

1.1 目的

通过 NSSM（Non-Sucking Service Manager）工具，将 Jenkins 节点代理（agent.jar）注册为 Windows 系统服务，实现节点开机自启动、故障自动重启，无需手动执行启动命令，保障 Jenkins 节点稳定在线。

1.2 适用场景

Windows 系统的 Jenkins 节点（物理机/虚拟机）；
需长期稳定运行的节点（如自动化测试节点、构建节点）；
希望节点故障后自动恢复的场景。

1.3 核心优势

支持开机自启动，无需人工干预；
可配置故障重启策略（如服务崩溃后自动重启）；
图形化界面配置，操作简单，无需编写复杂脚本；
支持服务状态监控、启停管理、参数修改。

二、前置准备

2.1 必备工具/文件

名称	说明	获取方式
NSSM 工具	Windows 服务管理工具（无需安装，解压即用）	官网下载：https://nssm.cc/download （选择对应系统版本，如 64-bit）
Jenkins Agent	节点代理程序（agent.jar），从 Jenkins 服务器获取	Jenkins 服务器 → 管理 Jenkins → 管理节点 → 新建节点 → 下载 agent.jar
Java 环境	需安装 JDK/JRE（1.8 及以上版本），确保 `java.exe` 可正常运行	官网下载对应版本 JDK，安装后配置环境变量

Jenkins Agent配置参考

agent.jar下载

配置好节点后，点击节点，复制下载命令，打开cmd命令窗口下载agent.jar

2.2 环境检查

验证 Java 环境：打开 CMD 命令行，执行 java -version，若显示版本信息（如 java version "1.8.0_301"），说明环境正常；
验证 agent.jar 可用性：将 agent.jar 放置到指定目录（如 D:\jenkins_node），手动执行启动命令测试是否能连接 Jenkins 服务器：
cmd 复制代码
```
java -jar agent.jar -url http://10.134.12.64:8080/ -secret 【你的节点密钥】 -name 【你的节点名称】 -webSocket -workDir "D:\jenkins_node"
```
若日志显示「Connected」，说明 agent.jar 配置正确，可正常连接 Jenkins。

三、NSSM 安装与环境配置

3.1 下载与解压 NSSM

从 NSSM 官网下载工具包（如 nssm-2.24.zip）；
解压到指定目录（如 D:\nssm），解压后目录包含 win32（32位系统）和 win64（64位系统）文件夹，根据系统选择对应版本；
（可选）配置环境变量：将 NSSM 所在目录（如 D:\nssm\win64）添加到系统「Path」环境变量，方便全局调用（无需切换到解压目录执行命令）。

四、注册 Jenkins 节点服务（核心步骤）

4.1 打开 NSSM 配置界面

以 管理员身份 打开 CMD 命令行（右键 CMD → 以管理员身份运行）；
执行以下命令注册服务（jenkinsCliService 为自定义服务名称，可修改）：
cmd 复制代码
```
nssm install jenkinsCliService
```
执行后弹出 NSSM 服务配置窗口，按以下步骤配置关键参数。

4.2 配置「Application」选项卡（核心）

用于指定服务运行的可执行程序、工作目录和启动参数：

配置项	操作步骤
Path（可执行程序路径）	点击「...」选择 `java.exe` 所在路径（如 `C:\Program Files\Java\jdk1.8.0_301\bin\java.exe`）
Working directory	选择 agent.jar 所在目录（如 `D:\jenkins_node`）
Arguments（运行参数）	填写 Jenkins 节点启动参数（需替换【】中的自定义内容）： `-jar agent.jar -url http://10.134.12.64:8080/ -secret 5830a43fdbb0ce2d9b55678bd3412a05ec53d7b9ed9620cda84844a28666a1bc -name Dilu -webSocket -workDir "D:\jenkins_node"`

⚠️ 注意：

参数需与 Jenkins 节点配置一致（-secret 为节点密钥，-name 为节点名称，从 Jenkins 服务器节点配置页获取）；
workDir 需与 agent.jar 所在目录一致，避免文件路径错误。

4.3 配置「Details」选项卡（可选）

用于设置服务显示名称和描述，方便识别：

配置项	操作步骤
Display name	服务显示名称（如「Jenkins-Dilu节点服务」）
Description	服务描述（如「Dilu Jenkins 冒烟测试节点自启动服务，负责Android+帝录设备测试」）
Startup type	启动类型选择「Automatic（Delayed Start）」（延迟自动启动，避免系统开机时资源竞争）

4.4 配置「Log on」选项卡（关键）

用于设置服务运行的用户身份，确保服务有足够权限访问系统资源：

配置项	操作步骤
身份选择	推荐选择「Local System account」（本地系统账户），具备访问文件、网络的权限；若节点需访问特定用户目录或网络资源，可选择「This account」，输入Windows用户账户和密码
权限说明	本地系统账户无需额外配置，适合大多数场景；自定义账户需确保有 agent.jar 目录的读写权限和网络访问权限

4.5 配置「Recovery」选项卡（核心）

设置服务故障后的处理策略，保障服务稳定性：

配置项	操作步骤
First failure（第一次故障）	选择「Restart the service」（重启服务），重启间隔设置为「1分钟」
Second failure（第二次故障）	选择「Restart the service」（重启服务），重启间隔设置为「3分钟」
Subsequent failures（后续故障）	选择「Restart the service」（重启服务），重启间隔设置为「5分钟」
Reset failure count after（重置故障计数）	设置为「1天」（24小时），避免持续故障导致无限重启
Restart service after（重启服务延迟）	设置为「0分钟」（立即重启）

4.6 保存服务配置

所有参数配置完成后，点击「Install service」按钮，弹出「Service installed successfully」提示，说明服务注册成功。

五、Jenkins 节点服务管理（启动/停止/修改）

5.1 启动服务

管理员身份打开 CMD 命令行，执行：
cmd 复制代码
```
nssm start jenkinsCliService
```
若提示「jenkinsCliService: START: 服务启动成功」，说明服务启动正常；
验证：登录 Jenkins 服务器 → 管理 Jenkins → 管理节点，查看目标节点（如 Dilu）状态是否为「在线」。

⚠️ 常见问题：启动服务提示「Could not open service」

原因：权限不足，未以管理员身份运行 CMD；
解决：关闭当前 CMD，以管理员身份重新打开，再次执行启动命令。

5.2 停止服务

cmd 复制代码

nssm stop jenkinsCliService

执行后提示「jenkinsCliService: STOP: 服务停止成功」，Jenkins 节点状态变为「离线」。

5.3 重启服务

cmd 复制代码

nssm restart jenkinsCliService

适用于修改服务配置后，重启服务生效。

5.4 查看服务状态

cmd 复制代码

nssm status jenkinsCliService

输出结果说明：

RUNNING：服务正在运行；
STOPPED：服务已停止；
PAUSED：服务已暂停。

5.5 修改服务配置

若需调整服务参数（如启动参数、故障策略），执行：

cmd 复制代码

nssm edit jenkinsCliService

弹出配置窗口，修改对应参数后点击「OK」，重启服务即可生效。

5.6 删除服务

若节点不再使用，需删除服务：

先停止服务：nssm stop jenkinsCliService；
执行删除命令：
cmd 复制代码
```
nssm remove jenkinsCliService
```
按提示输入「Y」确认删除，服务删除后不可恢复。

六、更改Jenkins节点服务的用户

目的是为了规避节点运行任务时，使用了默认的system用户，会有一些权限问题的坑，比如拉取代码时没有权限，因为秘钥一般是配置在用户目录下的（C:\Users\4388.ssh）

七、常见问题排查

问题 1：服务启动成功，但 Jenkins 节点显示「离线」

原因：
1. 启动参数错误（如 url 错误、secret 不匹配、name 与 Jenkins 节点名称不一致）；
2. Jenkins 服务器未启动或网络不通；
3. agent.jar 路径错误或文件损坏。
解决：
1. 检查启动参数（Arguments），确保与 Jenkins 节点配置完全一致；
2. 手动执行启动命令测试：java -jar agent.jar 【你的启动参数】，查看是否有连接错误日志；
3. 验证 Jenkins 服务器 URL 可访问（节点物理机浏览器打开 http://10.134.12.64:8080/）；
4. 重新下载 agent.jar 替换原有文件。

问题 2：服务启动提示「Java 不是内部或外部命令」

原因：Java 环境变量未配置，或 java.exe 路径错误；
解决：
1. 检查 Java 环境变量「Path」是否包含 jdk\bin 目录（如 C:\Program Files\Java\jdk1.8.0_301\bin）；
2. 重新配置环境变量后，重启 CMD 再次执行启动命令；
3. 若环境变量配置无效，在 NSSM「Application」→「Path」中填写完整的 java.exe 路径（如 C:\Program Files\Java\jdk1.8.0_301\bin\java.exe）。

问题 3：服务启动后很快停止（日志显示「Connection refused」）

原因：Jenkins 服务器拒绝连接（如 secret 错误、节点已被删除）；
解决：
1. 登录 Jenkins 服务器 → 管理节点，确认节点（如 Dilu）已存在且「Secret」与启动参数一致；
2. 若节点不存在，重新创建节点并获取新的 secret 和启动参数；
3. 若节点存在，点击「重启节点」，再启动 NSSM 服务。

问题 4：权限不足，无法访问 agent.jar 或工作目录

原因：服务运行用户（如 Local System）对 agent.jar 目录无读写权限；
解决：
1. 右键 agent.jar 所在目录（如 D:\jenkins_node）→「属性」→「安全」；
2. 给「SYSTEM」用户分配「完全控制」或「读写」权限；
3. 点击「应用」→「确定」，重启服务。