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