统一发包管理（Maven 仓库）详细步骤

适用于希望在公司/团队内部统一管理 Java 构件（JAR、POM、源码包）、实现统一依赖来源、防止"本地有但别人拉不到"的情况，并方便与 CI/CD 对接的场景。下面以 Nexus Repository 为例说明，也可替换为 JFrog Artifactory、阿里云制品库等。

1. 为什么要统一发包

依赖统一来源：所有项目从同一套 Maven 仓库下载构件，减少"拉不下来"的问题。
私有包可控：公司内部研发的公共组件、SDK、网关适配器等只发到内部仓库，不暴露到公网。
版本可追踪：每次发版都会留下坐标与元数据，可追踪构建来源。
便于 CI/CD：构建机/流水线只要配置一次 settings.xml，即可统一发布。
权限治理：控制谁能发布、谁只能下载，避免误传。

2. 方案选型

常见三种：

直接用 Maven Central
- 适用于开源库/需公开的组件
- 审核流程复杂，不适合公司内部频繁发包
自建 Maven 私服（推荐）
- 常见：Sonatype Nexus , JFrog Artifactory , Apache Archiva
- 完整支持 Maven、npm、docker 等多种格式
云厂商制品库
- 如阿里云/华为云/腾讯云的制品仓库
- 运维成本低，适合不想自己搭建的团队

下面以 Nexus 3 为例写详细步骤。

3. 搭建 Maven 私服（以 Nexus 3 为例）

3.1 安装前提

一台能被开发机/CI 访问到的服务器（Linux/Windows 都可）
JDK 8+（部分版本 Nexus 自带）
开放 Web 端口（默认 8081）

3.2 安装示意（Linux）

bash 复制代码

# 1. 下载
wget https://download.sonatype.com/nexus/3/latest-unix.tar.gz
tar -zxvf latest-unix.tar.gz -C /opt
mv /opt/nexus-* /opt/nexus

# 2. 创建数据目录（可选）
mkdir -p /data/nexus-data
chown -R nexus:nexus /data/nexus-data

# 3. 配置运行用户 & 数据目录
vim /opt/nexus/bin/nexus.rc
# 添加：
run_as_user="nexus"

vim /opt/nexus/bin/nexus.vmoptions
# 修改数据路径：
-Dkaraf.data=/data/nexus-data

3.3 启动

bash 复制代码

# 切到 nexus 用户
su - nexus
/opt/nexus/bin/nexus start

# 查看日志
tail -f /data/nexus-data/log/nexus.log

3.4 首次登录

浏览器打开：http://<server-ip>:8081/
初始账号：admin
初始密码在：/data/nexus-data/admin.password
登录后请立即修改密码，并创建团队账号/角色

4. 仓库类型规划

Nexus 中 Maven 仓库一般分 3 类：

hosted（宿主/私有仓库）
- 用来存你们自己发的包
- 建议建一个：maven-releases（发布版），一个：maven-snapshots（快照版）
proxy（代理仓库）
- 代理中央仓库、阿里云仓库等
- 例如创建：maven-central，地址指向 https://repo1.maven.org/maven2/
group（仓库组）
- 把多个仓库组合成一个对外的地址，开发者只需要配一个仓库组
- 比如建一个 maven-public，里面包含：maven-releases + maven-snapshots + maven-central

4.1 建议的仓库结构

maven-releases：你们正式发布的包
maven-snapshots：开发中不稳定的包
maven-central（proxy）：公共开源包
maven-public（group）：对外统一使用的地址

这样开发者 settings.xml 里只要配一个 maven-public 即可。

5. 客户端（开发者）配置 settings.xml

开发者本地或 CI 机器要能：

从私服下载依赖
向私服上传构件（deploy）

5.1 基础 settings.xml 样例

通常放在：~/.m2/settings.xml，示例：

xml 复制代码

<settings>
  <!-- 1. 认证信息 -->
  <servers>
    <!-- id 必须与后面 distributionManagement/repositories 中的 id 一致 -->
    <server>
      <id>nexus-releases</id>
      <username>deploy-user</username>
      <password>deploy-pass</password>
    </server>
    <server>
      <id>nexus-snapshots</id>
      <username>deploy-user</username>
      <password>deploy-pass</password>
    </server>
  </servers>

  <!-- 2. 镜像，把所有请求都打到仓库组 -->
  <mirrors>
    <mirror>
      <id>nexus-public</id>
      <mirrorOf>*</mirrorOf>
      <url>http://your-nexus:8081/repository/maven-public/</url>
    </mirror>
  </mirrors>

  <!-- 3. 配置代理/本地仓库路径等也可在这里 -->
</settings>

注意：http://your-nexus:8081/... 换成你们自己的地址；企业环境建议走 https。

6. 项目 POM 中的发布配置

在你要"发包"的项目中，pom.xml 里要声明把构件发到哪里去。

xml 复制代码

<project>
  ...
  <distributionManagement>
    <!-- 正式版 -->
    <repository>
      <id>nexus-releases</id>
      <name>Nexus Releases</name>
      <url>http://your-nexus:8081/repository/maven-releases/</url>
    </repository>

    <!-- 快照版 -->
    <snapshotRepository>
      <id>nexus-snapshots</id>
      <name>Nexus Snapshots</name>
      <url>http://your-nexus:8081/repository/maven-snapshots/</url>
    </snapshotRepository>
  </distributionManagement>
</project>

这里的 <id> 必须和 settings.xml 里的 <server> 的 id 一一对应，这样 Maven 才知道用哪个账号密码去 deploy。

7. 如何发包（本地）

7.1 打包

bash 复制代码

mvn clean install

7.2 deploy 到私服

bash 复制代码

mvn clean deploy

如果是 1.0.0-SNAPSHOT 这种版本号，Maven 会自动发到 snapshot 仓库
如果是 1.0.0 这种没有 SNAPSHOT 的，会发到 releases 仓库

7.3 常见补充

需要源码包：在 pom 里加 maven-source-plugin
需要 javadoc 包：加 maven-javadoc-plugin
这样你们的私服里会有更完整的构件信息

8. 与 CI/CD 集成

以 Jenkins/GitLab CI 为例，流程通常是：

拉代码
执行测试 ：mvn test
构建并部署 ：mvn -s settings.xml clean deploy
settings.xml 放在 CI 的凭据里 （或把 <servers> 部分的密码从 Jenkins Credentials 注入）
构建机和开发者使用同一套仓库地址 → 保证一致性

示例（GitLab CI 片段）：

yaml 复制代码

deploy:
  stage: deploy
  script:
    - mvn -s .maven/settings.xml clean deploy
  only:
    - main

9. 版本与分支策略建议

主干发正式版 ：main/master 构建 -> 1.0.0, 1.0.1
开发分支发快照版 ：feature/dev 构建 -> 1.0.1-SNAPSHOT
禁止覆盖 release：Nexus releases 仓库可设置为不可重写，防止误部署
组件要有变更记录：推荐配合 Git Tag + CHANGELOG

10. 权限和安全

创建专门的 deploy 账号，不要用 admin
按仓库授权：谁能发 releases，谁只能发 snapshots
开启 https，避免密码明文传输
如果是公网访问，建议接一层 Nginx 做反向代理 + 认证

11. 常见问题排查

401/权限不足
- 检查 settings.xml 中 <server> 的用户名密码
- 检查发版用的仓库地址是不是 releases/snapshots 写反了
Repository does not allow updating assets
- 你在往 releases 里发同一个版本，且仓库不允许覆盖
- 解决：改版本号，或在 Nexus 中开启允许重写（不推荐）
Could not transfer artifact ... from/to ...
- 检查 Nexus 是否能访问外网（proxy 仓库拉不下来）
- 检查你本机/CI 是否能访问 Nexus 域名/端口
下载特别慢
- 给 Nexus 配置国内公共源的 proxy，如阿里云
- 或者让 Nexus 挂在离 CI 更近的网络位置

12. 落地清单（Checklist）

私服服务可访问（Nexus/Artifactory）
建好了 releases / snapshots / proxy / public group
开发机 settings.xml 配置完成
项目 pom.xml 配置 distributionManagement
CI 中能执行 mvn deploy
权限分配给了专用账号
出现问题有日志可查（Nexus 日志 + Maven 构建日志）

13. 参考模板：最短可用示例

settings.xml（开发者本机）

xml 复制代码

<settings>
  <servers>
    <server>
      <id>nexus-releases</id>
      <username>deploy-user</username>
      <password>deploy-pass</password>
    </server>
    <server>
      <id>nexus-snapshots</id>
      <username>deploy-user</username>
      <password>deploy-pass</password>
    </server>
  </servers>
  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://your-nexus/repository/maven-public/</url>
    </mirror>
  </mirrors>
</settings>

pom.xml（需要发包的项目）

xml 复制代码

<project>
  ...
  <version>1.0.0-SNAPSHOT</version>

  <distributionManagement>
    <repository>
      <id>nexus-releases</id>
      <url>http://your-nexus/repository/maven-releases/</url>
    </repository>
    <snapshotRepository>
      <id>nexus-snapshots</id>
      <url>http://your-nexus/repository/maven-snapshots/</url>
    </snapshotRepository>
  </distributionManagement>
</project>

这样你就完成了"统一发包管理（Maven 仓库）"的基本建设。