使用gpg插件发布jar包到Maven中央仓库完整实践

ゞ浴缸里的玫瑰 2022-04-22 07:46 936阅读 0赞

本文记录了在maven环境下使用gpg插件将 jar 包部署到中央仓库并快速检验和更新的完整实践过程。相对于网上其他教程使用oss-parent作为父工程的方法，这种方法入侵度低，自由度高，也是官方推荐使用的。实践过程解决了gpg验证以及javadoc注解不规范的问题。

### 文章目录 ###

*   *  先行知识
     *   *  1 项目基础配置
         *  2 Maven发布相关网址
         *  3 发布事项
     *  一 注册并提交工单（register sonatype）
     *  二 使用gpg生成密钥
     *  三 完成maven配置
     *   *  1 配置 setting.xml
         *  2 配置pom文件基本信息
         *  3 在pom文件里配置gpg相关插件
     *  四 完成第一次发布
     *   *  1 运行 deploy
         *  2 到issue添加comment
         *  3 查看 search.maven.org
     *  五 版本更新
     *  六 其他

## 先行知识 ##

### 1 项目基础配置 ###

首先需要注意项目的 **groupId**,下文注册sonatype账号时也需要填写 **groupId** ,两者最好一致，并确保你拥有该域名所有权，我推荐用**GitHub个人主页**作为对应地址。格式为 **com.github.username**  
本文以如下配置为例：

<groupId>com.github.linshenkx</groupId>
        <artifactId>rpc-netty-spring-boot-starter</artifactId>
        <version>1.0.0.RELEASE</version>

### 2 Maven发布相关网址 ###

在整个发布过程中，有以下3个关键网址，注意前2个共用一个账号。

1.  工单管理：[https://issues.sonatype.org][https_issues.sonatype.org]  
    负责申请上传资格及完成第一次上传，后续更新不需要使用，相当于一个启动装置。
2.  构件仓库 : [https://oss.sonatype.org][https_oss.sonatype.org]  
    上传的jar包会先存放到这里，在这里进行 Release 后即可发布到maven中央仓库。
3.  镜像仓库: [http://search.maven.org][http_search.maven.org]  
    最终成功发布的jar可以在这里搜到。

### 3 发布事项 ###

网上有些人说使用相同版本号部署可以覆盖原版本，经试验是不行的，也很好理解，对于同一个版本的jar包，怎么可能因为拉取时间的不同而导致获得内容的不同呢？所以，应该将每一次上传部署都看作不可逆操作，谨慎对待。

## 一 注册并提交工单（register sonatype） ##

首先进入 [https://issues.sonatype.org][https_issues.sonatype.org] 注册账号并登录  
然后点击最上面的 Create创建Issue，选择Project和Issue Type如下  
![Create Issue][]  
除了这两个选择项外，其他的必填项按照提示填就好，需要特别注意的是，你要拥有GroupId对应的域名的所有权，私有域名的话需要验证所有权会比较麻烦(在Attachment项提供证书)，个人的话最好就是使用项目对应托管平台的主页，这样可以省去验证的步骤。创建完成可见如下:  
注意这个过程是需要后台管理员审核的，一般在2个小时左右即会有回复，在审核通过之前 Issue 的状态将是 open，通过后为 resolved ，有问题的话 Resolution 将显示 Unresolved 直到你解决后才会显示为 Fixed。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70]  
项目的驱动将通过Comments来进行，如下，通过后管理员将添加如下comment

> Configuration has been prepared, now you can:  
> Deploy snapshot artifacts into repository [https://oss.sonatype.org/content/repositories/snapshots][https_oss.sonatype.org_content_repositories_snapshots]  
> Deploy release artifacts into the staging repository [https://oss.sonatype.org/service/local/staging/deploy/maven2][https_oss.sonatype.org_service_local_staging_deploy_maven2]  
> Promote staged artifacts into repository ‘Releases’  
> Download snapshot and release artifacts from group [https://oss.sonatype.org/content/groups/public][https_oss.sonatype.org_content_groups_public]  
> Download snapshot, release and staged artifacts from staging group [https://oss.sonatype.org/content/groups/staging][https_oss.sonatype.org_content_groups_staging]

前面两个仓库用于上传，分别对应工程的 snapshots版本和 release版本，要配置到pom文件里。  
发布成功的工程可以通过后面两个仓库查看和下载，晚点会同步到中央仓库里。

## 二 使用gpg生成密钥 ##

这一步我主要参考了官方指南 [https://central.sonatype.org/pages/working-with-pgp-signatures.html][https_central.sonatype.org_pages_working-with-pgp-signatures.html] 上面用命令行的方式一步步写得很清楚了，不过我发现其过程比较适用于Linux环境，Windows环境下有所不同  
我使用的环境是window和maven，使用mac和gradle的也可以参考，但后面maven配置具体步骤会有不同，需要注意。  
这里我推荐使用gpg的gui工具，可视化生成密钥，也可以使用命令行。  
Windows的话先到 [https://gpg4win.org/download.html][https_gpg4win.org_download.html] 下载最新的版本，直接安装即可打开即可

1.  新建密钥对（OpenPGP类型）  
    这里需要填入名字和电子邮件，然后注意可以在高级设置那里将有效期一栏的小勾取消掉，即有效期无限，如下  
    ![新建密钥对][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 1]
2.  确认信息并输入密码
3.  选择将公钥上传到目录服务  
    注意：如果这里不点的话后面分发后将无法在服务器找到对应公钥  
    ![选择将公钥上传到目录服务][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 2]
4.  右键选择生成的证书在服务器上发布
5.  根据密钥ID在服务器上查找公钥  
    最终必须保证这一步成功！如下  
    ![查找成功][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 3]

> 注意：这里有个bug，如果生成的密钥ID的第一个字符是数字0的话，在下面使用maven-gpg插件的时候可能会被自动去掉导致密钥找不到，所以保险起见遇到这种情况就重新生成证书

## 三 完成maven配置 ##

这里主要参考 [https://central.sonatype.org/pages/apache-maven.html][https_central.sonatype.org_pages_apache-maven.html]  
注意网上很多教程都使用了将pom父工程设置为 org.sonatype.oss:oss-parent的方法，这种方法对工程侵入性极强，官方已经标记为 不推荐使用 了。

### 1 配置 setting.xml ###

<settings>
      <servers>
        <server>
          <id>ossrh</id>
          <username>your-jira-id</username>
          <password>your-jira-pwd</password>
        </server>
      </servers>
    </settings>

如果使用的是Mac系统，由于使用的是 gpg2 还需要在正在使用的profile下配置如下属性

<properties>
            <gpg.executable>gpg2</gpg.executable>
            <gpg.passphrase>the_pass_phrase</gpg.passphrase>
          </properties>

### 2 配置pom文件基本信息 ###

在pom文件里添加developers、scm、licenses等信息,如下

<developers>
            <developer>
                <name>LinShen</name>
                <email>1558867741@qq.com</email>
            </developer>
        </developers>
    
        <scm>
            <connection>scm:git:https://github.com/linshenkx/rpc-netty-spring-boot-starter</connection>
            <developerConnection>scm:git:git@github.com/linshenkx/rpc-netty-spring-boot-starter.git</developerConnection>
            <url>https://github.com/linshenkx/rpc-netty-spring-boot-starterr</url>
            <tag>HEAD</tag>
        </scm>
    
        <licenses>
            <license>
                <name>The Apache Software License, Version 2.0</name>
                <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
                <distribution>repo</distribution>
                <comments>A business-friendly OSS license</comments>
            </license>
        </licenses>

### 3 在pom文件里配置gpg相关插件 ###

根据官方指南，这里需要4个插件，

1.  maven-source-plugin 用来生成Source Jar文件
2.  maven-javadoc-plugin 用来生成 javadoc 文档
3.  maven-gpg-plugin 用来对工程文件进行自动签名
4.  nexus-staging-maven-plugin 用来将工程发布到中央仓库  
    另外注意生成javadoc文档时需要指定关闭doclint，不然可能因为使用了不规范的javadoc注解而导致失败，完整配置如下

<build>
            <plugins>
                
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-source-plugin</artifactId>
                    <version>2.2.1</version>
                    <executions>
                        <execution>
                            <id>attach-sources</id>
                            <goals>
                                <goal>jar-no-fork</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
                
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>2.9.1</version>
                    <executions>
                        <execution>
                            <id>attach-javadocs</id>
                            <goals>
                                <goal>jar</goal>
                            </goals>
                            <configuration>
                                <additionalparam>-Xdoclint:none</additionalparam>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
                
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-gpg-plugin</artifactId>
                    <version>1.5</version>
                    <executions>
                        <execution>
                            <id>sign-artifacts</id>
                            <phase>verify</phase>
                            <goals>
                                <goal>sign</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
                
                <plugin>
                    <groupId>org.sonatype.plugins</groupId>
                    <artifactId>nexus-staging-maven-plugin</artifactId>
                    <version>1.6.7</version>
                    <extensions>true</extensions>
                    <configuration>
                        <serverId>ossrh</serverId>
                        <nexusUrl>https://oss.sonatype.org/</nexusUrl>
                        <autoReleaseAfterClose>true</autoReleaseAfterClose>
                    </configuration>
                </plugin>
            </plugins>
        </build>

注意我这里在 nexus-staging-maven-plugin 插件里开启了自动 Release。也可以关掉，然后登录构件仓库 : [https://oss.sonatype.org][https_oss.sonatype.org] 手动去 close然后 relseae

## 四 完成第一次发布 ##

### 1 运行 deploy ###

这里建议在确保能正确运行的前提下跳过测试，即在pom文件所在目录下运行如下指令

mvn clean deploy -Dmaven.test.skip=true

运行的过程会要求输入 gpg的私钥密钥。  
最后的输出应该如下，即先上传再close，再release。  
中间如果出错直接在控制台就可以查看到信息，也可以去构件仓库看。  
![输出][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 4]

### 2 到issue添加comment ###

上述步骤顺利完成后到issue下评论，如下，第一次在close的时候就已经失败了，我没有注意到就去comment，后台管理员提醒我去查看错误信息，第二次comment后就顺利通过。大概过两个小时就可以去 [search.maven.org][http_search.maven.org] 检索上传的jar包了。  
![添加comment][comment]

### 3 查看 [search.maven.org][http_search.maven.org] ###

如下，根据groupId进行检索，需要注意的是，当前结果还不是完整的，事实上，有些快一点的2个小时后即可检索到，有些则花了6个小时，有些还不止，所以当工程比较大的时候请耐心等候。  
![search.maven.org][]  
如果担心是哪里出问题的话可以先到 [https://oss.sonatype.org/content/groups/public][https_oss.sonatype.org_content_groups_public] 或者 [https://oss.sonatype.org/content/groups/staging][https_oss.sonatype.org_content_groups_staging] 查看上传是否成功，也可以在pom文件里将设置这些仓库，可以最快拉取到最新版本。

## 五 版本更新 ##

更改版本号再直接部署操作即可，不需要再去issue进行comment，等待时间会短很多。网上有些人说使用相同版本号部署可以覆盖原版本，经试验是不行的，也很好理解，对于同一个版本的jar包，怎么可能因为拉取时间的不同而导致获得内容的不同呢？所以，应该将每一次上传部署都看作不可逆操作，谨慎对待。

## 六 其他 ##

参考资料：  
[https://central.sonatype.org/pages/apache-maven.html][https_central.sonatype.org_pages_apache-maven.html]  
[https://central.sonatype.org/pages/working-with-pgp-signatures.html][https_central.sonatype.org_pages_working-with-pgp-signatures.html]  
[https://www.gnupg.org/howtos/zh/index.html][https_www.gnupg.org_howtos_zh_index.html]  
[https://docs.kde.org/stable5/en/pim/kleopatra/index.html][https_docs.kde.org_stable5_en_pim_kleopatra_index.html]  
[https://stackoverflow.com/questions/28846802/how-to-manually-publish-jar-to-maven-central/42917618][https_stackoverflow.com_questions_28846802_how-to-manually-publish-jar-to-maven-central_42917618]

[https_issues.sonatype.org]: https://issues.sonatype.org
[https_oss.sonatype.org]: https://oss.sonatype.org
[http_search.maven.org]: http://search.maven.org
[Create Issue]: /images/20220422/6ed267b72df8438a9accae0d383758d7.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70]: /images/20220422/eb1d390591a946cebc86f824e0fcae45.png
[https_oss.sonatype.org_content_repositories_snapshots]: https://oss.sonatype.org/content/repositories/snapshots
[https_oss.sonatype.org_service_local_staging_deploy_maven2]: https://oss.sonatype.org/service/local/staging/deploy/maven2
[https_oss.sonatype.org_content_groups_public]: https://oss.sonatype.org/content/groups/public
[https_oss.sonatype.org_content_groups_staging]: https://oss.sonatype.org/content/groups/staging
[https_central.sonatype.org_pages_working-with-pgp-signatures.html]: https://central.sonatype.org/pages/working-with-pgp-signatures.html
[https_gpg4win.org_download.html]: https://gpg4win.org/download.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 1]: /images/20220422/d5ea11d35d494ecaa62f6688fc8cb1dd.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 2]: /images/20220422/5ebd6a2dce4e4eccaec286db478912ce.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 3]: /images/20220422/d0479c9c9d344ed69a59b061b8fddd2e.png
[https_central.sonatype.org_pages_apache-maven.html]: https://central.sonatype.org/pages/apache-maven.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FsaW55dWE_size_16_color_FFFFFF_t_70 4]: /images/20220422/ded9a7f04cbc4a3dba29c7703a7173f5.png
[comment]: /images/20220422/2b968d11984f45de9cd7e55dd70b21d6.png
[search.maven.org]: /images/20220422/43cb9243d2d64b6898775ef8ee110052.png
[https_www.gnupg.org_howtos_zh_index.html]: https://www.gnupg.org/howtos/zh/index.html
[https_docs.kde.org_stable5_en_pim_kleopatra_index.html]: https://docs.kde.org/stable5/en/pim/kleopatra/index.html
[https_stackoverflow.com_questions_28846802_how-to-manually-publish-jar-to-maven-central_42917618]: https://stackoverflow.com/questions/28846802/how-to-manually-publish-jar-to-maven-central/42917618