镜像地址的命名结构
镜像地址是「仓库地址/命名空间/仓库名:标签」的三段结构：不带地址前缀默认走 Docker Hub，私有镜像必须写全地址，否则登录、推送与拉取全部对不上。理解这个结构是排查镜像认证与推送失败问题的基础。
基本信息
| 三段式 | 仓库地址加命名空间与仓库名，可带端口与标签 |
|---|---|
| 默认仓库 | 不写地址时走 Docker Hub，官方镜像在 library 命名空间 |
| 私有仓库 | 必须写全地址，登录凭据按仓库分别保存 |
| 标签与摘要 | 标签可被覆盖，摘要指向不可变内容 |
| Harbor 术语 | 其命名空间称为项目，权限按项目授予 |
| 本地查看 | docker image ls 的仓库列就是地址前缀 |
地址组成与示例
| 组成 | 示例 | 说明 |
|---|---|---|
| 仓库地址 | registry.example.com | 不写则默认 Docker Hub |
| 命名空间 | team | 对应团队或项目，用于授权 |
| 仓库名 | myapp | 应用名称 |
| 标签 | 1.2.3 | 可覆盖，按发布版本管理 |
| 摘要 | sha256 开头 | 内容寻址，完全可复现 |
推送流程
推送流程
docker tag myapp:1.2.3 registry.example.com/team/myapp:1.2.3 # 按目标地址打标签
docker login registry.example.com # 登录对应仓库
docker push registry.example.com/team/myapp:1.2.3 # 推送
docker pull registry.example.com/team/myapp@sha256:<摘要> # 按摘要拉取典型使用场景
- 私有仓库镜像地址必须写全，团队协作时统一命名规范
- 按团队划分命名空间，权限授予到命名空间即可覆盖
- 生产部署用摘要固定版本，避免标签被覆盖导致行为漂移
- 排查推送失败时先确认地址前缀与登录的仓库是否一致
镜像名采用仓库、项目、应用加版本的结构便于权限控制：项目对应团队，最小权限策略就能覆盖，审计范围也清晰。
标签是可变的，同名标签被重新推送后内容会变；需要严格可复现的部署请用摘要引用，这在排查本地能跑线上不行时差别很大。
私有镜像不写仓库地址会推到 Docker Hub，既白费功夫，又可能把内部代码暴露到公开仓库。