🧩 深入解析 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"

📌 使用 -secret 和 HTTP 方式通常更方便，也是 Jenkins UI 推荐的方式。

---

🛡️ 安全提示

• .jnlp 文件中含有明文认证信息（如 secret key），切勿暴露在公网或版本控制系统中。
• 建议为每个 Agent 使用独立的 token，便于权限管理和问题追踪。
• 使用 HTTPS 而不是 HTTP 能有效防止中间人攻击。

---

🧠 Last

.jnlp 文件是 Jenkins Agent 与 Master 通信的桥梁，定义了连接参数和资源路径。理解其结构不仅有助于你更好地管理 CI/CD 系统，也能在遇到连接问题时迅速定位根因。

---

如果你对 Jenkins Agent 启动方式还有更多疑问，比如如何通过 Docker 或 SSH 启动 Agent，也欢迎留言交流～