🧩 深入解析 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，也欢迎留言交流～
)
)
