簡介本資源面向在內(nèi)網(wǎng)、隔離網(wǎng)等無外網(wǎng)環(huán)境中部署Jenkins的運維與DevOps工程師針對Jenkins 2.346.1無法在線拉取插件的問題提供一套完整的離線插件安裝方案。壓縮包共約2000個文件整體314.4MB涵蓋90個jpi與30個hpi插件包、366個jar依賴、192個xml配置及大量js、html、css等前端資源并附帶properties、timestamp等元數(shù)據(jù)文件構(gòu)成可直接落地的離線插件倉庫。資源圍繞離線下載插件、創(chuàng)建離線插件包、配置初始化腳本、啟動驗證、后續(xù)維護(hù)更新與安全權(quán)限控制等環(huán)節(jié)展開幫助讀者打通內(nèi)網(wǎng)Jenkins插件安裝全流程。目前已有3171人學(xué)習(xí)下載適合需要快速搭建內(nèi)網(wǎng)CI/CD環(huán)境、排查插件加載失敗問題的技術(shù)人員參考可有效減少重復(fù)試錯成本。1. 內(nèi)網(wǎng) Jenkins 離線裝插件為什么 2.346.1 的插件包不能隨便下很多團(tuán)隊的內(nèi)網(wǎng)構(gòu)建機(jī)跑著 Jenkins 2.346.1版本不算新但勝在穩(wěn)定誰也不想動它。問題出在裝插件上外網(wǎng)能訪問的更新中心內(nèi)網(wǎng)機(jī)器一個字節(jié)都拉不到點「安裝」就是轉(zhuǎn)圈然后報錯。有人圖省事從別的機(jī)器把.hpi拷過來直接丟進(jìn)plugins目錄重啟后插件列表里是有了但構(gòu)建任務(wù)一跑就拋NoSuchMethodError查半天才發(fā)現(xiàn)是插件版本和 Jenkins 核心對不上。這個場景要解決的核心問題就一句話在沒有外網(wǎng)的內(nèi)網(wǎng)環(huán)境里給 Jenkins 2.346.1 裝上一批能正常工作的插件。適合兩類人一是負(fù)責(zé)內(nèi)網(wǎng) CI 環(huán)境維護(hù)、被離線安裝折騰過的運維二是需要在隔離網(wǎng)絡(luò)里搭一套完整構(gòu)建流水線的開發(fā)。下面按「先搞懂依賴關(guān)系再動手下載最后排錯」的順序拆開講每一步都能直接抄。2. 離線安裝的底層邏輯插件依賴樹與版本匹配2.1 為什么不能只下單個 .hpi 文件Jenkins 插件不是孤立運行的。一個插件會聲明它依賴哪些其他插件、依賴的最低版本是多少這些信息寫在插件元數(shù)據(jù)里。你只下git.hpi它可能依賴git-client、credentials、structs等一串插件缺一個就裝不上或者裝上了運行時報錯。常見做法是先確定你要裝的目標(biāo)插件然后遞歸解析它的依賴樹把所有依賴插件連同目標(biāo)插件一起下載。手動做這件事很容易漏所以一般用工具自動解析。版本匹配是第二個關(guān)鍵點。Jenkins 2.346.1 對應(yīng)的插件更新中心有它自己的版本范圍同一個插件在 2.346.1 和 2.4xx 上能用的版本可能不同。判斷依據(jù)是插件頁面上的「Required Core」字段它標(biāo)明了這個插件版本要求的最低 Jenkins 核心版本。你選的插件版本Required Core 必須小于等于 2.346.1。2.2 依賴解析的兩種可行路徑路徑一用官方更新中心的數(shù)據(jù)做離線解析。Jenkins 更新中心有一個update-center.json里面記錄了每個插件的所有版本、依賴關(guān)系和 Required Core。你可以在外網(wǎng)機(jī)器上拉這個文件用腳本解析出目標(biāo)插件的完整依賴樹再按版本約束篩選出適配 2.346.1 的版本組合。路徑二用現(xiàn)成的離線下載工具。社區(qū)里有針對 Jenkins 的插件下載腳本輸入插件名和 Jenkins 版本輸出一個包含所有依賴的目錄。這類工具的原理和路徑一一樣只是把解析邏輯封裝好了。我一般會走路徑一因為可控。下面給一個用 Python 解析依賴樹的骨架代碼核心是從update-center.json里遞歸找依賴。import json import requests # 從外網(wǎng)機(jī)器拉取更新中心數(shù)據(jù)內(nèi)網(wǎng)機(jī)器提前拷貝好這個文件 # 注意不同 Jenkins 版本的更新中心 URL 不同2.346.1 對應(yīng)的是穩(wěn)定版更新中心 UPDATE_CENTER_URL https://updates.jenkins.io/stable/update-center.json def load_update_center(local_pathNone): 加載更新中心數(shù)據(jù)支持本地文件或在線拉取 if local_path: with open(local_path, r, encodingutf-8) as f: raw f.read() else: raw requests.get(UPDATE_CENTER_URL).text # update-center.json 外層包了一層 JSONP 回調(diào)需要剝掉 raw raw.strip() if raw.startswith(updateCenter.post(): raw raw[len(updateCenter.post():] if raw.endswith();): raw raw[:-2] return json.loads(raw) def resolve_deps(uc_data, plugin_name, jenkins_version, resolvedNone): 遞歸解析插件依賴返回 {插件名: 版本} 的字典 if resolved is None: resolved {} if plugin_name in resolved: return resolved plugins uc_data[plugins] if plugin_name not in plugins: raise ValueError(f插件 {plugin_name} 不在更新中心數(shù)據(jù)里) info plugins[plugin_name] # 篩選出 Required Core 當(dāng)前 Jenkins 版本的版本 candidates [] for ver, meta in info.items(): if ver name: continue required_core meta.get(requiredCore, 0) if compare_version(required_core, jenkins_version) 0: candidates.append((ver, meta)) if not candidates: raise ValueError(f{plugin_name} 沒有適配 {jenkins_version} 的版本) # 取滿足條件的最高版本 candidates.sort(keylambda x: x[0], reverseTrue) chosen_ver, chosen_meta candidates[0] resolved[plugin_name] chosen_ver # 遞歸處理依賴 for dep_name, dep_ver in chosen_meta.get(dependencies, {}).items(): resolve_deps(uc_data, dep_name, jenkins_version, resolved) return resolved def compare_version(v1, v2): 簡單的版本號比較返回 -1/0/1 parts1 [int(x) for x in v1.split(.) if x.isdigit()] parts2 [int(x) for x in v2.split(.) if x.isdigit()] for a, b in zip(parts1, parts2): if a b: return -1 if a b: return 1 return 0這段代碼的邏輯說明load_update_center負(fù)責(zé)把更新中心數(shù)據(jù)讀進(jìn)來注意它外層有 JSONP 包裝直接json.loads會失敗必須先剝殼。resolve_deps是核心遞歸函數(shù)它先按requiredCore過濾出適配當(dāng)前 Jenkins 版本的插件版本取最高版本后再遍歷這個版本的dependencies字段繼續(xù)遞歸。compare_version是個簡化版比較函數(shù)實際用的時候建議換成packaging.version庫避免遇到1.10和1.9比較出錯。參數(shù)方面jenkins_version傳2.346.1plugin_name傳你要裝的目標(biāo)插件名比如git。跑完之后resolved字典里就是完整的插件名和版本列表。2.3 下載環(huán)節(jié)的目錄組織解析出依賴列表后下載環(huán)節(jié)要按固定結(jié)構(gòu)組織文件方便后續(xù)批量安裝。我一般用這樣的目錄offline-plugins/ ├── download_list.txt # 插件名:版本 列表 ├── hpi/ # 所有 .hpi 文件 │ ├── git-4.11.3.hpi │ ├── git-client-3.11.0.hpi │ └── ... └── install.sh # 批量安裝腳本下載 URL 的規(guī)律是https://updates.jenkins.io/download/plugins/{插件名}/{版本}/{插件名}.hpi。注意文件名里不帶版本號版本號在路徑里。下載腳本按這個規(guī)律拼 URL 即可。3. 內(nèi)網(wǎng)落地實操從外網(wǎng)下載到 Jenkins 加載3.1 外網(wǎng)機(jī)器上的下載與打包在外網(wǎng)機(jī)器上先跑上面的解析腳本拿到依賴列表然后批量下載。下面是一個下載腳本讀download_list.txt逐行下載。#!/bin/bash # 在外網(wǎng)機(jī)器上執(zhí)行下載所有插件到 hpi 目錄 set -e DOWNLOAD_DIR./hpi LIST_FILE./download_list.txt BASE_URLhttps://updates.jenkins.io/download/plugins mkdir -p $DOWNLOAD_DIR while IFS: read -r name version; do # 跳過空行和注釋 [[ -z $name || $name \#* ]] continue url${BASE_URL}/${name}/${version}/${name}.hpi out${DOWNLOAD_DIR}/${name}-${version}.hpi if [[ -f $out ]]; then echo 已存在跳過: $out continue fi echo 下載: $url curl -fSL -o $out $url done $LIST_FILE echo 下載完成共 $(ls -1 $DOWNLOAD_DIR | wc -l) 個文件邏輯說明IFS:按冒號分割每行因為download_list.txt的格式是插件名:版本。curl -fSL里-f讓 HTTP 錯誤碼直接失敗而不是寫入錯誤頁面-L跟隨重定向-S顯示錯誤。下載完成后檢查文件數(shù)量是否和列表行數(shù)一致不一致說明有下載失敗。打包時把hpi目錄和install.sh一起打成 tar 包通過內(nèi)網(wǎng)允許的方式傳到目標(biāo)機(jī)器。注意不要用zip因為 Jenkins 機(jī)器上不一定有解壓工具tar更通用。3.2 內(nèi)網(wǎng)機(jī)器上的批量安裝傳到內(nèi)網(wǎng)后有兩種安裝方式。方式一是直接拷貝到JENKINS_HOME/plugins目錄然后重啟。方式二是用 Jenkins CLI 的install-plugin命令。方式一更直接但要注意權(quán)限和文件屬主。#!/bin/bash # 在內(nèi)網(wǎng) Jenkins 機(jī)器上執(zhí)行 set -e JENKINS_HOME/var/lib/jenkins # 按實際路徑改 HPI_DIR./hpi # 備份現(xiàn)有插件目錄出問題能回滾 BACKUP_DIR${JENKINS_HOME}/plugins.bak.$(date %Y%m%d%H%M%S) cp -a ${JENKINS_HOME}/plugins $BACKUP_DIR echo 已備份到 $BACKUP_DIR # 拷貝新插件注意屬主 cp -v ${HPI_DIR}/*.hpi ${JENKINS_HOME}/plugins/ chown -R jenkins:jenkins ${JENKINS_HOME}/plugins # 刪除插件解壓緩存強(qiáng)制重新解壓 find ${JENKINS_HOME}/plugins -maxdepth 1 -type d -name *.hpi -prune -o -type d -print | while read d; do # 只刪和 hpi 同名的解壓目錄 base$(basename $d) if [[ -f ${JENKINS_HOME}/plugins/${base}.hpi ]]; then rm -rf $d fi done echo 插件拷貝完成請重啟 Jenkins邏輯說明先備份是血淚經(jīng)驗插件裝崩了能直接回滾。chown必須做否則 Jenkins 進(jìn)程讀不到文件。刪除解壓緩存這一步很多人會漏Jenkins 加載插件時如果發(fā)現(xiàn)同名目錄已存在可能不會重新解壓新的.hpi導(dǎo)致你以為裝了新版本實際還是舊的。重啟命令按你的部署方式選systemctl restart jenkins或service jenkins restart。重啟后看日志確認(rèn)加載情況。3.3 驗證插件是否真正生效重啟不等于裝好。驗證分三步第一步看 Jenkins 啟動日志里有沒有插件加載失敗的報錯第二步進(jìn)「系統(tǒng)管理 → 插件管理 → 已安裝」看插件是否在列表里且版本正確第三步實際跑一個用到該插件的構(gòu)建任務(wù)。# 查看啟動日志中的插件加載錯誤 grep -i failed to load\|SEVERE.*plugin\|Plugin.*failed /var/log/jenkins/jenkins.log | tail -50 # 查看已加載插件列表通過 Jenkins CLI java -jar jenkins-cli.jar -s http://localhost:8080/ -auth admin:token list-plugins | grep -i git日志里如果出現(xiàn)Failed to load: xxx (xxx)后面跟NoClassDefFoundError或NoSuchMethodError基本就是版本不匹配。list-plugins命令需要 Jenkins CLI 的 jar 包和認(rèn)證信息認(rèn)證用 API Token 比密碼安全。4. 避坑與排查離線裝插件最容易翻車的五個點4.1 現(xiàn)象插件列表里有了但構(gòu)建時報 NoSuchMethodError原因插件版本和 Jenkins 核心版本不匹配。你下載的插件版本 Required Core 高于 2.346.1Jenkins 加載時沒攔住但運行時調(diào)用了核心不存在的方法。解決回到更新中心數(shù)據(jù)重新按requiredCore 2.346.1篩選版本。不要只看插件的最新版最新版往往要求更高的核心版本。4.2 現(xiàn)象重啟后插件消失或者版本沒變原因Jenkins 的插件加載機(jī)制會優(yōu)先讀解壓后的目錄如果同名目錄已存在它不會重新解壓新的.hpi。你拷貝了新文件但舊目錄還在加載的還是舊版本。解決拷貝新.hpi后刪除對應(yīng)的解壓目錄再重啟。上面的安裝腳本里已經(jīng)包含這一步。更穩(wěn)妥的做法是停掉 Jenkins 再操作避免運行中文件被占用。4.3 現(xiàn)象插件裝上了但功能不可用比如 Git 插件找不到 git 命令原因插件本身是 Jenkins 側(cè)的封裝它依賴系統(tǒng)里安裝的 git 可執(zhí)行文件。離線環(huán)境里 Jenkins 機(jī)器可能沒裝 git或者 git 路徑不在 Jenkins 進(jìn)程的 PATH 里。解決在 Jenkins 的「系統(tǒng)管理 → 全局工具配置」里顯式指定 git 路徑不要依賴 PATH。同時確認(rèn)jenkins用戶能執(zhí)行g(shù)it --version。4.4 現(xiàn)象依賴插件缺失安裝時報「依賴未滿足」原因解析依賴樹時漏了傳遞依賴或者某個依賴插件的版本被其他插件約束到了不兼容的范圍。解決用resolve_deps跑完整依賴樹不要手動挑。如果兩個插件對同一個依賴的版本要求沖突優(yōu)先滿足 Required Core 更高的那個插件的約束然后驗證另一個插件是否還能工作。4.5 現(xiàn)象拷貝文件后 Jenkins 啟動失敗日志報權(quán)限錯誤原因cp操作是以當(dāng)前用戶執(zhí)行的文件屬主不是jenkinsJenkins 進(jìn)程讀不到。解決chown -R jenkins:jenkins整個 plugins 目錄。另外注意JENKINS_HOME的父目錄權(quán)限如果 Jenkins 用戶對父目錄沒有執(zhí)行權(quán)限一樣讀不到。提示每次批量裝插件前先備份plugins目錄和config.xml?；貪L成本遠(yuǎn)低于排查成本。5. 進(jìn)階技巧用腳本做版本校驗和增量更新裝完一批插件后后續(xù)維護(hù)的痛點在于怎么知道哪些插件有新版本、新版本是否適配當(dāng)前 Jenkins。我一般會寫一個校驗?zāi)_本把內(nèi)網(wǎng)已裝插件列表和外網(wǎng)更新中心數(shù)據(jù)做比對輸出可升級列表和對應(yīng)的 Required Core。import json def check_updates(uc_data, installed, jenkins_version): 比對已裝插件和更新中心輸出可升級且適配的插件 plugins uc_data[plugins] result [] for name, current_ver in installed.items(): if name not in plugins: continue candidates [] for ver, meta in plugins[name].items(): if ver name: continue if compare_version(meta.get(requiredCore, 0), jenkins_version) 0: candidates.append(ver) if not candidates: continue candidates.sort(keylambda v: [int(x) for x in v.split(.) if x.isdigit()], reverseTrue) latest candidates[-1] if compare_version(latest, current_ver) 0: result.append((name, current_ver, latest)) return result # installed 從 Jenkins 的 plugins 目錄或 list-plugins 輸出解析得到 # 輸出格式[(插件名, 當(dāng)前版本, 可升級版本), ...]這個腳本的價值在于它不會推薦 Required Core 超過當(dāng)前 Jenkins 版本的升級避免你升完發(fā)現(xiàn) Jenkins 起不來。installed字典可以從JENKINS_HOME/plugins目錄下的.hpi文件名解析也可以用list-plugins命令的輸出。增量更新的操作流程是跑校驗?zāi)_本拿到可升級列表只下載這些插件的.hpi傳到內(nèi)網(wǎng)后按第 3 章的安裝腳本替換。注意替換前仍然要備份并且刪除對應(yīng)的解壓目錄。還有一個容易被忽略的點Jenkins 的插件更新中心數(shù)據(jù)本身會變同一個插件版本在不同時間拉到的update-center.json可能不同。所以在外網(wǎng)下載時建議把update-center.json一起打包傳到內(nèi)網(wǎng)后續(xù)排查版本問題時能對照當(dāng)時的數(shù)據(jù)。從那以后我每次做離線插件安裝都強(qiáng)制走一遍「解析依賴 → 下載 → 備份 → 拷貝 → 刪緩存 → 重啟 → 驗證」這七步少一步都可能翻車。希望幫到你。本文還有配套的精品資源點擊獲取