個人開源專案如何上傳maven中央倉庫

語言: CN / TW / HK

最近在寫一些開源專案,想把自己寫的東西放到maven中央倉庫,提供給更多的人使用。所以寫這一篇文章,記錄一下自研開源專案jar包上傳同步maven中央倉庫成功的整個過程,這其中還是有不少的坑的。

  • 一、OSSRH賬號註冊於配置
  • 1.1.賬號註冊
  • 1.2.域名認證
  • 二、安裝GnuPG軟體,並生成簽名
  • 三、專案基礎配置
  • 四、maven打包配置
  • 五、CLOSE&RELEASE

  • 首先需要在sonatype JIRA管理平臺完成新建專案的申請,稽核通過之後才能進行上傳jar的操作
  • 上傳過程首先肯定是要本地進行打包,為保整專案資訊完整性及上傳過程安全性,需要進行特殊的操作,後文詳述
  • 本地打包之後首先傳入sonatype Nexus staging庫,這個庫只做臨時儲存,校驗內容完整、資訊完整之後才能通過平臺操作轉移到release庫。
  • 開源專案jar轉到到release庫之後,實際上需要我們操作的內容就全都完成了。sonatype maven庫的專案會自動同步到maven中央倉庫,這個過程會有延時,但延時很短。
  • 如果你使用國內的maven中央倉庫的映象,與maven中央倉庫會有比較大的延時,請耐心等待同步之後,才可以使用。

一、OSSRH賬號註冊於配置

sonatype是由社群支援的開源專案託管服務(Open Source Project Repository Hosting,簡稱OSSRH),它免費,開發者可以將自己的開源專案生成的maven jar包託管到這裡。 「當將maven專案打包部署到這裡之後,將自動同步到maven中央倉庫。」 所以不管怎樣,我們都需要先註冊一個sonatype平臺賬號。

1.1.賬號註冊

註冊地址:https://issues.sonatype.org/secure/Signup!default.jspa ,按照下圖所示的內容填寫自己的郵箱、全名、登陸使用者名稱username、登陸密碼passwprd,填寫驗證碼即可完成註冊。友情提示:註冊過程中的密碼的強度要求非常高,填寫完成之後最好找個記事本把密碼先記下來,以面後續使用的時候忘記。另外,註冊完成之後,沒有任何“註冊成功”相關的提示,而是直接跳轉到登入介面。

使用我們剛剛註冊的使用者登陸進去,登陸進去之後會提示我們選擇語言:我習慣中文,當然選中文;然後會提示我們選擇一個頭像;然後會提示我們要進行什麼工作,“瀏覽當前專案即可”,這一步不重要。

進入JIRA管理平臺之後,點選頂部導航欄的“新建”按鈕,然後在彈出的模態框中填寫資訊,如下:

  • 專案和問題型別,一定要選對,按圖操作
  • 概要內容填寫專案名稱即可,Group Id 根據專案的maven座標按需填寫,與maven專案pom配置一致。(這裡需要注意:實際操作的時候,先把下文中的《1.2.域名認證》看完,再做這部操作,存在對應關係避免做錯)
  • 程式碼上傳GitHub之後的專案URL、scm版本管理url(帶.git)依次如圖填寫。

點選新建即可,新建問題之後。實際上是發起了一個新建專案稽核的稽核工作流,會有人稽核你所填寫的資訊。

1.2.域名認證

因為上文中Group ID我填寫的是我自己購買的域名,所以我需要證明這個域名是我的。證明的方式也很簡單,就是在我的域名購買的平臺,給域名增加一條txt的域名解析記錄,域名解析記錄的值會在JIRA平臺的流程稽核結果記錄中給出,如下圖中的紅色框起來的內容(本次新建專案申請的流水編號:OSSRH-83481)。

如果沒有域名怎麼辦?沒有域名你可以給Group Id填寫github的使用者域,如:​ ​com.github.<gihub使用者名稱>​ ​​。填寫github使用者域,驗證方式也不一樣,需要你在github中新建一個空的倉庫,倉庫的名稱是​ ​OSSRH-83481​ ​ 。

因為我的域名是在阿里雲買的,所以我去阿里云為該域名新增一個TXT型別的解析記錄值。

如果你不太確定TXT解析記錄值是否生效,可以通過windows CMD命令列,響應如下的資訊證明設定正確

> nslookup -type=TXT 你的域名
伺服器:  dns.google
Address:  8.8.8.8

非權威應答:
你的域名       text =

        "OSSRH-83481"

域名解析記錄值新增完成之後,回到sonatype JIRA管理平臺。在​ ​OSSRH-83481​ ​問題裡面如下圖所示的位置,有一個Respose按鈕,點選該按鈕證明你已經完成了域名認證操作。(因為我是操作完成之後,寫的這篇文章,所以這個按鈕已經沒了,我模擬了一個)

在整個的新建問題,專案流程稽核過程中,你的註冊郵箱會不斷的收到sonatype JIRA管理平臺發出的郵件,提示你稽核流程進行到了什麼階段。(這個稽核過程非常迅速,應該是機器人蔘與的稽核,不是人為操作的,我用了5分鐘就完成了整個稽核流程). 稽核通過之後,你會看到如下的狀態:已解決。

二、安裝GnuPG軟體,並生成簽名

新建專案稽核通過之後,我們需要在開發PC上安裝GnuPG,因為我們上傳到sonatype maven庫的所有檔案都要經過GnuPG進行簽名,不經過簽名的檔案無法上傳成功。下載地址:https://gpg4win.org/thanks-for-download.html 。下載完成之後,傻瓜式的“下一步”“下一步”安裝即可。下載完成之後,我們開啟windows的 CMD命令列,執行如下命令。(注意:我的操作都是在CMD命令列下面執行的,不要power shell ,不要git bash。我都試過,不是不行,是操作過程不一致。如果和我的操作過程不一致,可能導致你操作失敗!)

gpg --gen-key

下圖中紅色的部分是我填寫的內容,我的名字、郵箱,以及一個O表示ok。會提示我們輸入一個Passphrase,填寫2遍。這個Passphrase就是一個密碼,一定要記住,下文會用到。

GnuPG簽名的公鑰私鑰對生成完成之後,可以使用如下命令檢視結果

C:\Users\hanxt>gpg --list-key
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2024-08-09
C:\Users\hanxt\AppData\Roaming\gnupg\pubring.kbx
------------------------------------------------
pub   ed25519 2022-08-10 [SC] [expires: 2024-08-09]
      6B4F6A477A1BE195326AEAFA0EE41461FB92CD0B
uid           [ultimate] HanXiaotong <[email protected]>
sub   cv25519 2022-08-10 [E] [expires: 2024-08-09]

金鑰對生成完成之後,將其公鑰發往sonatype認可的keyserver,公鑰的字串可以通過上文中的​ ​gpg --list-key​ ​檢視到

gpg --keyserver keyserver.ubuntu.com --send-keys 6B4F6A477A1BE195326AEAFA0EE41461FB92CD0B

通過下面的命令列,可以校驗公鑰的字串發往伺服器是否成功。

gpg --keyserver keyserver.ubuntu.com --recv-keys 6B4F6A477A1BE195326AEAFA0EE41461FB92CD0B

三、專案基礎配置

完成上述的準備工作,我們要對專案進行打包了,打包工具我用的maven。需要檢查如下資訊是否配置完整,如果沒有配置完整,請補充!缺少這些資訊,maven專案後續將無法轉成release狀態。請根據自己專案的實際情況填寫。

<groupId>com.zimug</groupId>
<artifactId>zimug-monitor-threadpool</artifactId>
<version>1.0</version>

<name>${project.groupId}:${project.artifactId}</name>
<description>spring boot starter  for thread pool monitor  </description>
<url>https://github.com/hanxt/zimug-monitor-threadpool</url>

license中填寫開源協議,scm填寫專案的git程式碼倉庫地址,developer填寫開發人員的聯絡方式。

<licenses>
    <license>
      <name>BSD 3-Clause</name>
      <url>https://spdx.org/licenses/BSD-3-Clause.html</url>
    </license>
  </licenses>
  <scm>
    <connection>https://github.com/hanxt/zimug-monitor-threadpool.git</connection>
    <url>https://github.com/hanxt/zimug-monitor-threadpool</url>
  </scm>
  <developers>
    <developer>
      <name>zimug</name>
      <email>[email protected]</email>
      <roles>
        <role>Developer</role>
      </roles>
      <timezone>+8</timezone>
    </developer>
  </developers>

四、maven打包配置

只有在sonatype JIRA管理平臺上註冊的使用者,才能將開源專案 jar上傳到sonatype Nexus 倉庫。所以我們在上傳jar檔案的時候,有必要告知伺服器端我們的註冊使用者名稱及密碼。找到maven的setting.xml,新增如下配置:

<servers>
    <server>
      <id>ossrh</id> 
      <username>sonatype註冊username</username>
      <password>sonatype註冊使用者的password</password>
    </server>
</servers>

setting.xml是針對maven進行全域性配置,除此之外還需要針對專案進行配置pom.xml,首先配置遠端倉庫的地址。需要注意的是這裡的id與setting.xml中sever配置的id要一致。

<distributionManagement>
  <snapshotRepository>
    <id>ossrh</id>
    <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
  </snapshotRepository>
  <repository>
    <id>ossrh</id>
    <url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
  </repository>
</distributionManagement>

這裡有幾個需要注意的地方,

  • snapshotRepository是專案快照版本snapshot上傳地址,如果專案的版本號,如:1.0-SNAPSHOT,會上傳到這個倉庫。
  • 通常情況下repository是我們真正需要釋出專案的遠端倉庫上傳地址。需要注意的是我們這裡寫的是staging暫存地址,而不是release版本的地址。(為什麼這麼做?後文詳述)
  • 另外需要注意的是,我們上傳的遠端倉庫的地址是帶s01字首的,而比較舊的文章中不帶s01字首。這是因為舊的sonatype maven倉庫已經資源滿載了,所以官方新建了一個s01 maven倉庫,未來可能還會有s02、s03。現階段在sonatype JIRA管理平臺上註冊的使用者,只能上傳這個新的s01倉庫。

遠端倉庫配置完成之後,我們還需要針對專案pom.xml增加一些打包配置,這些配置基本不用修改,原樣貼上進去即可。(其中maven-gpg-plugin外掛會呼叫上文中安裝的GnuPG軟體,對檔案進行簽名)

<profiles>
  <profile>
    <id>release</id>
    <build>
      <plugins>
        <!-- Source -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-source-plugin</artifactId>
          <version>2.2.1</version>
          <executions>
            <execution>
              <phase>package</phase>
              <goals>
                <goal>jar-no-fork</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <!-- Javadoc -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-javadoc-plugin</artifactId>
          <version>2.9.1</version>
          <configuration>
            <show>private</show>
            <nohelp>true</nohelp>
            <charset>UTF-8</charset>
            <encoding>UTF-8</encoding>
            <docencoding>UTF-8</docencoding>
            <additionalparam>-Xdoclint:none</additionalparam>
            <!-- TODO 臨時解決不規範的javadoc生成報錯,後面要規範化後把這行去掉 -->
          </configuration>
          <executions>
            <execution>
              <phase>package</phase>
              <goals>
                <goal>jar</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <!-- GPG -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-gpg-plugin</artifactId>
          <version>1.6</version>
          <executions>
            <execution>
              <phase>verify</phase>
              <goals>
                <goal>sign</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <!--Compiler -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.0</version>
          <configuration>
            <source>1.8</source>
            <target>1.8</target>
            <fork>true</fork>
            <verbose>true</verbose>
            <encoding>UTF-8</encoding>
          </configuration>
        </plugin>
        <!--Release -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-release-plugin</artifactId>
          <version>2.5.1</version>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

在專案根目錄下,執行下面的命令進行maven打包操作(同時將專案jar deploy到遠端maven倉庫),在打包執行過程中,會彈出一個對話方塊提示你輸入金鑰(Passphrase),輸入上文《安裝GnuPG軟體,並生成簽名》章節中你填寫的Passphrase即可。

mvn clean install deploy -P release

這裡需要注意的是:

  • 不要使用IDEA的maven UI打包,IDEA的maven UI打包會報錯,無法執行gpg命令。至於具體原因我也沒搞清楚,使用上文中的CMD命令列打包即可。
  • 使用mvn命令列打包的時候,需要注意你的JAVA_HOME環境變數的指向,是不是你期望的版本。我的電腦上安裝了多個版本的JDK,JAVA_HOME指向的是JDK11,而我希望打包的版本是JDK8。有可能造成混亂!
  • 如果maven depoly釋出命令報401 authentication錯誤,是因為你的maven的setting.xml的server配置的使用者名稱密碼錯誤,或者setting.xml的server配置id與pom裡面配置的repository id不一致導致的。也有可能你的電腦上maven 多個版本,專案使用的不是同一個setting.xml。
  • 如果報400錯誤,很有可能是你已經上傳過的jar,同一個版本再次重複上傳了。

五、CLOSE&RELEASE

專案jar正確的上傳到nexus repository倉庫之後,我們還需要進行進一步的操作。這是因為我們上傳的jar放入了staging暫存庫裡面,我們需要把它轉到release庫,這其中sonatype平臺會針對你的專案資訊、jar文件、原始碼等內容進行完整性校驗,完整性校驗不通過的專案是無法轉到release的,也就無法同步到maven中央倉庫。

這些操作需要我們通過介面進行,使用sonatype註冊使用者進行登入:https://s01.oss.sonatype.org/ 。如圖所示,如果我們專案打包上傳成功,會在Staging Repository裡面看到一個Repository,將其勾選。點選“CLOSE”按鈕之後,會自動進行完整性校驗,校驗結果可以雙擊勾選倉庫所在行進行檢視。(只要按照我上文中的內容,將pom中的專案資訊以及打包配置填寫完整,這裡基本都會校驗通過)

CLOSE校驗通過之後,重新整理幾次頁面,Release按鈕就變成可點選的狀態。此時點選Release按鈕,就將專案jar從Staging暫存庫,轉移到了Release正式庫。實際上需要我們操作的內容就全都完成了。

sonatype maven庫的專案會自動同步到maven中央倉庫,通過maven座標引入使用即可,不要著急,這個過程可能會有一些延時。上傳之後可能一段時間內無法在maven中央倉庫搜尋到,但是使用maven座標下載jar包也沒有問題。

一切都ok之後,最好回到sonatype JIRA管理平臺將“問題”關閉,這樣sonatype JIRA管理流程就全部完成了。

碼文不易,如果您覺得有幫助,請幫忙點選在看或者分享,沒有您的支援我可能無法堅持下去! 歡迎關注公眾號:字母哥雜談,回覆003贈送作者專欄《docker修煉之道》的PDF成書版本。