动态代理 Maven 存储库

在线编辑

动态 Instana 代理需要访问 Maven 存储库，以便下载功能、传感器和更新。

默认情况下，动态代理配置为使用以下存储库：

  • 仓库名称： shared
  • URL: https://artifact-public.instana.io/artifactory/shared
  • 认证：
    • 用户名： _
    • 密码： 您的 Instana 下载密钥

在无法访问软件 shared 仓库的环境（例如物理隔离环境）中使用动态代理，需要进行自定义代理配置，并确保 Maven 软件仓库的镜像站点可访问。 此要求仅适用于动态代理，因为静态代理无需访问 Maven 存储库。 有关代理更新的更多信息，请参阅 《动态主机代理的更新》。

注意： 在2026年5月之前，动态代理配置了两个 Maven 存储库： shared 和 features。 该 features 仓库已不再需要，因为所有必要的构建产物现已在该 shared 仓库中提供。 不过，为了与早期版本保持兼容，该 features 存储库的配置机制仍然得到支持。 如需了解更多信息，请参阅旧版 Maven 存储库配置。

创建一个 Maven 仓库镜像

在线编辑

您可以使用任何与 Maven 2 Wagon 兼容的仓库，来创建 Instana Maven 仓库的镜像。

以下各节介绍了针对仓库管理器的仓库镜像配置：Sonatype Nexus（推荐）和 JFrog Artifactory。

仓库镜像必须能够通过网络访问 Instana Maven 上的仓库。

Sonatype Nexus

首先，请按照 Nexus 文档中的说明准备一个自托管的 Nexus 实例。

接下来，在 Nexus 中创建一个新仓库 ，配置如下：

  • 食谱：maven2 （代理链接）
  • 姓名： instana-shared
  • 版本策略： 混合
  • 排版政策： 宽松
  • 远程存储： https://artifact-public.instana.io/artifactory/shared
  • 身份验证： 已启用
    • 身份验证类型： 用户名
    • 用户名： _
    • 密码： 您的 Instana 下载密钥

JFrog Artifactory

首先，请按照 Artifactory 文档中的说明，准备一个自托管的 Artifactory 实例。

接下来，在 Artifactory 上创建一个新的远程仓库 ，配置如下：

  • 软件包类型：Maven
  • 仓库密钥： instana-shared
  • URL: https://artifact-public.instana.io/artifactory/shared
  • 用户名： _
  • 密码： 您的 Instana 下载密钥
  • 代码库结构：maven-2-default

配置代理程序

在线编辑

设置好 Maven 仓库镜像后，请配置您的动态代理以使用该镜像。 Instana 代理使用以下配置文件来管理对 Maven 存储库的访问：

  • org.ops4j.pax.url.mvn.cfg 配置主要存储库。
  • org.ops4j.pax.url.mvn.repositoriesmvn-settings.xml 为在.中定义的软件仓库配置镜像源。 该文件还配置了存储库及其镜像的凭据。

容器化代理会提供容器环境变量以及 Kubernetes 或 Helm 配置参数，用于调整配置文件中的相关设置。 这些机制消除了在容器中手动编辑配置文件的必要性。

您可以通过以下两种方式自定义动态代理 Maven 的配置：

配置 Maven 镜像站点

在线编辑

非集装箱化代理

要配置非容器化代理以使用镜像化的 Maven 存储库，请打开 文件 <instana-agent-dir>/etc/mvn-settings.xml ，然后取消注释并调整 部分 <mirrors> ：
<mirrors>
  <mirror>
    <id>instana-shared</id>
    <url>https://repo.example.com/artifactory/instana-shared</url>
    <mirrorOf>shared</mirrorOf>
  </mirror>
</mirrors>

请将示例中的 URL 替换为您仓库镜像的实际地址 URL。

如果您的镜像需要身份验证，请将凭据添加到 文件 mvn-settings.xml 中的 部分 <servers> ：
<servers>
  <server>
    <id>instana-shared</id>
    <username>myuser</username>
    <password>mypassword</password>
  </server>
</servers>

Kubernetes 环境

对于通过 operator 或 Helm 图表部署在 Kubernetes 上的代理，请使用以下配置参数：

  • agent.instanaSharedRepoMirrorUrl - 共享仓库的镜像地址： URL
  • agent.instanaSharedRepoMirrorUsername - 镜像认证的用户名
  • agent.instanaSharedRepoMirrorPassword - 镜像认证密码

Docker 容器

对于基于 Docker 的代理，请使用以下容器环境变量：

  • INSTANA_SHARED_REPOSITORY_MIRROR_URL - 共享仓库的镜像地址： URL
  • INSTANA_SHARED_REPOSITORY_MIRROR_USERNAME - 镜像认证的用户名
  • INSTANA_SHARED_REPOSITORY_MIRROR_PASSWORD - 镜像认证密码

覆盖默认的 Maven 仓库

在线编辑

除了配置代理使用仓库镜像外，您还可以覆盖默认的主仓库位置。

非集装箱化代理

要为非容器化代理设置 Maven 存储库位置，请编辑该 <instana-agent-dir>/etc/org.ops4j.pax.url.mvn.cfg 文件并修改该 org.ops4j.pax.url.mvn.repositories 设置：

org.ops4j.pax.url.mvn.repositories=https://repo.example.com/artifactory/instana-shared@id=shared@snapshots@snapshotsUpdate=always

URL 参数：

  • @id=shared - 仓库标识符。
  • @snapshots - 启用快照工件的使用。
  • @snapshotsUpdate=always - 在每次代理更新时更新快照工件。 如果未设置此参数，快照每24小时仅更新一次。

要配置多个仓库，请提供以逗号分隔的仓库 URL 列表。

如果 中的 org.ops4j.pax.url.mvn.repositories 某个仓库需要身份验证，请将凭据添加到 文件 <instana-agent-dir>/etc/mvn-settings.xml 中的 部分 <servers> ：
<servers>
  <server>
    <id>shared</id>
    <username>myuser</username>
    <password>mypassword</password>
  </server>
</servers>
容器化代理

请使用以下容器环境变量，为容器化代理设置 Maven 存储库的位置：

  1. INSTANA_MVN_REPOSITORY_URL - 基于您的 Maven 仓库的 URL 分支。 请参阅以下示例：
    INSTANA_MVN_REPOSITORY_URL=https://artifact-public.instana.io/artifactory
  2. sharedINSTANA_MVN_REPOSITORY_SHARED_PATH - 存储库的路径。 请参阅以下示例：
    INSTANA_MVN_REPOSITORY_SHARED_PATH=instana-shared@id=shared@snapshots@snapshotsUpdate=always

这些容器环境变量用于配置 配置文件 org.ops4j.pax.url.mvn.cfg 中的 设置 org.ops4j.pax.url.mvn.repositories ：

org.ops4j.pax.url.mvn.repositories=${INSTANA_MVN_REPOSITORY_URL}/${INSTANA_MVN_REPOSITORY_SHARED_PATH}

Maven 旧版存储库配置

在线编辑

在2026年5月之前，动态代理配置了两个 Maven 存储库： shared 和 features。 该 features 仓库已不再需要，因为所有必要的构建产物现已在该 shared 仓库中提供。

所有动态代理版本（无论发布日期如何）均与仅使用该 shared 存储库的新配置兼容。 所有动态代理（包括 2026 年 5 月及之后的版本）也将继续支持旧版 features 存储库的配置机制。

旧版镜像配置

对于非容器化代理，您仍可在 文件 <instana-agent-dir>/etc/mvn-settings.xml 中为 仓库 features 配置镜像：
<mirror>
  <id>instana-features</id>
  <url>https://repo.example.com/artifactory/instana-features</url>
  <mirrorOf>features</mirrorOf>
</mirror>
如果您的镜像需要身份验证，请将凭据添加到 文件 mvn-settings.xml 中的 部分 <servers> ：
<server>
  <id>instana-features</id>
  <username>myuser</username>
  <password>mypassword</password>
</server>

Kubernetes 的旧版配置

对于 Kubernetes 的部署，请使用以下配置参数为旧版 features 仓库配置镜像：

  • agent.agentReleaseRepoMirrorUrl
  • agent.agentReleaseRepoMirrorUsername
  • agent.agentReleaseRepoMirrorPassword

Docker 的旧版配置

对于基于 Docker 的代理，请使用以下容器环境变量来配置旧版 features 仓库的镜像：

  • AGENT_RELEASE_REPOSITORY_MIRROR_URL
  • AGENT_RELEASE_REPOSITORY_MIRROR_USERNAME
  • AGENT_RELEASE_REPOSITORY_MIRROR_PASSWORD

旧版仓库覆盖

org.ops4j.pax.url.mvn.repositories对于容器化代理，您可以选择使用 ` INSTANA_MVN_REPOSITORY_FEATURES_PATH container` 环境变量将仓库 features 添加到：

INSTANA_MVN_REPOSITORY_FEATURES_PATH=features-public@id=features@snapshots@snapshotsUpdate=always

如果设置了此容器环境变量，则会在容器配置中追加第二个仓库 URL ：

org.ops4j.pax.url.mvn.repositories=${INSTANA_MVN_REPOSITORY_URL}/${INSTANA_MVN_REPOSITORY_SHARED_PATH},${INSTANA_MVN_REPOSITORY_URL}/${INSTANA_MVN_REPOSITORY_FEATURES_PATH}