本文记录了在maven环境下使用gpg插件将 jar 包部署到中央仓库并快速检验和更新的完整实践过程。相对于网上其他教程使用oss-parent作为父工程的方法,这种方法入侵度低,自由度高,也是官方推荐使用的。实践过程解决了gpg验证以及javadoc注解不规范的问题。
文章目录
先行知识
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如下
除了这两个选择项外,其他的必填项按照提示填就好,需要特别注意的是,你要拥有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>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个插件,
- 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包了。
3 查看 search.maven.org
如下,根据groupId进行检索,需要注意的是,当前结果还不是完整的,事实上,有些快一点的2个小时后即可检索到,有些则花了6个小时,有些还不止,所以当工程比较大的时候请耐心等候。
如果担心是哪里出问题的话可以先到 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