1. 为什么要在内网自建 Docker 镜像仓库很多团队一开始都是直接用公共镜像仓库拉取基础镜像本地构建完业务镜像后要么推到公共仓库要么干脆只在本地留着。等到服务器规模一上来问题就全冒出来了构建机拉取镜像慢、带宽被反复占用、不同环境拿到的镜像版本对不上、CI 流水线里因为网络抖动频繁失败。更麻烦的是有些内部业务镜像根本不适合放到公网仓库一旦泄露就是安全事故。我所在的团队就踩过这个坑。早期十几台机器的时候大家各自docker pull公共镜像勉强能忍。后来机器数量涨到几十台每次发版所有节点同时拉镜像出口带宽直接被拉满构建时间从几分钟变成十几分钟。那段时间我几乎天天在排查“为什么这次部署又超时了”。后来痛定思痛决定在内网搭一个私有镜像仓库把所有基础镜像和业务镜像都收拢进来统一管理。选型上其实没纠结太久。私有仓库方案无非就那么几种官方 registry、Harbor、Nexus3 这几类。官方 registry 太简陋没有 Web 界面权限管理也弱Harbor 功能全但组件多部署和维护成本偏高对中小团队来说有点重。Nexus3 是我比较熟悉的老朋友了它本来就是个仓库管理器支持 Maven、npm、PyPI、Docker 等多种格式一个服务就能把公司里各种包管理需求全兜住。而且它自带 Web 管理界面、用户权限体系、清理策略用 Docker 部署也就一条命令的事。所以这篇文章我就围绕docker 搭建 nexus3 并配置 docker 私有仓库这个主题把整个落地过程讲透。从镜像拉取、容器启动、仓库创建、权限配置到客户端对接、推送拉取验证、常见坑排查全部走一遍。适合正在考虑自建镜像仓库的运维、后端、DevOps 同学参考哪怕你之前没接触过 Nexus跟着做也能跑通。2. 部署前的整体设计与关键决策2.1 为什么用 Docker 跑 Nexus3 而不是裸装Nexus3 官方提供了多种安装方式直接下载 tar 包解压、rpm/deb 包安装、Docker 镜像运行。我强烈建议用 Docker 方式原因有几个。第一是环境隔离干净。Nexus3 依赖 JVM裸装的话你得先装 JDK还得考虑版本兼容。用 Docker 镜像JVM 和依赖全打包在里面宿主机只需要有 Docker 就行不会污染系统环境。第二是升级和迁移方便。Nexus3 的数据都在一个数据目录里用 Docker 的话把这个目录挂载到宿主机升级时直接换镜像重启数据还在。迁移到另一台机器也就是把数据目录拷过去的事。第三是资源限制好控制。Nexus3 默认会吃不少内存用 Docker 可以方便地通过参数限制内存上限避免它把宿主机内存吃光影响其他服务。当然也有代价就是多了一层容器网络端口映射和存储挂载要配置清楚。但这点成本相比收益完全可以接受。2.2 数据持久化的规划这是整个部署里最容易被忽视、也最容易出事的一环。Nexus3 容器里有两个关键目录需要持久化/nexus-data这是 Nexus3 的核心数据目录包含配置、仓库元数据、blob 存储、用户信息等。这个目录绝对不能丢丢了等于整个仓库重建。日志目录一般也在/nexus-data/log下面跟着一起挂载就行。我的做法是在宿主机上单独划一个目录比如/data/nexus3/nexus-data然后通过-v挂载进容器。这样即使容器被删了数据还在重新起一个容器挂上同一个目录就能恢复。这里有个细节要注意Nexus3 容器内默认以 UID 200 的用户运行如果你挂载的宿主机目录权限不对容器启动会因为写不了数据目录而失败。所以挂载前要先chown -R 200:200 /data/nexus3/nexus-data把目录属主改成 200。这个坑我见过太多人踩容器一直重启日志里报权限拒绝查半天才发现是目录权限问题。2.3 端口与访问方式的取舍Nexus3 默认监听 8081 端口这是 Web 管理界面和 API 的入口。Docker 私有仓库功能则通常再单独开一个端口比如 8082用来处理 Docker 的 push/pull 请求。为什么 Docker 仓库要单独一个端口因为 Docker 客户端对 registry 的访问路径有固定约定比如/v2/、/v2/name/manifests/tag这些。如果和 Web 界面共用端口路径容易冲突配置起来也麻烦。Nexus3 支持为 Docker 仓库单独配置一个 connector 端口这样职责清晰Web 管理走 8081镜像推拉走 8082。另外还要考虑是否启用 HTTPS。Docker 默认要求 registry 走 HTTPS如果走 HTTP需要在客户端的daemon.json里配置insecure-registries。内网环境如果暂时没有证书可以先走 HTTP 加白名单的方式但生产环境我还是建议上 HTTPS后面会讲怎么配。2.4 内存与 JVM 参数预估Nexus3 是个 Java 应用内存给少了会频繁 GC 甚至 OOM。官方建议至少 4GB 内存我实测下来如果只是当 Docker 仓库用2GB 到 4GB 之间比较稳妥。容器启动时可以通过-e INSTALL4J_ADD_VM_PARAMS来调整 JVM 参数比如设置堆大小。一个常见的配置是-Xms1g -Xmx2g -XX:MaxDirectMemorySize2g。这里MaxDirectMemorySize容易被忽略Nexus3 处理大镜像上传时会用到直接内存如果这个值太小上传大镜像可能失败。我一开始没设传一个 1GB 多的镜像时直接报错后来加上就好了。3. 一步步搭建 Nexus3 容器3.1 拉取镜像与目录准备先拉官方镜像。这里建议指定一个明确的版本号不要用latest避免哪天官方更新了导致行为变化。docker pull sonatype/nexus3:3.68.0然后准备数据目录mkdir -p /data/nexus3/nexus-data chown -R 200:200 /data/nexus3/nexus-data这两条命令看着简单但第二条是必须的。我见过有人跳过这步容器起来后一直重启docker logs里全是Permission denied折腾半天才反应过来是权限问题。3.2 启动容器的完整命令下面是我实际用的启动命令参数都加了注释说明docker run -d \ --name nexus3 \ --restart always \ -p 8081:8081 \ -p 8082:8082 \ -v /data/nexus3/nexus-data:/nexus-data \ -e INSTALL4J_ADD_VM_PARAMS-Xms1g -Xmx2g -XX:MaxDirectMemorySize2g \ sonatype/nexus3:3.68.0逐条解释一下--restart always让容器在宿主机重启后自动拉起生产环境必备。-p 8081:8081Web 管理界面端口。-p 8082:8082预留给 Docker 仓库的 connector 端口后面在 Nexus 里配置。-v数据持久化挂载。-e INSTALL4J_ADD_VM_PARAMS调整 JVM 内存参数。启动后别急着访问Nexus3 首次启动要初始化数据大概需要一到两分钟。可以用docker logs -f nexus3观察看到类似Started Sonatype Nexus的字样就说明起来了。3.3 获取初始管理员密码Nexus3 新版本不再用默认的admin/admin123而是生成一个随机初始密码存在数据目录里的一个文件中。进容器查看docker exec nexus3 cat /nexus-data/admin.password拿到这串密码后浏览器访问http://宿主机IP:8081用用户名admin和这串密码登录。登录后会强制要求你修改密码改成一个自己记得住的强密码。提示这个初始密码文件在修改密码后会被删除所以第一次登录后一定要把新密码记好。如果忘了密码只能通过删除数据目录里的相关配置重置代价比较大。3.4 首次登录后的基础设置登录进去后建议先做几件事。一是到设置里把匿名访问关掉避免任何人都能匿名拉取镜像。二是规划好仓库的命名规范比如按环境分dev、prod或者按团队分。三是想清楚清理策略镜像越堆越多磁盘迟早会满。4. 创建 Docker 私有仓库的完整配置4.1 Docker 仓库的三种类型Nexus3 里 Docker 仓库分三种类型理解它们的区别很关键类型作用典型用途hosted本地托管仓库存放自己推送的镜像存放内部业务镜像proxy代理仓库缓存远程公共仓库的镜像缓存基础镜像加速拉取group聚合仓库把多个仓库合并成一个入口统一拉取入口简化客户端配置我的建议是三种都建。hosted 放自己的镜像proxy 代理公共仓库做缓存group 把前两者聚合起来客户端只需要配置 group 的地址拉取时 Nexus 会自动判断是从本地取还是去代理缓存取。这样既省事又高效。4.2 创建 hosted 类型的 Docker 仓库进入 Nexus 管理界面路径是设置 - Repository - Repositories - Create repository选择docker (hosted)。关键参数这样填Namedocker-hosted名字自己定但要有辨识度。HTTP勾选端口填8082。这就是前面容器映射出来的端口。Enable Docker V1 API一般不用勾现在都是 V2 API。StorageBlob store 用默认的 default 就行如果镜像量大可以单独建一个 blob store 方便管理。Hosted 下的 Deployment policy选Allow redeploy这样同一个 tag 可以重复推送覆盖。如果选Disable redeploy同 tag 第二次推送会被拒绝适合对版本严格管控的场景。创建完成后这个仓库就能接收 push 了。4.3 创建 proxy 类型的 Docker 仓库同样在创建页面选docker (proxy)。Namedocker-proxy。Remote storage填公共镜像仓库的地址比如https://registry-1.docker.io。Docker Index选Use Docker Hub或者手动指定。HTTP这里注意proxy 仓库通常不需要单独开端口它通过 group 或者 hosted 的端口被访问。但如果你想让 proxy 也能独立访问可以给它分配端口。我一般不给 proxy 单独开端口统一走 group。proxy 仓库的作用是缓存。第一次拉某个镜像时Nexus 会去远程拉取并缓存到本地第二次再拉就直接从本地返回速度飞快。这对频繁拉取基础镜像的场景帮助巨大。4.4 创建 group 类型的 Docker 仓库选docker (group)。Namedocker-group。HTTP勾选端口填8083或者复用其他端口但要保证不冲突。这里我习惯给 group 单独一个端口客户端统一连这个。Member repositories把docker-hosted和docker-proxy都加进去顺序上 hosted 放前面这样拉取时优先查本地。创建完这三个仓库整个 Docker 仓库体系就搭好了。客户端只需要配置 group 的地址就能同时享受本地镜像和代理缓存。4.5 配置权限与用户默认情况下只有 admin 能操作。生产环境肯定不能大家都用 admin得建专门的用户和角色。先建角色设置 - Security - Roles - Create role。比如建一个docker-push角色赋予nx-repository-view-docker-docker-hosted-add、nx-repository-view-docker-docker-hosted-edit、nx-repository-view-docker-docker-hosted-read这些权限。再建一个docker-pull角色只给 read 权限。然后建用户把角色分配给用户。这样 CI 流水线用一个有 push 权限的账号普通开发者用只有 pull 权限的账号权限清晰。注意Docker 客户端登录时用的是 Nexus 的用户名密码但 Docker 对密码里的特殊字符有时处理不好建议给这类服务账号设置不含特殊符号的强密码避免登录失败。5. 客户端对接与推拉验证5.1 配置 Docker 客户端信任如果 Nexus 走的是 HTTP需要在每台客户端的/etc/docker/daemon.json里加上{ insecure-registries: [192.168.1.100:8083] }把 IP 和端口换成你自己的。改完重启 Dockersystemctl restart docker如果走 HTTPS 且有可信证书就不需要这一步。内网测试阶段用 HTTP 加白名单是最快的但生产环境强烈建议上 HTTPS。5.2 登录私有仓库docker login 192.168.1.100:8083输入前面建的用户名和密码。登录成功后凭据会存在~/.docker/config.json里。5.3 给镜像打 tag 并推送假设本地有个镜像叫myapp:1.0要推到私有仓库docker tag myapp:1.0 192.168.1.100:8083/myapp:1.0 docker push 192.168.1.100:8083/myapp:1.0推送时注意镜像名的格式仓库地址/镜像名:tag。仓库地址就是 group 的地址。推上去后在 Nexus 界面里进docker-hosted仓库就能看到这个镜像。5.4 从私有仓库拉取在另一台机器上docker pull 192.168.1.100:8083/myapp:1.0如果这个镜像在 hosted 里直接从本地返回如果不在Nexus 会去 proxy 对应的远程仓库找找到后缓存下来再返回。整个过程对客户端透明。5.5 验证代理缓存是否生效拉一个公共基础镜像测试docker pull 192.168.1.100:8083/library/nginx:latest第一次拉会慢一点因为要去远程取。拉完后再拉一次速度应该明显变快因为已经缓存到本地了。也可以去 Nexus 界面看docker-proxy仓库的存储占用确认缓存生效。6. 常见问题与排查技巧实录6.1 容器启动失败或反复重启最常见的原因就是数据目录权限不对。排查步骤docker logs nexus3如果看到Permission denied或者Cannot write to /nexus-data就是权限问题。解决方法是停掉容器chown -R 200:200 /data/nexus3/nexus-data再启动。另一个原因是内存不足。如果日志里有 OOM 相关字样调大-Xmx和MaxDirectMemorySize。6.2 推送镜像报 413 或超时大镜像推送失败通常是两个原因。一是 Nexus 的直接内存不够前面提到的MaxDirectMemorySize要调大。二是反向代理如果有的请求体大小限制比如 Nginx 默认client_max_body_size是 1MB传大镜像直接被拦。如果前面挂了 Nginx要把它调大比如client_max_body_size 0表示不限制。6.3 客户端登录报错docker login失败先确认地址和端口对不对再确认insecure-registries配了没有。如果报http: server gave HTTP response to HTTPS client就是客户端在尝试 HTTPS 但服务端是 HTTP加白名单即可。6.4 拉取镜像报 manifest 相关错误有时候拉取会报manifest unknown或manifest invalid。这通常是镜像 tag 不存在或者仓库类型配置有问题。确认镜像确实推到了 hosted 仓库且 group 里包含了这个 hosted 仓库。6.5 磁盘空间被吃满镜像越堆越多是必然的。Nexus3 有清理策略功能可以配置定期删除旧版本镜像。路径是设置 - Repository - Cleanup Policies建一个策略比如保留最近 30 天或者最近 10 个版本然后把它应用到 Docker 仓库上。另外可以配置一个定时任务定期执行清理。下面这张表汇总了常见问题和对应处理方式现象可能原因处理方式容器反复重启数据目录权限不对chown 200:200 后重启容器 OOMJVM 内存不足调大 Xmx 和直接内存推送 413请求体限制调大代理的 body 限制登录失败未配 insecure-registries加白名单重启 Dockermanifest 错误tag 不存在或仓库配置错核对仓库和 tag磁盘满镜像未清理配置清理策略和定时任务6.6 几个我踩过的坑第一个坑是没给 group 单独开端口直接拿 hosted 的端口当统一入口结果代理缓存用不上每次拉公共镜像还是走远程。后来给 group 单独配了端口客户端统一连 group问题解决。第二个坑是清理策略配了但没生效原因是没建对应的定时任务。Nexus 的清理策略需要配合Admin - Tasks里的Cleanup service任务才会定期执行光建策略不建任务是没用的。第三个坑是升级镜像时直接docker rm旧容器结果忘了数据目录挂载的路径新容器挂了个空目录数据全没了。好在有备份。所以升级前一定要确认挂载路径最好先备份数据目录。7. 生产环境的加固建议7.1 上 HTTPS内网也不能完全裸奔。给 Nexus 配 HTTPS 有两种方式一是直接在 Nexus 里配置 SSL 证书二是前面挂一个反向代理做 TLS 终止。后者更灵活证书管理也方便。配好 HTTPS 后客户端就不需要insecure-registries了安全性提升一个档次。7.2 定期备份数据目录Nexus 的数据目录就是全部家当。建议用定时任务定期打包备份比如每天凌晨备份一次保留最近 7 天。备份时最好先停容器或者用 Nexus 自带的备份任务避免数据不一致。7.3 监控与告警至少要监控两件事磁盘使用率和容器健康状态。磁盘快满时提前告警避免写满导致服务不可用。容器可以用docker inspect或者外部监控工具检查健康状态。7.4 高可用考虑单点 Nexus 挂了整个镜像仓库就不可用。如果团队对可用性要求高可以考虑多实例加共享存储或者用对象存储做 blob store 后端。不过对大多数中小团队来说单实例加定期备份已经够用没必要过度设计。我在实际运维这个仓库的过程中最大的体会是前期把数据持久化和权限这两块做扎实后面基本不用怎么操心。真正容易出问题的往往是那些看起来不起眼的细节比如目录权限、内存参数、清理任务这些地方多花十分钟确认能省下后面几小时的排查时间。
