构建与依赖 / 系统课时

代理、认证与网络配置

代理、认证与网络配置

这节解决 Maven 在公司代理、私有仓库和 CI 环境里“能连网却拉不到依赖”的问题。完成后,你会把代理和仓库凭据放进 settings.xml,用仓库 ID 正确匹配认证信息,并能根据 401、403、407 和 TLS 错误快速定位故障。

学习目标

  • 配置 Maven 3.9.x 的 HTTP 代理、镜像与私服认证,并避免把密码写进项目 POM。
  • 理解 server.id、仓库或镜像 id 的匹配规则,能检查认证为什么没有生效。
  • 在 CI 中使用批处理模式和秘密注入完成非交互式构建,并按错误类型排查网络问题。

把网络与凭据移出 POM

Maven 的用户级配置默认位于 ~/.m2/settings.xml,这里适合放代理、镜像和服务器认证。项目仓库地址可以由 POM 描述,但用户名、令牌和代理密码不应随源码分发。下面示例面向 Maven 3.9.x;仓库与代理域名使用示例域名,实际项目替换为自己的地址。

xml
<settings>
  <proxies>
    <proxy>
      <id>corp-http-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.corp.example</host>
      <port>8080</port>
      <username>${env.PROXY_USER}</username>
      <password>${env.PROXY_TOKEN}</password>
      <nonProxyHosts>localhost|127.*</nonProxyHosts>
    </proxy>
  </proxies>
  <mirrors>
    <mirror>
      <id>corp-repo</id>
      <name>Corporate Repository Manager</name>
      <url>https://repo.corp.example/repository/maven-public/</url>
      <mirrorOf>*</mirrorOf>
    </mirror>
  </mirrors>
  <servers>
    <server>
      <id>corp-repo</id>
      <username>${env.REPO_USER}</username>
      <password>${env.REPO_TOKEN}</password>
    </server>
  </servers>
</settings>

这个文件把四个敏感值留给环境变量注入;Maven 的 settings.xml 支持 ${env.NAME} 形式的环境变量插值。nonProxyHosts 使用 | 分隔,适合把本机或内网直连地址排除在代理之外。若代理不需要认证,直接删除代理里的 username 和 password。

Maven 通过代理访问私服并按 ID 选择凭据

让 ID 匹配后再谈认证

<servers> 不按 URL 选凭据,而是按 id 匹配。若 mirrorOf 为 *,中央仓库等请求会先被镜像替换,此时真正连接的是镜像 corp-repo,所以 <server><id> 也必须写 corp-repo;写成 central 往往会导致请求没有带上正确凭据。

连接方式 凭据应匹配的 ID 常见错误
直接访问 POM 中的 <repository> 该 repository 的 id server id 拼错,返回 401
通过 <mirror> 替换仓库 mirror 的 id 仍给原 repository id 配凭据
经过认证代理 <proxy> 自己的用户名和密码 把私服令牌误当代理密码

在 CI 已注入 PROXY_USER、PROXY_TOKEN、REPO_USER、REPO_TOKEN 后,可直接用同一份仅含占位符的配置验证。-B 是批处理模式,-ntp 关闭下载进度,-U 会要求 Maven 检查缺失的 release 和更新的 SNAPSHOT。

bash
test -n "${REPO_USER:-}" && test -n "${REPO_TOKEN:-}" && test -n "${PROXY_USER:-}" && test -n "${PROXY_TOKEN:-}"
mvn -B -s ./ci/settings.xml -ntp -U verify

预期结果:项目本身可正常构建且网络配置正确时,末尾应出现:

text
[INFO] BUILD SUCCESS

如果公司代理无需用户名和密码,应同时从 settings.xml 和变量检查命令中移除 PROXY_USER、PROXY_TOKEN,不要为了“配置完整”保留空凭据。

在 CI 中做非交互式认证

非交互式认证的关键不是让 Maven 自动猜密码,而是让 CI 在进程启动前准备好凭据。推荐把 REPO_USER、REPO_TOKEN 等保存到 CI 的 Secret 管理中,运行时注入环境变量;提交到仓库的 settings.xml 只保留 ${env.REPO_TOKEN} 这类引用,并限制构建日志打印环境变量。

Maven 3 也支持服务器密码加密。首次配置时运行 mvn --encrypt-master-password,把结果保存到 ~/.m2/settings-security.xml;再运行 mvn --encrypt-password,把得到的加密值放入 settings.xml 的 <password>。这两条命令建议不带密码参数,让 Maven交互读取,避免明文进入 shell 历史。

本地 Linux 或 macOS 可把敏感配置权限收紧为 600;Windows 则应使用文件 ACL 只允许构建账户读取。CI 使用临时工作目录时,构建结束后还应删除动态生成的 settings.xml,避免工作区归档把凭据带走。

按错误类型定位网络问题

先看 HTTP 或 TLS 错误,再决定改代理、凭据还是证书;不要一上来删除整个 ~/.m2/repository。同一条 mvn -B -s ./ci/settings.xml -ntp -U verify 命令即可作为复现入口,必要时临时增加 -X 获取调试日志,但分享日志前要检查 URL、用户名和令牌是否被带出。

现象 优先检查 处理动作
407 Proxy Authentication Required 代理用户名、密码、代理地址 修正 <proxy>,确认代理账号可用
401 Unauthorized <server><id> 与实际 repository 或 mirror id 修正 ID 或仓库令牌
403 Forbidden 账号权限、仓库路径策略 让仓库管理员确认读取权限
Unknown host / connect timeout DNS、代理 host/port、nonProxyHosts 用同网络环境验证代理可达性
PKIX path building failed 企业 TLS 代理或私有 CA 把受信 CA 正确导入构建 JDK 的信任库

最终验收可以很具体:同一台构建机上,删除项目 target 后执行批处理构建,不出现凭据提示、不把密码写入 POM、网络请求经过预期代理,且依赖能从指定私服解析并得到 BUILD SUCCESS。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

代理、认证与网络配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通