Maven 私服怎么搭：从安装到配置settings.xml 以及托管、代理、聚合仓

构建越来越慢、内部 jar 靠网盘传、外网一抖就 Could not transfer artifact——多半不是 Maven 坏了，而是私服还没接对：服务没起来、仓库类型不对、settings.xml / pom.xml 的 id 对不上，或令牌没配进密码位。

下面用 AngusRepo 社区版私有化部署，按操作顺序走完一遍：安装 → 建仓与令牌 → settings.xml 拉取 → pom.xml 发布 → 验证。命令里的主机写成 repo.example.com，换成你的域名即可。更细的 401/409 见 Maven deploy 失败排查。

1. 安装（得到可打开的控制台）

前提：Docker Engine + Compose v2；约 2 核 / 4 GB；放行 80；gm.example.com 与 repo.example.com 已解析到本机（试用可写 /etc/hosts）。完整步骤见 第一次跑通。

curl --fail --location --progress-bar -o AngusRepo-Community-1.0.0.zip \
  https://repo.anguskit.com/raw/raw-public/AngusKit/repo/AngusRepo-Community-1.0.0.zip
unzip AngusRepo-Community-1.0.0.zip
cd AngusRepo-1.0.0
./install.sh

向导与快速开始对齐：Compose；Access 选 2（捆绑反代）；TLS 选 4（HTTP :80）；Database 选 Compose 内 MySQL；Public DNS name 填后缀如 example.com。出现 Install finished. 后：

./bin/angusctl.sh doctor   # 看到 doctor: OK

浏览器打开 http://gm.example.com/ 登录，再打开 http://repo.example.com/。Windows 用 curl.exe + .\install.bat。需要 HTTPS 时见 安装与部署。

下文默认 HTTP 私有化，URL 写成 http://repo.example.com/...。上了可信证书后，把协议改成 https:// 即可。控制台能打开后，先建仓库和令牌，再改客户端配置。

2. 建仓、令牌与拓扑

推送（mvn deploy）只能进 HOSTED；PROXY、GROUP 只读。在 http://repo.example.com/ 创建（名称可自定，后面配置保持一致）：

GROUP 成员顺序建议 releases → snapshots → proxy：制品二进制按 first-match；maven-metadata.xml 版本列表合并各成员已登记版本。开发者只配一个拉取 URL；Release 与 SNAPSHOT 分仓，清理策略与是否可覆盖也不一样。

同一控制台继续准备：

• [ ] 创建访问令牌（只显示一次，立刻保存）
• [ ] CI 对两个 HOSTED 有 Write；开发者对 maven-group 有 Read
• [ ] GROUP 成员顺序确认为 releases → snapshots → central-proxy

export REPO_USER="admin"              # 控制台用户名，不是令牌名称
export REPO_TOKEN="your_access_token" # 密码位一律填令牌
export REPO_HOST="repo.example.com"   # 换成你的 repo.<域名>

具体路径以控制台「接入配置」为准；字段说明见 Maven 格式手册。

3. 拉取：settings.xml

用 mirror 把依赖请求指到 GROUP。保存为工程旁的 settings.xml，或合并进 ~/.m2/settings.xml 的 <servers> / <mirrors>，不要整文件覆盖。

<settings>
  <mirrors>
    <mirror>
      <id>angus-maven-group</id>
      <mirrorOf>*</mirrorOf>
      <url>http://repo.example.com/maven/maven-group/</url>
    </mirror>
  </mirrors>
  <servers>
    <server>
      <id>angus-maven-group</id>
      <username>${env.REPO_USER}</username>
      <password>${env.REPO_TOKEN}</password>
    </server>
    <server>
      <id>angus-maven-releases</id>
      <username>${env.REPO_USER}</username>
      <password>${env.REPO_TOKEN}</password>
    </server>
    <server>
      <id>angus-maven-snapshots</id>
      <username>${env.REPO_USER}</username>
      <password>${env.REPO_TOKEN}</password>
    </server>
  </servers>
</settings>

密码位填令牌。<server> 的 <id> 必须和下面 pom.xml / mirror 里用的 id 完全一致（区分大小写），对不上最常见就是 401。

4. 发布：pom.xml

发布目标必须是 HOSTED，不能指向 GROUP 或 PROXY。

<distributionManagement>
  <repository>
    <id>angus-maven-releases</id>
    <url>http://repo.example.com/maven/maven-releases/</url>
  </repository>
  <snapshotRepository>
    <id>angus-maven-snapshots</id>
    <url>http://repo.example.com/maven/maven-snapshots/</url>
  </snapshotRepository>
</distributionManagement>

5. 验证闭环

# 拉取：走 GROUP；第一次可能回源，第二次应走 PROXY 缓存
mvn -s settings.xml dependency:resolve

# 发布：进对应 HOSTED
mvn -s settings.xml clean deploy

控制台制品列表应能看到新版本；再从 GROUP 解析同一坐标，应能拉到。CI 里同样注入 REPO_USER / REPO_TOKEN，并用同一份 settings.xml。流水线编排可另见 Jenkins 构建测试发布。Gradle 怎么接同一套私服见后续 Gradle 专文。

6. 日常维护（resolve / deploy 跑通之后）

清理 SNAPSHOT — 每个制品保留最近 N 个版本，先 Dry Run，见 清理策略。Release 仓保持不可变，重复 deploy 会 409。

PROXY 冷缓存 — 首次拉中央仓依赖会慢，属正常；可对高频依赖做预热。

入库检查 — 上传时有轻量门禁；需要更细的漏洞 / 许可证分析时再接外部扫描。打开阻断前先处理误报，见 入库门禁与 SBOM。

报错速查

字段级说明见 Maven 格式手册；更多排错见 故障排查手册。

FAQ

能不能 deploy 到 GROUP？

不能。GROUP / PROXY 只读，发布必须指向 HOSTED。

Release 和 SNAPSHOT 为什么要分仓？

正式版应不可变；SNAPSHOT 允许同版本覆盖，清理策略也不同。混在一个仓里，权限和清理都难做干净。

settings.xml 里 mirror 的 id 要和 server 一致吗？

要。mirror、distributionManagement 与对应 <server> 的 id 必须对齐，Maven 才会带上认证。

小结

• 安装并打开控制台 → 建两个 HOSTED + PROXY + GROUP → 发令牌。
• 拉取走 GROUP（settings.xml mirror）；发布走 HOSTED（pom.xml distributionManagement）。
• id 对齐 + 令牌进密码位，是避免 401 的关键；Release 不要重复 deploy。
• 跑通后配 SNAPSHOT 清理与 PROXY 预热，避免磁盘和冷缓存拖慢构建。

参考文章

• 第一次跑通
• 安装与部署
• Maven 格式
• 清理策略
• Maven deploy 失败排查
• Jenkins 构建测试发布
• 入库门禁与 SBOM
• 故障排查手册