簡介SonarQube 7.9壓縮包是一份面向代碼質(zhì)量管理場景的開源工具部署資源適合需要搭建或升級SonarQube服務(wù)、持續(xù)檢測源碼漏洞與壞味道的開發(fā)及運(yùn)維人員。壓縮包整體約196.67MB解壓后包含server啟動腳本、data數(shù)據(jù)存儲、extensions插件擴(kuò)展、web前端資源、conf配置目錄、內(nèi)置Elasticsearch核及l(fā)ogs日志等模塊可支撐從安裝配置到運(yùn)行維護(hù)的完整流程。目前已累計(jì)472人學(xué)習(xí)下載。通過bin目錄的管理腳本可快速啟停服務(wù)在sonar.properties中可調(diào)整數(shù)據(jù)庫連接、端口與日志級別將第三方語言插件放入extensions即可擴(kuò)展分析范圍。內(nèi)置的Elasticsearch能高效檢索質(zhì)量度量數(shù)據(jù)配合web界面查看分析結(jié)果有助于團(tuán)隊(duì)在開發(fā)早期發(fā)現(xiàn)潛在缺陷、統(tǒng)一編碼規(guī)范持續(xù)降低維護(hù)成本。1. 為什么還在用 SonarQube 7.9低配服務(wù)器和老項(xiàng)目的最優(yōu)解接手一個(gè)兩年沒人做靜態(tài)檢查的老 Java 項(xiàng)目我第一件事就是把 SonarQube 拉起來跑一批壞味道數(shù)據(jù)。試了最新版4G 內(nèi)存的服務(wù)器直接起不來規(guī)則集和接口也變了不少折騰兩小時(shí)沒出報(bào)告。換回下載目錄里的 sonarqube-7.9 鏡像一條 Docker 命令五分鐘出結(jié)果。SonarQube 7.9 是官方 LTS 版本規(guī)則集完整、運(yùn)行門檻低、配套插件生態(tài)成熟大量老項(xiàng)目至今還在用它做質(zhì)量基線。這個(gè)資源適合兩類人維護(hù)老系統(tǒng)、只想把質(zhì)量數(shù)據(jù)跑出來的開發(fā)者第一次接觸 SonarQube、不想在環(huán)境配置上花太多時(shí)間的新手。它解決的問題很純粹——在低成本環(huán)境下把代碼壞味道量化出來規(guī)則條條可見改完能立刻復(fù)掃驗(yàn)證。2. 用 Docker 拉起 7.9一條 Compose 搞定服務(wù)端與數(shù)據(jù)庫2.1 為什么 7.9 必須配 PostgreSQL數(shù)據(jù)庫選型的硬約束SonarQube 7.9 官方支持的數(shù)據(jù)庫是 PostgreSQL、Oracle、SQL Server 和內(nèi)嵌 H2。生產(chǎn)環(huán)境里主流做法是配 PostgreSQL因?yàn)榘惭b最省事、權(quán)限模型也清晰。很多人第一次用 7.9 時(shí)拿 MySQL 去連啟動日志直接報(bào)Unsupported database mysql這是因?yàn)閺?7.9 開始官方正式移除了 MySQL 支持。如果你只是臨時(shí)體驗(yàn)一下用內(nèi)置 H2 也能跑但重啟后數(shù)據(jù)容易丟不適合長期管理。數(shù)據(jù)庫選型上我一般推薦 PostgreSQL 10 或 11。7.9 對 PostgreSQL 的支持范圍覆蓋 9.3 到 11選 10 的鏡像最穩(wěn)既有 JSON 支持又不帶 12 之后的新特性風(fēng)險(xiǎn)。用 Docker Compose 把服務(wù)端和數(shù)據(jù)庫一起拉起是最省心的方式。version: 2 services: sonarqube: image: sonarqube:7.9.6-community container_name: sonarqube ports: - 9000:9000 environment: - sonar.jdbc.urljdbc:postgresql://db:5432/sonar - sonar.jdbc.usernamesonar - sonar.jdbc.passwordsonar depends_on: - db db: image: postgres:10.4-alpine container_name: sonardb environment: - POSTGRES_USERsonar - POSTGRES_PASSWORDsonar - POSTGRES_DBsonar volumes: - sonardb:/var/lib/postgresql/data volumes: sonardb: driver: local這段 Compose 里的關(guān)鍵參數(shù)是sonar.jdbc.url它決定了服務(wù)端連哪個(gè)數(shù)據(jù)庫。jdbc:postgresql://db:5432/sonar里的db是 Compose 內(nèi)部主機(jī)名對應(yīng)下面的db服務(wù)后面三個(gè)環(huán)境變量分別指定了數(shù)據(jù)庫用戶名、密碼和庫名。depends_on保證數(shù)據(jù)庫先啟動但這只是進(jìn)程級別的等待極端情況下數(shù)據(jù)庫還沒就緒服務(wù)端就啟動了稍后會提到怎么處理。postgres 鏡像里的POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB三個(gè)變量必須和上面的 JDBC 參數(shù)保持一致不然服務(wù)端連不上數(shù)據(jù)庫。卷sonardb用來持久化數(shù)據(jù)刪容器不影響數(shù)據(jù)刪卷才會徹底清空。端口映射9000:9000是 SonarQube 默認(rèn) Web 端口如果你本機(jī) 9000 被占用改成19000:9000這類映射即可。2.2 容器起不來時(shí)先查這兩個(gè)參數(shù)內(nèi)存映射與日志等待啟動完等待一分鐘左右訪問http://localhost:9000如果遲遲打不開去查容器日志是最直接的手段。7.9 內(nèi)置了 Elasticsearch常見報(bào)錯是max virtual memory areas vm.max_map_count [65530] is too low這是宿主機(jī)的內(nèi)核參數(shù)限制不是容器配置問題。在宿主機(jī)執(zhí)行sudo sysctl -w vm.max_map_count262144這個(gè)值指定了進(jìn)程能擁有的內(nèi)存映射區(qū)域數(shù)量Elasticsearch 默認(rèn)要求不低于 262144。臨時(shí)修改立刻生效但重啟后失效建議寫進(jìn)/etc/sysctl.conf持久化。另一個(gè)小坑是日志里反復(fù)出現(xiàn)Process [elasticesearch] is stopped原因常是容器內(nèi)存不夠。7.9 的 Docker 鏡像默認(rèn)把 ES 堆內(nèi)存設(shè)為 1G如果你的服務(wù)器只有 2G 內(nèi)存再跑 PostgreSQL 很容易觸發(fā) OOM。這時(shí)需要給容器限內(nèi)存同時(shí)調(diào)低 ES 堆內(nèi)存。在 Compose 的 sonarqube 服務(wù)里加兩行environment: - sonar.search.javaAdditionalOpts-Xms512m -Xmx512msonar.search.javaAdditionalOpts直接控制 Elasticsearch JVM 參數(shù)把堆內(nèi)存從默認(rèn)降到 512M換穩(wěn)定性。不過降到 512M 之后大型項(xiàng)目的索引性能會受影響適合幾百個(gè)文件的倉庫。2.3 不用 Docker 的手動部署最容易漏的目錄與權(quán)限如果你的服務(wù)器上不方便裝 Docker手動部署其實(shí)也就三步下載 7.9 發(fā)行包、改conf/sonar.properties、啟動bin/下的腳本。關(guān)鍵配置集中在conf/sonar.properties文件里sonar.jdbc.urljdbc:postgresql://localhost:5432/sonar sonar.jdbc.usernamesonar sonar.jdbc.passwordsonar sonar.web.port9000注意手動部署時(shí)數(shù)據(jù)庫連接串的寫法是jdbc:postgresql://localhost:5432/sonar和 Docker 里的差別就在主機(jī)名部分。改動后不要用 root 用戶直接跑啟動腳本SonarQube 官方明確要求非 root 運(yùn)行否則 Elasticsearch 拒絕啟動。創(chuàng)建專用用戶并授權(quán)數(shù)據(jù)目錄是我推薦的做法useradd sonar chown -R sonar:sonar /opt/sonarqube-7.9 su sonar -c /opt/sonarqube-7.9/bin/linux-x86-64/sonar.sh start訪問時(shí)還需要確認(rèn)防火墻有沒有放行 9000 端口以及sonar.web.port是否被占用。手動部署比 Docker 多出的幾個(gè)變量就是這些——運(yùn)行用戶、目錄權(quán)限、端口沖突排查時(shí)按這個(gè)順序來基本不會卡住。3. 把掃描器接到項(xiàng)目從本地 sonar-scanner 到 CI 集成的完整路徑3.1 本地掃描第一個(gè)項(xiàng)目sonar-project.properties 配置拆解服務(wù)端起來之后需要安裝掃描器才能分析代碼。我習(xí)慣用 sonar-scanner-cli 的 4.x 版本和 7.9 服務(wù)端的兼容性最好不需要額外加參數(shù)。解壓后先改conf/sonar-scanner.properties把服務(wù)端地址和認(rèn)證信息寫進(jìn)去sonar.host.urlhttp://localhost:9000 sonar.login你的Token這里的sonar.login在 7.9 里推薦用 Token而不是賬號密碼。登錄 SonarQube 后在右上角頭像菜單里進(jìn)入「我的賬號 → 安全」生成一個(gè) Token復(fù)制出來填進(jìn)去。Token 比密碼安全的地方在于可以單獨(dú)撤銷即使泄露也不影響賬號密碼。然后在項(xiàng)目根目錄創(chuàng)建sonar-project.properties這是掃描器的項(xiàng)目級配置sonar.projectKeymy-project sonar.projectNameMy Project sonar.projectVersion1.0 sonar.sourcessrc sonar.java.binariestarget/classes sonar.java.libraries**/lib/*.jar sonar.sourceEncodingUTF-8sonar.projectKey是項(xiàng)目的唯一標(biāo)識在同一臺 SonarQube 上不能重復(fù)sonar.sources指向源碼目錄sonar.java.binaries指向編譯后的 class 目錄這個(gè)參數(shù)在 7.9 里特別容易漏漏了會報(bào)java files cant be analyzed。sonar.java.libraries指定依賴 jar 的路徑如果項(xiàng)目有多級依賴目錄可以用通配符。最后執(zhí)行sonar-scanner掃描結(jié)束會輸出BUILD SUCCESS和一個(gè)http://localhost:9000/dashboard?idmy-project的鏈接。打開就能看到行數(shù)、壞味道、覆蓋率這些基礎(chǔ)指標(biāo)。第一次跑掃描時(shí)我一般會盯著日志里的WARN看很多參數(shù)問題不會讓掃描失敗但會直接導(dǎo)致某些指標(biāo)缺失。3.2 接入 Maven先編譯再掃描順序別搞反Maven 項(xiàng)目接 SonarQube 是最省事的場景不需要手動建sonar-project.properties因?yàn)閜om.xml里已經(jīng)包含坐標(biāo)信息。推薦的做法是在pom.xml里配置插件屬性或者直接在命令行傳參mvn clean verify sonar:sonar \ -Dsonar.host.urlhttp://localhost:9000 \ -Dsonar.login你的Token這里順序有講究先clean verify生成最新的 class 文件和測試報(bào)告再執(zhí)行sonar:sonar做分析。如果直接跑mvn sonar:sonar當(dāng)源碼有編譯錯誤時(shí)分析器拿不到完整的字節(jié)碼結(jié)果會少一部分規(guī)則檢查。sonar:sonar這個(gè)參數(shù)里的 host 地址寫的是外部訪問地址如果你在 Docker 容器里跑掃描器注意不要寫localhost要寫宿主機(jī) IP。多模塊項(xiàng)目還有一個(gè)常見問題默認(rèn)只會分析當(dāng)前模塊。如果有父子模塊需要在父pom.xml里加properties sonar.modulesmodule-a,module-b/sonar.modules /propertiessonar.modules是逗號分隔的模塊列表指定后掃描器會依次分析各模塊并匯總到同一個(gè)項(xiàng)目看板。不加這個(gè)參數(shù)時(shí)7.9 會把子模塊的代碼分析結(jié)果算到各自獨(dú)立的 projectKey 下質(zhì)量門禁的匯總數(shù)據(jù)就是錯的。3.3 接入 Jenkins用 Token 認(rèn)替代密碼構(gòu)建步驟只保留兩行Jenkins 接入時(shí)我見過不少團(tuán)隊(duì)在系統(tǒng)配置里填賬號密碼這種做法在 7.9 上也能通但一遇到密碼輪換就要改 Job。用 Token 就干凈得多。先在 Jenkins 的憑據(jù)管理里添加一個(gè) Secret text把 SonarQube Token 填進(jìn)去然后在構(gòu)建步驟里執(zhí)行mvn clean verify sonar:sonar \ -Dsonar.host.urlhttp://sonarqube:9000 \ -Dsonar.login${SONAR_TOKEN}${SONAR_TOKEN}是從 Jenkins 憑據(jù)注入的環(huán)境變量。需要注意的是sonar.host.url這里寫了http://sonarqube:9000這是 Jenkins 和 SonarQube 在同一個(gè) Docker 網(wǎng)絡(luò)時(shí)用的主機(jī)名如果你的 Jenkins 和 SonarQube 不在同一網(wǎng)絡(luò)改成實(shí)際 IP。還有一點(diǎn)7.9 的 Webhook 配置在「項(xiàng)目 → 管理 → Webhook」里Jenkins 的 SonarQube 插件依賴它接收分析完成通知沒配的話流水線會卡在等待階段直到超時(shí)。4. 質(zhì)量門禁不是默認(rèn)值把閾值調(diào)到團(tuán)隊(duì)能落地的程度4.1 先弄懂五個(gè)核心指標(biāo)Bug、漏洞、壞味道、覆蓋率、重復(fù)度SonarQube 7.9 的看板頁默認(rèn)展示的指標(biāo)是 Bug、漏洞、壞味道、覆蓋率、重復(fù)度中文版界面也沿用這套翻譯。這五個(gè)指標(biāo)對應(yīng)不同的質(zhì)量維度Bug 反映代碼里可能導(dǎo)致運(yùn)行時(shí)錯誤的問題比如空指針、數(shù)組越界漏洞集中在安全層面比如 SQL 注入、硬編碼密碼壞味道是代碼結(jié)構(gòu)問題像過長方法、命名不規(guī)范覆蓋率衡量的是測試對代碼行的覆蓋情況重復(fù)度表示相同代碼塊被復(fù)制的比例。7.9 里還有一個(gè)概念叫「新增代碼」New Code默認(rèn)以最近 30 天為周期。質(zhì)量門禁分了兩套規(guī)則——新增代碼一套、整體代碼一套。這套設(shè)計(jì)對老項(xiàng)目特別友好你可以讓整體代碼的壞味道存量慢慢還債但新增代碼必須滿足門檻防止問題繼續(xù)積累。很多團(tuán)隊(duì)第一次配門禁時(shí)只盯著全局指標(biāo)結(jié)果老項(xiàng)目永遠(yuǎn)紅燈反而沒人去管新增代碼的質(zhì)量了。4.2 規(guī)則集配置復(fù)制默認(rèn)規(guī)則再裁剪別直接改官方模板7.9 默認(rèn)把規(guī)則集和質(zhì)量門禁都設(shè)為「Sonar way」直接拿去跑老項(xiàng)目大概率會遇到大量誤報(bào)。比如某些命名規(guī)范規(guī)則在舊代碼里普遍存在但改起來要動幾百個(gè)類團(tuán)隊(duì)根本不接受。這時(shí)候正確的做法不是刪規(guī)則而是復(fù)制一份默認(rèn)規(guī)則集再調(diào)整。操作路徑是在界面頂部點(diǎn)「質(zhì)量配置」找到 Java 對應(yīng)的 Sonar way 規(guī)則集點(diǎn)「復(fù)制」命名成「My Java Rules」。然后在新的規(guī)則集里逐個(gè)查看規(guī)則把確實(shí)不適合當(dāng)前團(tuán)隊(duì)的規(guī)則停用。常見的誤報(bào)規(guī)則包括java:S100方法名必須符合規(guī)范、java:S115常量命名規(guī)范這些具體停哪些要看項(xiàng)目歷史和團(tuán)隊(duì)約定。復(fù)制規(guī)則集后要把項(xiàng)目關(guān)聯(lián)切到新規(guī)則集上「項(xiàng)目 → 管理 → 質(zhì)量配置」選擇剛建好的規(guī)則集。這里要注意一個(gè) 7.9 的行為修改規(guī)則集后已經(jīng)分析過的歷史數(shù)據(jù)不會自動重新計(jì)算需要在項(xiàng)目首頁點(diǎn)「重新分析」或者等下一次掃描觸發(fā)。如果規(guī)則改動比較大我一般直接重新跑一次全量掃描讓數(shù)據(jù)對齊。4.3 質(zhì)量門禁參數(shù)參考一套能直接落地的小團(tuán)隊(duì)閾值質(zhì)量門禁在「質(zhì)量門禁」菜單里配置同樣可以復(fù)制默認(rèn)模板再改。我整理過一套適合 5-20 人小團(tuán)隊(duì)的閾值直接用「條件」按鈕添加即可指標(biāo)整體代碼新增代碼Bug00漏洞00覆蓋率不低于 50%不低于 50%重復(fù)度不高于 5%不高于 3%壞味道無硬性限制不高于 5這套配置的核心邏輯是安全類問題零容忍新增代碼必須控制覆蓋率但壞味道存量不做剛性考核。你可能會問覆蓋率 50% 是不是太低了對于剛接上 SonarQube 的老項(xiàng)目80% 的默認(rèn)要求會讓團(tuán)隊(duì)直接在門外止步。先跑通流程后續(xù)再一個(gè)模塊一個(gè)模塊地提升閾值比一次性卡死更實(shí)際。配置完后點(diǎn)「應(yīng)用」到項(xiàng)目在 Pull Request 或合并代碼前跑一次掃描門禁結(jié)果是掛在每次分析記錄上的。7.9 的門禁失敗狀態(tài)會在掃描結(jié)果里明確標(biāo)紅提醒開發(fā)者處理后才允許合入這就是把質(zhì)量卡進(jìn)流程的落地方式。5. 避坑指南SonarQube 7.9 最常見的五個(gè)翻車點(diǎn)5.1 現(xiàn)象啟動日志報(bào)Unsupported database mysql進(jìn)程直接退出原因7.9 版本官方移除 MySQL 支持但很多從舊版本升級上來的團(tuán)隊(duì)還沿用 MySQL 配置。解決切換到 PostgreSQL或者把sonar.jdbc.url改回 PostgreSQL 連接串并重新初始化數(shù)據(jù)庫。血的教訓(xùn)是不要試圖用連接池中間件把 MySQL 偽裝成 PostgreSQL服務(wù)端啟動時(shí)會校驗(yàn)數(shù)據(jù)庫特性繞過校驗(yàn)也會在后續(xù)索引創(chuàng)建時(shí)失敗。從舊版本升級前先把 MySQL 數(shù)據(jù)用工具遷移到 PostgreSQL再啟動 7.9。5.2 現(xiàn)象容器反復(fù)重啟日志出現(xiàn)max virtual memory areas vm.max_map_count [65530] is too low原因Elasticsearch 需要大量內(nèi)存映射區(qū)域默認(rèn)內(nèi)核限制不夠。這個(gè)報(bào)錯在裸機(jī)部署和容器部署里都會遇到和鏡像無關(guān)。解決在宿主機(jī)執(zhí)行sudo sysctl -w vm.map_map_count262144。有些云服務(wù)器鏡像默認(rèn)值只有 65530改了之后容器內(nèi) ES 才能正常分配內(nèi)存。這個(gè)參數(shù)不會影響其他應(yīng)用放心調(diào)。5.3 現(xiàn)象掃描顯示BUILD SUCCESS但項(xiàng)目看板里一個(gè)文件都沒有日志里出現(xiàn)java files cant be analyzed原因sonar.java.binaries沒有指向編譯輸出目錄。7.9 分析 Java 代碼需要讀取 class 文件只給源碼路徑是不夠的。解決先確認(rèn)target/classes存在再在sonar-project.properties里配置sonar.java.binariestarget/classes。如果項(xiàng)目是純源碼沒有編譯環(huán)境可以在分析前執(zhí)行mvn compile或javac輸出 class 文件。這個(gè)參數(shù)漏配是新手最常見的坑沒有之一。5.4 現(xiàn)象裝了漢化包后登錄頁面能打開但登錄成功就無限刷新/白屏原因漢化包版本和 7.9 服務(wù)端版本不匹配。中文語言包分版本對應(yīng)不同的 SonarQube 主版本拿新版漢化包塞進(jìn) 7.9 會因?yàn)榻涌诓患嫒輰?dǎo)致前端渲染異常。解決刪除extensions/plugins下的語言包 jar 文件重啟服務(wù)端恢復(fù)登錄然后到官方插件倉庫下載與 7.9 完全匹配的漢化包版本重新放入插件目錄并重啟。這個(gè)坑我踩過之后形成了一個(gè)習(xí)慣安裝任何 SonarQube 插件前先確認(rèn)插件標(biāo)注的兼容版本范圍絕不在生產(chǎn)環(huán)境直接嘗試未知版本的插件。5.5 現(xiàn)象Java 項(xiàng)目覆蓋率一直顯示 0%測試明明有幾十個(gè)用例原因SonarQube 本身不做覆蓋率采集需要讀取 JaCoCo 生成的覆蓋率報(bào)告文件。默認(rèn)規(guī)則集沒配報(bào)告路徑時(shí)服務(wù)端拿不到數(shù)據(jù)。解決在sonar-project.properties里加一行sonar.coverage.jacoco.xmlReportPathstarget/site/jacoco/jacoco.xml前提是 Maven 構(gòu)建時(shí)已經(jīng)配置了 JaCoCo 插件并生成了報(bào)告文件。前端項(xiàng)目則用sonar.javascript.lcov.reportPathslcov.info指向 lcov 報(bào)告。覆蓋率一直為 0 時(shí)先確認(rèn)報(bào)告文件真實(shí)存在再檢查路徑寫沒寫對最后回頭看看BUILD SUCCESS日志里有沒有Coverage information was not collected這種提示詞。6. 從 7.9 升級到新版先備份再驗(yàn)證的三步走如果你不是非 7.9 不可而是想要新版的規(guī)則集和性能優(yōu)化升級前先把遷移路徑規(guī)劃好。SonarQube 官方支持跨 LTS 版本升級7.9 的下一步官方建議是 8.9 LTS再往后才考慮 9.x。直接跨兩個(gè) LTS 版本升級會出現(xiàn)數(shù)據(jù)模型不兼容報(bào)錯。以下三步走我每次升級都會執(zhí)行。第一步是備份。停止 SonarQube 服務(wù)備份數(shù)據(jù)庫和配置文件pg_dump -U sonar sonar sonar_backup.sql tar czf sonarqube_conf_backup.tar.gz /opt/sonarqube-7.9/conf /opt/sonarqube-7.9/extensions第二步是替換發(fā)行包。把新版 SonarQube 解壓到新目錄拷貝備份的extensions插件目錄和conf/sonar.properties再把數(shù)據(jù)庫指向同一個(gè) PostgreSQL 庫啟動后服務(wù)端會自動執(zhí)行數(shù)據(jù)遷移腳本。第三步是驗(yàn)證。訪問首頁確認(rèn)所有項(xiàng)目還在點(diǎn)進(jìn)項(xiàng)目看歷史曲線是否保留再用 sonar-scanner 跑一次全量掃描對比 Bug、覆蓋率等指標(biāo)是否與舊版一致。遷移過程中如果出現(xiàn)Database migration failed直接恢復(fù)備份重新來不要試圖手工改數(shù)據(jù)庫表結(jié)構(gòu)。升級 8.9 之后你會發(fā)現(xiàn)質(zhì)量門禁、規(guī)則集配置界面有變化項(xiàng)目數(shù)據(jù)本身不受影響。我經(jīng)歷過一次跳過 8.9 直接升 9.x 失敗后每次升級前都會先查一遍 LTS 版本的兼容矩陣再動手。從那以后升級這種事我再也不依賴直覺而是老老實(shí)實(shí)按驗(yàn)證清單走完。希望這份 7.9 的部署、掃描到遷移的踩坑整理能幫到你我平時(shí)用到的配置模板也都打包在下載目錄里直接拿去對照能省不少排查時(shí)間。本文還有配套的精品資源點(diǎn)擊獲取