Maven仓库使用与私有仓库搭建

本文为“拥抱Android Studio”系列第四篇。作者何畅彬，现任BugTags技术总监，关注移动SDK研发、后端服务设计与实现，个人博客： http://kvh.io/。

使用 Android Studio，必然要与 maven 仓库频繁打交道，在创造和分享自己打造的 Android library 的时候，maven 仓库的知识更是必不可少。本章将为开发者系统梳理这方面的知识。

使用、创造和分享

笔者曾经不思量力的思考过『是什么推动了互联网技术的快速发展？』这种伟大的命题。结论是，除了摩尔定律之外，技术经验的快速积累和广泛分享，也是重要的原因。

有人戏称，『写 Java，首先要学会选包』，在这里不好评论对错。不过这句话里面，至少包含两层意思：首先 Java 有大量的现成的依赖包，不必要自己造轮子；其次，Java 的包存放较为集中，集成方式也方便。

笔者从事 Android 和 Java 开发以来，经历了几个阶段：

闭门造轮子 > 使用别人的轮子 > 开门造轮子 > 分享轮子

在使用、创造、分享轮子的过程中，maven 仓库的使用可谓必备技能。

相信各位使用 Android Studio，对于 jcenter()、mavenCentral() 等概念应该是司空见惯了。程序员要知其然，知其所以然。本篇将按照如下脉络介绍在 Android Studio 中 Maven 仓库相关的概念和应用。

• Maven 包
• Maven 仓库
• 发布包到本地仓库
• 发布包到 Bintray Jcenter 远程仓库
• 发布包到 Sonatype MavenCentral 远程仓库
• 搭建私有 Sonatype 仓库
• 搭建私有 Artifacotory 仓库

Maven 包（Package）

至于 Maven 是什么，请参考 Apache Maven。

对于 Android 开发者而言，只需要知道 Maven 是一种构建工具，Maven 包是由所谓 POM（Project Object Model）所定义的文件包格式即可。

Gradle 可以使用 Maven 包，而且大部分的 Android 能够使用的远程依赖包都是 Maven 包。

先来看一个托管在某仓库上的 Maven 包：Bugtags-Android-Lib 所包含的内容：

bugtags-lib-1.1.0-javadoc.jar//javadoc 文件
bugtags-lib-1.1.0-javadoc.jar.asc//javadoc 文件的签名
bugtags-lib-1.1.0-sources.jar//源码文件
bugtags-lib-1.1.0-sources.jar.asc//源码文件的签名
bugtags-lib-1.1.0.aar//Android Library 的主文件包
bugtags-lib-1.1.0.aar.asc//主文件包的签名
bugtags-lib-1.1.0.pom//包描述文件
bugtags-lib-1.1.0.pom.asc//描述文件的签名

对于一个合符规范的 Maven Package，pom 文件、aar（或者 jar） 文件是必须的。

而 javadoc 文件、源码文件、签名文件都不是必要的，但是某些公开仓库（如 mavenCentral ）有此要求。

使用这个包的方式，相信大家已经很熟悉了：

dependencies {
    compile 'com.bugtags.library:bugtags-lib:1.1.0'
}

POM 文件

一个 Maven Package，最重要就是 POM（Project Object Model） 文件，这其实是一个 XML 文件，这里截取 Bugtags-Android-Lib POM 主要内容如下：

<xml version="1.0" encoding="UTF-8">
<project xsi:schemaLocation="http://maven.apache.org/POM/
4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.bugtags.library</groupId>
  <artifactId>bugtags-lib</artifactId>
  <version>1.1.0</version>
  <packaging>aar</packaging>
  <dependencies>
    <dependency>
      <groupId>com.android.support</groupId>
      <artifactId>support-v4</artifactId>
      <version>19.0.0</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>
</project>

• modelVersion: 从 mvn 2.x 起，这个数值都是4.0.0
• packaging：打包方式，aar 是 Android Libirary 的打包方式，常用的还有 jar
• dependency：声明依赖列表
• 包的唯一标示：

<!--包组 id，通常是发布者拥有的域名的反向，以免跟别人的重复-->
<groupId>com.bugtags.library</groupId>
<!--包 artifactId，不好意思我也不知道如何准确翻译，其实就是组以下应该有一个更小的归类-->
<artifactId>bugtags-lib</artifactId>
<!--包版本-->
<version>1.1.0</version>

其中三个字段与 Gradle 的依赖格式 'com.bugtags.library:bugtags-lib:1.1.0' 冒号分割的三段一一对应。这就解释了所谓的 Gradle 兼容 Maven 包。

Maven 仓库

Maven 包集中存放的地方，就是 Maven 仓库。这些仓库，可以是放在本地，也可以放在某个远程服务器上。 可以是私有仓库，也可以是公开的。下面是笔者日常开发用的库列表：

mavenCentral();
jcenter()
maven {
     url 'file:///Users/my-user-name/Documents/Android/repo/'
}
maven {
     url 'http://192.168.99.100:8081/content/repositories/releases/'
}

Android Studio Gradle 主要支持两个 Maven 中央库：mavenCentral 和 jcenter。

• mavenCentral 是最早的 maven 中央仓库
• jcenter 是 Android Studio 0.8 版本起的默认 maven 中央仓库
• 第三个是笔者的本机的仓库
• 第四个是笔者部署在内网服务器的私有仓库

读者可能会发现两个问题：

• 为什么有了 mavenCentral，谷歌还切换到了 jcenter？
• maven { url : xxx}，这种格式可以配置任何一个存在的仓库？

解释如下：

jcenter VS. mavenCentral

根据这篇博客，jcenter 具有如下优胜特点，使得谷歌进行切换：

• jcenter 是一个 mavenCentral 的超集，jcenter 还包含了其他 maven 包
• jcenter 具有更好的 cdn，默认支持 https，这个对于谷歌有巨大吸引力
• bintray（jcenter 的服务提供商）表示 jcenter 具有更好的性能
• 有数据表明 bintray jcenter 占用更少的本地缓存空间
• 更好的交互界面，可以从 jcenter 向 mavenCentral 同步包（下面两个平台的使用教程将会证实这一点）

笔者亲测，在 bintray 上发布包到 jcenter 在易用性上的确比 在 sonatype 发布到到 mavenCentral 要好得多。

使用符合规范的 maven 仓库

没错，你可以通过 maven { url : xxx }使用任何一个符合 maven 规范的仓库。

• 存在本地的

maven {
 url 'file:///Users/my-user-name/Documents/Android/repo/'
}

• 存在内网服务器的

maven {
 url 'http://192.168.99.100:8081/content/repositories/releases/'
}

• 存在某个远程服务器的

maven {
    url 'https://raw.githubusercontent.com/liaohuqiu/umeng-libs/master/repository'
}

此仓库由 liaohuqiu 同学为方便大家使用友盟开发者工具，把相应的包做成了符合规范的 Maven 包，托管在 github 项目中。

发布 Maven 包

使用 maven 包相信已经很清楚了，让我们更进一步。

当我们在日常开发实践中，积累了一些公共库，想要固定下来，被自己或者别人方便的使用，就需要发布 maven 包。

一个符合规范的 maven 包至少包含 pom 文件和主文件包。难道这些都要手动编写和创建么？

答案是：有了 gradle 插件，你只需要干很少的事儿。

全局设定

下面以发布这系列包为示例：

• groupId: com.as-gradle.demo //改成你的 groupId
• artifcatId: x //artifactId 会有些变化，这里先用 x 代替，下面会修改。
• version: 1.0.0

也就是'com.as-gradle.demo:x:1.0.0'

读者要进行练习的时候，最好改一下你的 groupId，否则可能会发布失败

下面使用到的示例工程已经放在了 github 上。

为了后面使用方便，首先在工程的项目 gradle.properties 中定义一些属性，这些属性，主要是用生成 POM 文件，将会在通篇文章中用到：

# 包信息
PROJ_GROUP=com.as-gradle.demo
PROJ_VERSION=1.0.0

发布包到本地仓库

• 创建一个 module：localrepo
• 将本地某个路径设置为仓库根目录：

/Users/your-user-name/Documents/Android/repo/

这里使用了一个叫做 your-user-name 的用户下的某个目录，请读者自行替换成自己的登录用户名。

• 为了优雅，在 localrepo 这个 module 的 gradle.properties 定义属性：

PROJ_NAME=localrepo
PROJ_ARTIFACTID=localrepo
PROJ_POM_NAME=Local Repository

• 在 module 中应用和配置 maven plugin：

apply plugin: 'maven'

• 在控制台运行：

$ ./gradlew -p localrepo clean build uploadArchives --info

• 一切顺利的话，你的第一个本地包已经发布到设定的目录的本地仓库了：

|   ├── com
│   ├── as-gradle
│   │   └── demo
│   │       └── localrepo
│   │           ├── 1.0.0
│   │           │   ├── localrepo-1.0.0.aar
│   │           │   ├── localrepo-1.0.0.aar.md5
│   │           │   ├── localrepo-1.0.0.aar.sha1
│   │           │   ├── localrepo-1.0.0.pom
│   │           │   ├── localrepo-1.0.0.pom.md5
│   │           │   └── localrepo-1.0.0.pom.sha1
│   │           ├── maven-metadata.xml
│   │           ├── maven-metadata.xml.md5
│   │           └── maven-metadata.xml.sha1

使用本地包（两个疑问向读者请教）

要使用这个包，首先在项目的 build.gradle 中添加这个本地仓库：

allprojects {
repositories {
    jcenter()

在某个 module（如 demo 项目中的 app） 的 build.gradle 中添加依赖：

compile 'com.as-gradle.demo:localrepo:1.0.0@aar'

这里有两个奇怪的地方，笔者也没有深入研究，初步猜测是 Android Studio 的 Bug，知道答案的读者请到我博客文章下留言赐教：

• 依赖末尾一般都需要加一个@aar，在某些版本的 Android Studio，又不需要，这是为什么？
• 另外，如果本地包本身使用了了远程的依赖，也需要在使用本地包的时候，一并加上，否则会报缺少包，这又是为什么？

想要让更多的人使用到你的劳动成果，你就需要把 Maven 包放在一个别人有权访问的远程仓库上，而不是本机，接下来要介绍发布 Maven 到 jcenter 仓库和 mavenCentral 仓库。因为前者的使用简单，本着『先易后难，快速出成效』的原则，我先介绍 jcenter 的上传。

发布包到 Bintray jcenter 远程仓库

简介

jcenter 是由 bintray 提供的 maven 中央库托管服务，bintray 又是 jfrog 公司的一款产品。jfrog 是一个商业公司，通过提供高级服务盈利，又为普通开发者提供了足够用的免费基础功能（截止至2016-01-24），笔者较为推崇这种开发者服务的商业模式。

引用一张图来表述 bintray 的工作方式

图片来源，http://inthecheesefactory.com/

使用 jcenter 需要在 bintray 上注册账号，在本地进行加密签名配置，下面开始介绍。

1. 注册账号

• 登陆 jcenter首页
• sigin -> signup，填写表单，注意 username 这一栏是后面的 bintray 私有库的后缀，要慎重选择。

2. 创建 GPG 签名

前方高能预警：比较繁琐，切勿半途放弃

前面介绍过，可以把 bintray 的包同步到 mavenCentral，而后者需要对包文件进行签名，签名和验证过程需要用到一个叫做GPG的工具产生的公钥和私钥。这里有适合多个平台的 GPG 程序，下面只介绍 OSX 平台。

这种工具大概的意义是产生公钥和私钥，把公钥发送到公开的服务器，私钥用来产生包文件签名。包的使用者在拿到包文件之后，通过公钥来验证文件的有效性，运行具体原理参考这里。

• 下载gpgtool，安装
• 检测安装成功，在命令行运行
  

  $ gpg --version
  gpg (GnuPG/MacGPG2) 2.0.28
  libgcrypt 1.6.3

  有类似的输出，就是正常安装了
• 产生证书，运行命令，按照提示输入
  

  $ gpg --gen-key

• 检查结果
  

  $ gpg --list-keys

  找到刚才创建证书的时候，输入的相关信息那三行，例如：
  

  pub   2048R/2E686B39 2015-06-02
  uid       [ultimate] Your Name <your-email@your-mailbox.com>
  sub   2048R/your-sub-key-id 2015-06-02

• 上传公钥到服务器，找到你的 pub 的那一行，2048R/后的那一串八位字符串，如上面的：2E686B39，就是公钥 ID
  

  $ gpg --keyserver hkp://pool.sks-keyservers.net --send-keys your-public-key-id

• 输出公钥和私钥成文件
  

  $ gpg -a --export your-email@your-mailbox.com > public_key_sender.asc
  $ gpg -a --export-secret-key your-email@your-mailbox.com > private_key_sender.asc

• 配置本地 gradle 运行环境的属性，位于~/.gradle/gradle.properties，添加内容：
  

  signing.keyId=your-public-key-id
  signing.password=your-gpg-password
  signing.secretKeyRingFile=/Users/your-user-name/.gnupg/secring.gpg

• bintray 本身可以通过在profile->GPG Sining中配置 public key 和 private key 来自动对上传的文件进行签名，在下图中，对应填入public_key_sender.asc与private_key_sender.asc的内容即可。
  

  

• 设置 bintray maven 包自动签名
  

  选取 maven 仓库首页，进入 edit：

  

  最下面有两个选项：

  GPG sign uploaded files using Bintray's public/private key pair.
  GPG Sign uploaded files automatically

  因为咱们是希望使用自己的 key，所以勾选第二个。

3. 创建 bintray 项目

首页-> maven -> add new package，填入对应的信息，其中 name 是在下面 bintray gradle 插件上传的时候，使用的项目名称，例如：bintryaar，这是要上传一个 Android Library，上传纯 Java 包的方式有点点不一样，下面有介绍。

4. 配置插件

bintray 官方在 github 上托管了bintray-examples，方便用户使用 gradle 上传包。因为这里要上传的是 aar 格式的包，所以，具体是参考gradle-aar-example例子，然而例子有一些地方没有更新，请注意下面的描述。

• 在 项目 中创建 local.properties 来配置 bintray 登陆信息以及 gpg 证书密码

  其中 your-bintray-user 就是 bintray 右上角显示的用户名称，your-bintray-apikey 在 profile->API Key 可以找到，your-gpg-password 则是创建 gpg 证书的时候的密码

  bintray.user=your-bintray-user
  bintray.apikey=your-bintray-apikey
  bintray.gpg.password=your-gpg-password

• 在项目的 build.gradle 配置 buildscript 的 classpath
  

  buildscript {
  repositories {
      jcenter()
  }
  dependencies {
      classpath 'com.android.tools.build:gradle:1.3.0'
      //下面两个包是用于上传的插件
      classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.0'
      classpath 'com.github.dcendents:android-maven-gradle-plugin:1.3'//注意此处
  }
  }

• 在 module 的 gradle.properties 文件中定义属性
  

  PROJ_NAME=bintrayaar
  PROJ_ARTIFACTID=bintrayaar
  PROJ_POM_NAME=Bintray Aar Repository

• 在 module 的 build.gradle 中使用插件
  

  apply plugin: 'com.github.dcendents.android-maven'
  apply plugin: 'com.jfrog.bintray'

• 为了build.gradle 文件干净，笔者创建了一个名为 bintray.gradle 的文件配置插件信息，请参考这个文件。
  关键点：
  

  artifacts {
  archives javadocJar
  archives sourcesJar
  }

  是为了同时生成 javadoc.jar 和 sources.jar 文件

• build，上传

  $ ./gradlew -p bintrayrepo/ clean build bintrayUpload --info

  如果一切顺利，你会在控制台看到多个文件上传成功的标输出

• 踩坑实录

  • HTTP/1.1 401 Unauthorized

    apikey 或者 user 填写错误

  • HTTP/1.1 409 Conflict

    包的该版本已经存在，需要在 bintray 管理界面上删除该版本后才可以再次上传

  • 想让 sources.jar 或者 javadoc.jar 为空
    

    task sourcesJar(type: Jar) {
        classifier = 'sources'
        from sourceSets.main.java.srcDirs
        exclude '**'
    }

5. 上传 Jar 包

• 在上传 jar 的时候，使用的插件有些区别

  apply plugin: 'maven-publish'
  apply plugin: 'com.jfrog.bintray'

• 在生成符合规定的 pom 文件的时候，要调用 groovy 的API，具体请参考这个文件

6. 通过私有仓库的方式引用

至此，刚才上传的两个库，已经可以通过如下方式引用了

allprojects {
    repositories {
            maven {
                url 'https://dl.bintray.com/freefaces/maven'//这个地址在包的页面的右方
            }
    }
}

compile 'com.as-gradle.demo:bintrayaar:1.0.0'
compile 'com.as-gradle.demo:bintrayjar:1.0.0'

但是你也发现了，包的用户需要添加一个额外的 maven 仓库。作为一个以用户价值为先的库的开发者，那当然不希望用户麻烦的。那就需要把这个私有的库，推送到 jcenter 上去。

7. 推送到 jcenter

在 bintray 的 maven 库的界面，有add to jcenter

点击之后，会进入一个消息页面，写或者不写都可以。提交，等待回复即可。

记住,包必须满足如下条件：

• 包含 sources.jar 和 javadoc.jar 文件
• 必须是 maven 包

bintray 的消息系统有些 bug，假设你的包提交申请被驳回，你修改之后再提交申请，可能没有人回复你。请 不要傻等 。直接找页面右侧的 Feedback，这个他们是很快有人回答的。

成功了之后，会出现如下的标记：

你可以在 jcenter服务器上看到你的包了

8. 推送到 mavenCentral

在包管理页面，可以找到推送到 mavenCentral 功能，

一个包要从 bintray 推送到 jcenter，有几个前提：

• 已经推送到了 jcenter [已完成]
• 每个文件都有对应的签名[已完成]
• 有 sonatye 账户[未完成]
• maven 仓库经过审核[未完成]

点击 Sync 之后，一段时间之后，右边的 Sync Status 会反馈出结果。

当然了，现在咱还干不了这个，因为还有两个条件没准备好。那咱们就进入 mavenCentral 的条件准备。

发布包到 Sonatype MavenCentral 远程仓库

1. 注册 sonatye 账户

进入sonatype issue页面，注册账号。

2. 创建 issue

登陆之后，顶部有按钮，Created，下面是关键的条目

• Project:Community Support - Open Source Project Repository Hosting (OSSRH)
• Issue Type: New Project
• Group Id：就是你的包的 groupId

其他的都认真填写。确认之后，大概两个工作日， Issue 会变成 resolved 状态，就可以发布你的包了。有了这两部，其实就可以从 bintray 上直接反向推到 mavenCentral ，而不需要走下面的步骤了，但是我还是简略介绍一下下面的步骤。如果很感兴趣详情，可以参考trinea的介绍。

3. 上传包

也有方便的 gradle 插件帮助我们进行传送，可以参考chrisbanes/gradle-mvn-push项目。配置好插件，上传。

4. 发布包

登陆oss sonatype，登陆，选择左边栏里的Staging Repositories, 然后点Close 按钮，sonatype 会做响应的 validation，通过的话，就可以点 Release 发布啦，如果不通过，就检查问题，先 Drop，并重新做 Staging 发布。

5. 检查包

在https://oss.sonatype.org/content/repositories/releases可以看到你发布的包。

6. 为何如此简略

因为这个过程真的很繁琐，ui 也不友好，在体验了 bintray 的便捷和友好，并发现 bintray 可以反向推送到 mavenCentral 之后，我就再也不想使用 sonatype 了。无奈，贪嗔痴是人类天性。

搭建私服

由于“你懂得”的原因，在国内访问 jcenter，总是偶尔不稳定，经常会出现诸如peer not found这种错误。为了保证用户的稳定使用库，那就要考虑搭建放在自己服务器上的私有仓库。

Sonatype 和 bintray 都提供了可供自己部署的 maven 库管理软件。Sonatype 提供了免费的sonatype/nexus，bintray 提供了免费的artifactory-oss。

为了部署简便，笔者使用了docker进行这两个私服搭建。对于 docker 是什么，怎么用，并不是系列文章的重点。有兴趣可以自行学习。入门文档在此。

搭建私有 Sonatype 仓库

• 下载安装 docker 镜像
  

  $ docker pull sonatype/nexus

• 运行镜像

  $ docker run -d -p 8081:8081 --name nexus sonatype/nexus:oss

• 访问服务器

  因为的 docker-machine ip 是：192.168.99.100，于是可以通过在浏览器访问http://192.168.99.100:8081/这个 URL 来访问 sonatype 私服。

  你会发现这个界面跟你在https://oss.sonatype.org/看到的几乎一样。

  默认账户密码是：

  admin
  admin123

• 设置仓库

  点击左侧 repository，会出现 repository 的列表，把其中的Releases的Configutation->Access Setting-> Deploy Polocy设置成Allow Redeploy使得可以重复发布包。

• 配置和使用插件

  我还是使用了chrisbanes/gradle-mvn-push插件，稍微改动了一下字段的值，主要改动是环境配置，如账号密码，repository URL 等，具体请参考这里mvn-push。

• 关键设置

  要在gradle.properties中设置：

  PROJ_NAME=sonatyaar
  PROJ_ARTIFACTID=sonatyaar
  PROJ_POM_NAME=Sonatye Aar Repository
  POM_PACKAGING=aar
  RELEASE_REPOSITORY_URL=http://192.168.99.100:8081/content/repositories/releases
  SNAPSHOT_REPOSITORY_URL=http://192.168.99.100:8081/content/repositories/snapshots

• 查看
  

  上传成功之后，就可以在浏览器的http://192.168.99.100:8081/content/repositories/releases看到这个包。并可引用了。

• 错误
  

  上传的时候，返回400，可能是Configutation->Access Setting-> Deploy Polocy没设置好；返回401，可能是账号密码错误。

搭建私有 Artifactory 仓库

bintray 其实提供了多个私有部署仓库的版本，分别是：

Artifactory OSS
Artifactory Pro
Artifactory Pro Registry

按名字来看，后两者可能是收费的，这里就只介绍Artifactory OSS，依然是使用 docker 进行部署运行。更详细的使用手册，参考Running with Docker。

• 下载镜像（截止至2016-01-27，最新版本是4.4.1）
  

  $ docker pull jfrog-docker-reg2.bintray.io/jfrog/artifactory-oss:4.4.1

• 运行镜像
  

  $ docker run -d -p 8080:8081 jfrog-docker-reg2.bintray.io/jfrog/artifactory-oss:4.4.1

• 在浏览器中访问http://192.168.99.100:8080/，默认账号密码是：
  

  admin
  password

笔者写到这，发现这个篇幅已经太长了。现在的读者，其实也没有太多耐心看长篇大论，所以考虑将更详细的私服的部署，放在一篇独立的博客中讲解。

kevinho/gradle-maven-complete

为了方便读者使用 gradle 将 aar、jar包推送到 jcenter 和 mavenCentral，笔者决定将本文所使用的 sample 项目，分离出一个独立的 github 项目：kevinho/gradle-maven-complete，里面包含如下范例：

• localrepo：本地仓库推送
• bintrayaar：bintray 的 aar 包推送
• bintrayjar：bintray 的 jar 包推送
• sonatypearr：mavenCentral 的 aar 包推送

基本上覆盖到了主流的场景了，希望我这个小轮子，也能帮助大家，喜欢记得 star 哦！

总结

这一篇，笔者结合实例讲解了 maven 仓库相关的知识，以及将 maven 包通过 gradle 插件上传本地仓库、bintray jcenter、sonatype mavenCentral，还简要介绍了 sonatype 和 artifactory 私服的 docker 搭建。或许你已经蠢蠢欲动了，那就赶紧打开你的电脑，把你的轮子，用 maven 武装起来吧！下一篇会介绍 gradle 插件的编写以及发布使用，敬请期待！