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

本文记录了在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个共用一个账号。

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

3 发布事项

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

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

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

Configuration has been prepared, now you can:
Deploy snapshot artifacts into repository https://oss.sonatype.org/content/repositories/snapshots
Deploy release artifacts into the staging repository 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
Download snapshot, release and staged artifacts from staging group https://oss.sonatype.org/content/groups/staging

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

二使用gpg生成密钥

这一步我主要参考了官方指南 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 下载最新的版本，直接安装即可打开即可

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

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

三完成maven配置

这里主要参考 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>[email protected]</email>
        </developer>
    </developers>

    <scm>
        <connection>scm:git:https://github.com/linshenkx/rpc-netty-spring-boot-starter</connection>
        <developerConnection>scm:git:[email protected]/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个插件，

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

    <build>
        <plugins>
            <!--生成Source jar文件-->
            <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>
            <!--生成Javadoc，关闭doclint,避免注解检查不通过-->
            <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>
            <!--Maven GPG插件用于使用以下配置对组件进行签名-->
            <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>
            <!--Nexus Staging Maven插件是将组件部署到OSSRH并将其发布到Central Repository的推荐方法-->
            <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 手动去 close然后 relseae

四完成第一次发布

1 运行 deploy

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

mvn clean deploy -Dmaven.test.skip=true

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

2 到issue添加comment

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

3 查看 search.maven.org

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

五版本更新

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

六其他

参考资料：
https://central.sonatype.org/pages/apache-maven.html
https://central.sonatype.org/pages/working-with-pgp-signatures.html
https://www.gnupg.org/howtos/zh/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