Quarkus Extension Registry

Quarkus 开发工具（例如 Quarkus CLI 插件、Maven 插件和 Gradle 插件）或 code.quarkus.io 可以用于列出和搜索 Quarkus 生态系统中与某个条件匹配的扩展。这包括 Quarkus platform 扩展和其他各种由社区提供的扩展，其中许多托管在 Quarkiverse Hub 上。

The Quarkus dev tools, such as the Quarkus CLI, the Maven and the Gradle plugins, or code.quarkus.io can be used to list and search the Quarkus ecosystem for extensions that match a certain criteria. That includes the Quarkus platform extensions and various other extensions contributed by the community, many of which are hosted on the Quarkiverse Hub.

关于所有可用的 Quarkus 扩展的信息由 Quarkus extension registries 提供给开发工具。

The information about all the available Quarkus extensions is provided to the dev tools by Quarkus extension registries.

Quarkus 扩展注册表是一个提供关于以下信息的数据库：

A Quarkus extension registry is a database providing information about:

available Quarkus platforms, indicating which of those are currently recommended for new projects and/or as updates;
available non-platform extensions, indicating which Quarkus versions they are compatible with.

registry.quarkus.io

托管在 registry.quarkus.io 上的注册表是默认的 Quarkus 社区扩展注册表。它会在每次发布 Quarkus community platform 时更新，并且包括托管在 Quarkiverse Hub 上的扩展。

The registry hosted at registry.quarkus.io is the default Quarkus community extension registry. It is updated on every release of the Quarkus community platform and includes extensions hosted on the Quarkiverse Hub.

Maven repository

托管在 registry.quarkus.io 上的注册表是一个 Maven snapshot 存储库，它为开发工具提供平台和扩展目录，作为 Maven JSON 构件。下载扩展目录后，它们将被缓存在用户的本地 Maven 存储库中，并且即使网络互联网（或注册表本身）不可用，它们仍可供开发工具使用。

The registry hosted at registry.quarkus.io is a Maven snapshot repository that provides platform and extension catalogs to the dev tools as Maven JSON artifacts. Once downloaded the extension catalogs will be cached in the user’s local Maven repository and will be available to the dev tools even if the Internet network (or the registry itself) isn’t available.

本地缓存的扩展目录构件会定期检查更新，并且如果在注册表中提供了这些目录的较新版本，则会更新它们。检查更新的默认时间间隔为 daily，这与 SNAPSHOT 构件的默认 Maven 存储库 updatePolicy 相匹配。

The extension catalog artifacts cached locally will be regularly checked for updates and updated if newer versions of those catalogs are available in the registry. The default interval to check for updates is daily, which matches the default Maven repository updatePolicy for SNAPSHOT artifacts.

Maven repository configuration

下面的存储库配置仅出于说明目的而显示，且必须 NOT 添加到用户 settings.xml 或应用程序的 pom.xml 中。Quarkus 开发工具预先配置了这个存储库。

The repository configuration below is shown only for illustrative purposes and does NOT have to be added to the user settings.xml or the application’s pom.xml. The Quarkus dev tools come with this repository pre-configured.

registry.quarkus.io 的完整 Maven repository configuration 为：

The complete Maven repository configuration of registry.quarkus.io is

<repository>
  <id>registry.quarkus.io</id>
  <name>Quarkus community extension registry</name>
  <url>https://registry.quarkus.io/maven</url>
  <snapshots>
    <enabled>true</enabled>
    <updatePolicy>daily</updatePolicy>
    <checksumPolicy>warn</checksumPolicy>
  </snapshots>
</repository>

初始化 Quarkus 开发工具后，此存储库配置会自动添加到用于从 registry.quarkus.io 解析平台和扩展目录的 Maven 解析器中。

When the Quarkus dev tools are initialized, this repository configuration is automatically added to the Maven resolver which will be used to resolve the platform and extension catalogs from registry.quarkus.io.

Maven repository mirrors and proxies

初始化 Quarkus 开发工具 Maven 解析器后，会在用户 settings.xml 中找到的相关 Maven 镜像和代理会自动应用至 registry.quarkus.io Maven 存储库配置，就像 registry.quarkus.io Maven 存储库在用户 settings.xml 中进行配置那样。

When the Quarkus dev tools Maven resolver is initialized, the relevant Maven mirrors and proxies found in the user settings.xml are automatically applied to the registry.quarkus.io.maven.repo Maven repository configuration, as if the registry.quarkus.io.maven.repo Maven repository was configured in the user settings.xml.

这意味着，例如，如果将匹配的 Maven 存储库镜像应用至 registry.quarkus.io Maven 存储库，则必须将 registry.quarkus.io Maven 存储库添加到相应的 Maven 服务器实例（例如 Nexus）中的镜像存储库组。

That means, if, for example, a matching Maven repository mirror was applied to the registry.quarkus.io.maven.repo Maven repository, the registry.quarkus.io.maven.repo Maven repository would have to be added to the mirror repository group in the corresponding Maven server instance (e.g. Nexus).

Overriding the default registry Maven repository configuration

实际上，可以通过简单添加所需的 <repository> 配置（其 <id> 值为 registry.quarkus.io）来在用户 settings.xml 中覆盖默认注册表 Maven 存储库配置。如果在用户 settings.xml 中找到了此类存储库配置，则开发工具将使用它来代替上面所示的默认 registry.quarkus.io Maven 存储库配置。

The default registry Maven repository configuration can actually be overridden in the user settings.xml by simply adding the desired <repository> configuration with the registry.quarkus.io as its <id> value. If such a repository configuration is found in the user settings.xml, the dev tools will use it in place of the default registry.quarkus.io.maven.repo Maven repository configuration shown above.

Quarkus Extension Registry Client Configuration

通常情况下，Quarkus 社区的用户在其环境中不需要任何与注册表相关的配置。默认情况下，由 registry.quarkus.io 托管的注册表已在所有 Quarkus 开发工具中启用。但是，在某些情况下，自定义注册表客户端配置可能会有所帮助。例如，更改本地注册表缓存更新策略或配置其他（非默认）Quarkus 扩展注册表。

Typically, Quarkus community users will not need to have any registry-related configuration in their environment. The registry hosted at registry.quarkus.io is enabled in all the Quarkus dev tools by default. However, there could be a few situations where a custom registry client configuration could help. For example, to change the local registry cache update policy or to configure additional (non-default) Quarkus extension registries.

Registry client configuration location

启动 Quarkus 开发工具时，将按照以下步骤搜索注册表客户端配置文件：

When the Quarkus dev tools are launched, a search for the registry client configuration file is performed following these steps:

quarkus.tools.config system property is checked, if it exists, its value will be used as a path to the registry client configuration file;
the current directory is checked to contain the .quarkus/config.yaml file, if the file exists, it will be used to configure the registry client;
the user home directory is checked to contain the ~/.quarkus/config.yaml file, if the file exists, it will be used to configure the registry client;
if none of the above steps located a configuration file, the default registry.quarkus.io.maven.repo configuration will be used.

Configuring multiple registries

registry.quarkus.io 是默认的 Quarkus 社区扩展注册表，但并不意味着它总是唯一注册表。其他组织可能发现创建自己的 Quarkus 扩展注册表以提供自己的 Quarkus platforms 和/或单独（非平台）Quarkus 扩展很有用。希望在其环境中启用自定义 Quarkus 扩展注册表的用户需要将其添加到注册表客户端配置文件。

The registry.quarkus.io is the default Quarkus community extension registry, but it is not meant to be always the only registry. Other organizations may find it useful to create their own Quarkus extension registries to provide their own Quarkus platforms and/or individual (non-platform) Quarkus extensions. Users wishing to enable custom Quarkus extension registries in their environment would need to add them to the registry client configuration file.

注册表客户端配置文件是一个简单的 YAML 文件，其中包含注册表列表，例如：

The registry client configuration file is a simple YAML file which contains a list of registries, for example:

registries:
- registry.acme.org
- registry.quarkus.io

上面的配置启用两个注册表： registry.acme.org 和 registry.quarkus.io 。注册表的顺序实际上很重要。当 Quarkus 开发工具应用户的请求寻找扩展时，将按照配置的顺序搜索注册表，即从列表的顶部到底部。首先找到的扩展和平台将显示为用户首选的扩展和平台。

The configuration above enables two registries: registry.acme.org and registry.quarkus.io. The order of the registries is actually significant. When the Quarkus dev tools are looking for extensions on user’s request, the registries will be searched in the order they are configured, i.e. from the top to the bottom of the list. Extensions and platforms found first will appear as the preferred ones to the user.

registry.quarkus.io 是默认注册表，通常无需显式配置，但是，如果用户提供自定义注册表列表并且其中没有 registry.quarkus.io ，则将启用 registry.quarkus.io 。

registry.quarkus.io is the default registry which normally does not have to be configured explicitly, however if a user provides a custom registry list and registry.quarkus.io is not in it, registry.quarkus.io will not be enabled.

例如，这里有一个将默认 registry.quarkus.io 注册表替换为自定义注册表的注册表客户端配置：

For example, here is a registry client configuration that replaces the default registry.quarkus.io registry with a custom one:

registries:
- registry.acme.org

Adjusting the registry cache update policy

通常，Quarkus 扩展注册表将实现为 Maven 快照存储库。从注册表解析出的平台和扩展目录将缓存到用户的本地 Maven 存储库。平台和扩展目录实际上是 SNAPSHOT 构件，注册表客户端会定期检查它们是否有更新。检查更新的默认注册表间隔与 Maven 的 snapshot repositories 的默认值 updatePolicy 匹配，即 daily 。可以在注册表配置中覆盖此默认值，例如：

Usually, a Quarkus extension registry will be implemented as a Maven snapshot repository. The platform and extension catalogs resolved from the registry as Maven artifacts will be cached in the user’s local Maven repository. The platform and extension catalogs are actually SNAPSHOT artifacts that are periodically checked for updates by the registry client. The default registry interval to check for updates matches the default value of the Maven’s updatePolicy for snapshot repositories and is daily. This default can be overridden in the registry configuration, for example:

registries:
- registry.acme.org:
    update-policy: "always"
- registry.quarkus.io

在上面的示例中，将在每个目录请求中检查 registry.acme.org 注册表的目录更新，而将每天检查一次 registry.quarkus.io 注册表的目录更新（在当天的第一个目录请求中）。

In the example above, the registry.acme.org registry will be checked for catalog updates on every catalog request, while the registry.quarkus.io registry will be checked for catalog updates once a day (on the first catalog request of the day).

下面是注册表的 update-policy 值的所有选择列表：

Here is a complete list of choices for a registry’s update-policy value:

always - check for the updates on every catalog request;
daily (default) - check for the catalog updates once a day on the first catalog request;
interval:X (where X is an integer in minutes) - custom interval in minutes;
never - resolve the catalogs once and never check for updates.

Disabling a registry in the configuration

配置文件中列出的所有注册表默认情况下均已启用。但是，可以通过向其配置中添加 enabled: false 来禁用注册表。例如：

All the registries listed in the configuration file are enabled by default. A registry can be disabled though by adding enabled: false to its configuration. For example:

registries:
- registry.acme.org
- registry.quarkus.io:
    enabled: false

在上面的配置中，仅启用了 registry.acme.org。上面的配置等同于：

In the configuration above, only the registry.acme.org is enabled. The configuration above is equivalent to:

registries:
- registry.acme.org

Enabling the debug mode

默认情况下，注册表客户端不会记录太多信息。但是，它确实会从 Maven 存储库后台解析各种工件。如果你想在日志中查看工件传输和其他调试相关消息，可以在配置中启用调试模式。例如：

The registry client is not logging much information by default. However, it does resolve various artifacts from Maven repositories behind the scenes. If you would like to see artifact transfer and other debugging related messages in the logs, you can enable the debug mode in the configuration. For example:

debug: true
registries:
- registry.acme.org
- registry.quarkus.io

Overriding a registry URL

可能会发生注册表 URL 更改的情况，但 ID 必须相同（因为查询了 Maven 坐标）。要覆盖注册表 URL，请添加以下内容：

There may be situations where the URL of the registry changes, however the ID needs to be the same (because the Maven coordinates are queried). To override the registry URL, add the following:

registries:
- registry.acme.org
- registry.quarkus.io:
    maven:
      repository:
        url: https://internal.registry.acme.org/maven

[id="how-to-register-as-nexus-repository"] How to register as a Nexus Repository proxy

你可以将 Quarkus 扩展注册表注册为 Nexus 存储库代理。你需要成为管理员才能执行这些操作。

You can register a Quarkus extension registry as a Nexus repository proxy.You need to be an administrator to perform these operations.

[id="how-to-register-as-nexus-2-repository"] Nexus 2.x

需要设置一些选项：

Some options need to be set:

Set the Repository Policy to Snapshot;
Disable Download Remote Indexes;
Disable Allow File Browsing;
Disable Include in Search.

以下是如何设置的示例：

Here is an example on how it should look like:

Nexus Repository Manager: Add Proxy Repository

Nexus Repository Proxy

[id="how-to-register-as-nexus-3-repository"] Nexus 3.x

Create a maven2(proxy) repository
Set the Version Policy to Snapshot
Set the Remote Storage URL to https://registry.quarkus.io/maven

Nexus Repository Proxy