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