Help us learn about your current experience with the documentation. Take the survey.

Maven 虚拟注册表

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed
Status: Beta

此功能的可用性由特性开关控制。更多信息请查阅历史记录。此功能处于 Beta 阶段。使用前请仔细阅读文档。

Maven 虚拟注册表通过单一、知名的 URL，在 GitLab 中管理和分发来自多个外部注册表的软件包。

使用 Maven 虚拟注册表可以：

创建虚拟注册表
将虚拟注册表连接到公共和私有上游注册表
配置 Maven 客户端从配置的上游拉取软件包
管理可用上游的缓存条目

这种方式能随时间提升软件包性能，并简化 Maven 软件包管理。

前置条件

使用 Maven 虚拟注册表前：

阅读使用虚拟注册表的前置条件

使用 Maven 虚拟注册表时，请注意以下限制：

每个顶级组最多可创建 20 个 Maven 虚拟注册表
单个 Maven 虚拟注册表最多只能设置 20 个上游
出于技术原因，proxy_download 设置强制启用，无论对象存储配置中如何设置
暂不支持 Geo 功能。可关注其开发进展于 issue 473033

管理虚拟注册表

通过 Maven 虚拟注册表 API 管理虚拟注册表。

无法在 UI 中配置虚拟注册表，但 epic 15090 提出了实现虚拟注册表 UI 的方案。

向虚拟注册表 API 认证

虚拟注册表 API 使用 REST API 认证方式。必须通过 API 认证才能管理虚拟注册表对象。

能使用虚拟注册表的用户可执行读取操作。

创建新注册表或添加上游等写入操作，仅限虚拟注册表所属顶级组的直接维护者执行。

创建和管理虚拟注册表

创建 Maven 虚拟注册表，请使用以下命令：

curl --fail-with-body \
     --request POST \
     --header "<header>" \
     --data '{"name": "<registry_name>"}' \
     --url "https://gitlab.example.com/api/v4/groups/<group_id>/-/virtual_registries/packages/maven/registries"

<header>: 认证头
<group_id>: 顶级组 ID
<registry_name>: 注册表名称

关于 Maven 虚拟注册表的其他端点及示例，请查阅 API 文档

管理上游注册表

前置条件：

必须拥有有效的 Maven 虚拟注册表 ID

当为现有虚拟注册表创建上游注册表时，该上游会被添加到可用上游列表的末尾。

为现有虚拟注册表创建上游，请使用以下命令：

curl --fail-with-body \
     --request POST \
     --header "<header>" \
     --data '{ "name": "<upstream_name>", "url": "<upstream_url>", "username": "<upstream_username>", "password": "<upstream_password>", "cache_validity_hours": <upstream_cache_validity_hours> }' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/<registry_id>/upstreams"

<header>: 认证头
<registry_id>: Maven 虚拟注册表 ID
<upstream_name>: 上游注册表名称
<upstream_url>: Maven 上游 URL
<upstream_username>: 可选。用于 Maven 上游的用户名。若设置 <upstream_password> 则为必填项
<upstream_password>: 可选。用于 Maven 上游的密码。若设置 <upstream_username> 则为必填项
<upstream_cache_validity_hours>: 可选。缓存有效期（小时）。默认值为 24。设置为 0 可禁用缓存条目检查
- 若 <upstream_url> 设置为 Maven 中央仓库：
  - 必须使用以下 URL：https://repo1.maven.org/maven2
  - 默认有效期设为 0。Maven 中央仓库的所有文件均为不可变

若未设置 <upstream_username> 和 <upstream_password>，则使用公共（匿名）请求访问上游

关于其他端点及示例（如更新上游注册表在列表中的位置），请查阅 API 文档

管理缓存条目

必要时可检查或删除缓存条目。

当虚拟注册表再次请求被删除缓存条目引用的文件时，将重新遍历上游列表以找到可满足请求的上游。

关于管理缓存条目的更多信息，请查阅 API 文档

使用虚拟注册表

创建虚拟注册表后，必须配置 Maven 客户端通过虚拟注册表拉取依赖。

Maven 客户端认证

虚拟注册表端点可使用以下任一令牌：

个人访问令牌
虚拟注册表所属顶级组的组部署令牌
虚拟注册表所属顶级组的组访问令牌
CI 作业令牌

令牌需要以下任一作用域：

api
read_virtual_registry

访问令牌和 CI 作业令牌会解析为用户。解析后的用户必须满足以下任一条件：

是顶级组的直接成员，最低权限级别为 guest
是 GitLab 实例管理员
是顶级组包含的项目的直接成员

配置 Maven 客户端

Maven 虚拟注册表支持以下 Maven 客户端：

必须在 Maven 客户端配置中声明虚拟注册表。

所有客户端必须进行认证。客户端认证可使用自定义 HTTP 头或 Basic Auth。建议为每个客户端使用以下配置之一。

令牌类型	名称必须为	令牌
个人访问令牌	`Private-Token`	直接粘贴令牌，或定义环境变量存储令牌
组部署令牌	`Deploy-Token`	直接粘贴令牌，或定义环境变量存储令牌
组访问令牌	`Private-Token`	直接粘贴令牌，或定义环境变量存储令牌
CI 作业令牌	`Job-Token`	`${CI_JOB_TOKEN}`

在 settings.xml 文件中添加以下配置：

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>REPLACE_WITH_NAME</name>
            <value>REPLACE_WITH_TOKEN</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

可通过两种方式在 mvn 应用中配置虚拟注册表：

作为默认注册表（Maven 中央仓库）的附加注册表。此配置下，可从任一声明注册表拉取同时存在于虚拟注册表和默认注册表的项目依赖
作为默认注册表（Maven 中央仓库）的替代。此配置下，依赖通过虚拟注册表拉取。建议将 Maven 中央仓库配置为虚拟注册表的最后一个上游，以避免缺少必需的公共依赖

将 Maven 虚拟注册表配置为附加注册表，在 pom.xml 文件中添加 repository 元素：

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id></url>
  </repository>
</repositories>

<id>: 与 settings.xml 中 <server> 使用的 ID 相同
<registry_id>: Maven 虚拟注册表 ID

将 Maven 虚拟注册表配置为默认注册表的替代，在 settings.xml 中添加 mirrors 元素：

<settings>
  <servers>
    ...
  </servers>
  <mirrors>
    <mirror>
      <id>central-proxy</id>
      <name>GitLab 中央仓库代理</name>
      <url>https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id></url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

<registry_id>: Maven 虚拟注册表 ID

令牌类型	名称必须为	令牌
个人访问令牌	`Private-Token`	直接粘贴令牌，或定义环境变量存储令牌
组部署令牌	`Deploy-Token`	直接粘贴令牌，或定义环境变量存储令牌
组访问令牌	`Private-Token`	直接粘贴令牌，或定义环境变量存储令牌
CI 作业令牌	`Job-Token`	`${CI_JOB_TOKEN}`

在您的 GRADLE_USER_HOME 目录中，创建包含以下内容的 gradle.properties 文件：

gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

在您的 build.gradle 中添加 repositories 配置：

Groovy DSL：

repositories {
    maven {
        url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id>"
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'REPLACE_WITH_NAME'
            value = gitLabPrivateToken
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

Kotlin DSL：

repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id>")
        name = "GitLab"
        credentials(HttpHeaderCredentials::class) {
            name = "REPLACE_WITH_NAME"
            value = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("header", HttpHeaderAuthentication::class)
        }
    }
}

<registry_id>: Maven 虚拟注册表 ID

令牌类型	用户名必须为	令牌
个人访问令牌	用户名	直接粘贴令牌，或定义环境变量存储令牌
组部署令牌	部署令牌用户名	直接粘贴令牌，或定义环境变量存储令牌
组访问令牌	与访问令牌关联的用户名	直接粘贴令牌，或定义环境变量存储令牌
CI 作业令牌	`gitlab-ci-token`	`sys.env.get("CI_JOB_TOKEN").get`

SBT 认证基于 basic HTTP Authentication。必须提供用户名和密码。

在您的 build.sbt 中添加以下行：

resolvers += ("gitlab" at "<endpoint_url>")

credentials += Credentials("GitLab Virtual Registry", "<host>", "<username>", "<token>")

<endpoint_url>: Maven 虚拟注册表 URL 例如：https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id>，其中 <registry_id> 是 Maven 虚拟注册表 ID
<host>: <endpoint_url> 中不含协议方案或端口号的主机名。例如：gitlab.example.com
<username>: 用户名
<token>: 配置的令牌

确保 Credentials 的第一个参数是 "GitLab Virtual Registry"。此领域名称必须与 Maven 虚拟注册表发送的 Basic Auth realm 完全匹配。