当前位置：首页 > news >正文

深入解析 Jenkins Agent 的 .jnlp 启动文件

news 来源：原创 2025/5/10 11:02:20

🧩 深入解析 Jenkins Agent 的 `.jnlp` 启动文件

在 Jenkins 中，通过 JNLP（Java Network Launch Protocol）方式连接 Agent 是一种常见且灵活的方式。你可能曾见过类似这样的命令：

java -jar agent.jar -jnlpUrl file:///users/sqi.io/jenkins-agent.jnlp -workDir "/users/sqi.io/jenkins"

但其中提到的 .jnlp 文件到底是做什么的？又包含了哪些关键内容？这篇文章将带你全面了解 Jenkins Agent 的 .jnlp 文件结构及其作用。

🧾 什么是 `.jnlp` 文件？

.jnlp 是一个基于 XML 格式的配置文件，原生用于 Java Web Start 应用的启动定义。在 Jenkins 中，它被用于定义 Agent 的启动参数和通信设置。通过该文件，Agent 能够远程连接到 Jenkins 主服务器，并进行构建任务处理。

🔍 `.jnlp` 文件结构解析

以下是一个 Jenkins 生成的 .jnlp 文件示例（敏感信息已脱敏处理）：

<jnlp codebase="http://<jenkins-host>:8080/computer/<agent-name>/" spec="1.0+">
  <information>
    <title>Agent for <agent-name></title>
    <vendor>Jenkins project</vendor>
    <homepage href="https://jenkins-ci.org/"/>
  </information>

  <security>
    <all-permissions/>
  </security>

  <resources>
    <j2se version="1.8+"/>
    <jar href="http://<jenkins-host>:8080/jnlpJars/remoting.jar"/>
  </resources>

  <application-desc main-class="hudson.remoting.jnlp.Main">
    <argument>[secret-key]</argument>
    <argument><agent-name></argument>
    <argument>-workDir</argument>
    <argument>/Users/sqi.io/jenkins</argument>
    <argument>-internalDir</argument>
    <argument>remoting</argument>
    <argument>-url</argument>
    <argument>http://<jenkins-host>:8080/</argument>
  </application-desc>
</jnlp>

🧱 结构详细说明

区块	说明
`<jnlp>`	指定资源加载的基础路径 (`codebase`) 与使用的规范版本 (`spec`)。
`<information>`	提供描述信息，如标题、厂商和主页。
`<security>`	表示该 Agent 请求“所有权限”，即 Full Permission，用于执行构建时的各种系统操作。
`<resources>`	指定所需的 Java 版本及所依赖的远程 `remoting.jar` 文件。该 jar 是 Jenkins Master 和 Agent 通信的核心。
`<application-desc>`	指定程序入口类和启动参数。Jenkins Agent 的入口为 `hudson.remoting.jnlp.Main`。

🚀 启动参数说明

以下是 <application-desc> 内各参数的意义：

参数	说明
`[secret-key]`	认证用的 token，确保连接安全。敏感信息，切勿泄露。
`<agent-name>`	节点在 Jenkins 中的标识名，例如 `mac-mini-jenkins-slave-001`。
`-workDir`	Agent 的本地工作目录，用于缓存构建文件。
`-internalDir`	用于存放 Jenkins remoting 自身运行相关的内部数据。
`-url`	Jenkins 主服务器地址。

✅ 等效命令行启动方式

根据上面的 .jnlp 文件，你可以构造一个等效的命令行启动方式：

java -jar agent.jar \
  -jnlpUrl http://<jenkins-host>:8080/computer/<agent-name>/slave-agent.jnlp \
  -secret [secret-key] \
  -workDir "/Users/sqi.io/jenkins"