构建越来越慢、内部 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`）。完整步骤见 第一次跑通。

```bash
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.` 后：

```bash
./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/` 创建（名称可自定，后面配置保持一致）：

| 仓库名示例 | 类型 | 干什么 |
| --- | --- | --- |
| `maven-releases` | HOSTED | 正式版；建议禁止覆盖 |
| `maven-snapshots` | HOSTED | SNAPSHOT；允许同版本覆盖 |
| `maven-central-proxy` | PROXY | 代理 Maven Central（远程 URL：`https://repo1.maven.org/maven2/`） |
| `maven-group` | GROUP | 统一拉取入口；成员顺序 release → snapshot → proxy |

![Maven 私服拓扑：deploy 到 HOSTED，resolve 经 GROUP 聚合 releases、snapshots 与 PROXY](https://developer.qcloudimg.com/http-save/yehe-1099973/5284a440fb1b40a56267ca5e3ccc26c1.png)
GROUP 成员顺序建议 releases → snapshots → proxy：制品二进制按 **first-match**；`maven-metadata.xml` 版本列表合并各成员已登记版本。开发者只配一个拉取 URL；Release 与 SNAPSHOT 分仓，清理策略与是否可覆盖也不一样。

同一控制台继续准备：

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

```bash
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>`，不要整文件覆盖。

```xml
<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。

```xml
<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. 验证闭环

```bash
# 拉取：走 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。

## 报错速查

| 症状 | 常见原因 | 怎么处理 |
| --- | --- | --- |
| `401 Unauthorized` | server id 与 pom/mirror 不一致，或令牌过期 | 核对 id；密码位改令牌；见 deploy 排查 |
| `409 Conflict` | 正式版重复 deploy | 升版本号，不要覆盖 Release |
| 中央仓有包却 `404` | GROUP 成员顺序错，或 PROXY 回源失败 | 查成员顺序与 PROXY 健康检查 |
| 一直拿到旧 SNAPSHOT | 本地 `~/.m2` 缓存 | `mvn -U`，或清掉对应目录 |
| 首次拉取很慢 | PROXY 冷缓存 | 正常；可预热高频依赖 |

字段级说明见 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 预热，避免磁盘和冷缓存拖慢构建。

## 参考文章

- [第一次跑通](https://www.anguskit.com/zh/docs/repo/get-started/quickstart)
- [安装与部署](https://www.anguskit.com/zh/docs/repo/manual/02-installation)
- [Maven 格式](https://www.anguskit.com/zh/docs/repo/manual/05-formats/01-maven)
- [清理策略](https://www.anguskit.com/zh/docs/repo/manual/10-cleanup)
- [Maven deploy 失败排查](https://www.anguskit.com/zh/blog/maven-deploy-failure-troubleshooting)
- [Jenkins 构建测试发布](https://www.anguskit.com/zh/blog/jenkins-pipeline-build-test-publish-artifacts)
- [入库门禁与 SBOM](https://www.anguskit.com/zh/blog/supply-chain-gate-sbom)
- [故障排查手册](https://www.anguskit.com/zh/docs/repo/manual/17-troubleshooting)

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

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

私有化部署后接 Maven：建 HOSTED/PROXY/GROUP，配 settings.xml 与 pom.xml，完成 resolve、deploy，并处理 401/409。

人工智能

Maven构建异常与私服配置密切相关。AngusRepo社区版提供私有化部署方案，通过安装、建仓、令牌配置、settings.xml拉取及pom.xml发布完成闭环。重点确保仓库类型匹配、id一致、密码位填入令牌，拉取走GROUP，发布走HOSTED。附常见401/409错误排查与日常维护建议。

代码解释

Windows

MySQL

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Maven 私服怎么搭：从安装到配置settings.xml 以及托管、代理、聚合仓-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐