镜像仓库
镜像仓库使用规范与操作指南
服务选择建议
阿里云容器镜像服务(ACR)
- 功能特性:支持镜像托管、安全扫描、多地域分发,提供企业版与默认实例版,企业版适用于大规模多地域场景。
- 推荐场景:生产环境建议使用企业版,同时也提供免费版。
- 服务地址:https://www.aliyun.com/product/acr
我们提供的暂时免费的镜像仓库
- 适用场景:临时测试或小规模使用,需注意账号独立(与主账号密码不互通)。
镜像仓库的账号密码和用户的账号密码不互通。
我们提供的暂时免费的镜像仓库使用指南
步骤 1: 登录共绩算力镜像站
- 访问控制台的 https://console.suanli.cn/serverless/image 页面
- 点击"凭证"
- 按照页面上的登录指引操作(运行命令->输入密码)
凭证的核心作用:
- 身份验证 凭证相当于平台访问的"数字钥匙",用于验证用户身份,确保只有授权用户才能访问私有镜像库。
- 权限控制 通过凭证关联账户权限,控制用户对镜像资源的拉取(pull)、推送(push)等操作。
- 安全通信 加密客户端与镜像站之间的数据传输,防止敏感信息泄露。

针对 Windows 和 Mac 系统的终端操作指南:
Windows 系统操作步骤
第一步:打开终端 按下 Win + S
搜索 PowerShell
或 CMD
,右键选择 “以管理员身份运行”(避免权限问题)
第二步:执行登录命令 (复制凭证中的登录镜像仓库命令) docker login harbor.suanleme.cn --username=XXX(换成用户所对应的仓库名称)
系统会提示输入密码:
Password:#输入你的仓库密码(输入时不会显示字符,直接盲输后按回车)
成功提示:
Login Succeeded
常见问题:
如果提示 docker command not found
:需先安装 Docker Desktop for Windows 并确保服务已启动。
密码错误或过期:通过网页端 "重置密码" 后重试。
Mac 系统操作步骤
第一步:打开终端 通过 Spotlight
(Command + Space
)搜索 终端
并打开
第二步:执行登录命令 docker login harbor.suanleme.cn --username=XXX(换成用户所对应的仓库名称)
输入密码: Password: # 输入密码(无回显,输完直接按回车)
成功提示: Login Succeeded
常见问题:
如果提示权限不足:在命令前加 sudo
(需输入 Mac 用户密码):sudo docker login harbor.suanleme.cn --username=huang5876
Docker 未运行:需启动 Docker Desktop for Mac 并等待图标变绿。
密码重置指引
- 访问镜像仓库控制台页面,点击 "重置密码"。
- 按提示通过邮箱或手机验证身份。
- 设置新密码后,重新执行登录命令。
步骤 2: 为镜像添加标签
为何需要添加标签?
镜像标签(Tag)相当于镜像的"地址 + 版本标识",目的是将本地镜像与远程仓库路径绑定。共绩算力镜像站要求镜像名称必须包含完整的仓库地址和账户信息,否则无法识别推送目标。
完整操作步骤
1. 查看本地镜像列表
在终端执行以下命令,确认要推送的本地镜像名称和版本:
查看本地所有的镜像
<em>#查看本地所有的镜像</em>
docker images
非 root 用户使用
<em>#查看本地所有的镜像</em>
sudo docker images
输出示例:
REPOSITORY TAG IMAGE ID CREATED SIZE
my-image latest a1b2c3d4e5f6 2 hours ago 1.2GB
Docker 镜像字段解析:
镜像仓库/名称 (REPOSITORY)
表示镜像的完整来源路径,由仓库地址、账户名和镜像名称组成。例如:
- 公共仓库镜像:
my-image
(默认从 Docker Hub 拉取,格式为仓库名/镜像名
)。 - 私有仓库镜像:
harbor.suanleme.cn/huang5876/my-app
(需包含仓库域名、账户名及镜像名)。
标签 (TAG)
用于标识镜像版本,支持自定义语义化命名规则:
latest
是默认标签,通常指向最新构建的镜像(生产环境慎用)。v1.2.0
是推荐的自定义标签,可通过版本号区分不同功能阶段的镜像(如开发版、稳定版)。
镜像唯一 ID (IMAGE ID) 由镜像内容生成的哈希值,是镜像的唯一标识符。实际显示为完整 64 位 ID 的前 12 位(例如 a1b2c3d4e5f
),可通过 docker inspect
命令查看完整 ID。
创建时间 (CREATED) 记录镜像的构建时间,格式为可读的相对时间(如 2 weeks ago
)。此时间不随镜像更新而改变,可用于判断镜像版本的新旧程度。
镜像大小 (SIZE) 表示镜像的虚拟存储空间,包含所有分层文件的总和。由于 Docker 采用分层存储机制,不同镜像可能共享基础层,因此实际磁盘占用通常小于各镜像 SIZE 的累加值(例如多个镜像共享同一 Ubuntu
基础层时)。
2. 执行标签添加命令
命令格式:
docker tag <原镜像名称>:<原标签> harbor.suanleme.cn/<你的账户>/<镜像名称>:<自定义标签>
参数解释:
<原镜像名称>:<原标签>
:本地已有的镜像名称和标签(如my-image:latest
)<你的账户>
:登录镜像仓库的账号(需在控制台 [镜像仓库 > 访问凭证] 中确认)<镜像名称>
:推送到仓库后的镜像名称(可自定义,建议与本地镜像同名)<自定义标签>
:镜像版本标识(如v1.0
、prod
)
3. 具体操作示例
假设你的账户是 huang5876
,本地镜像为 my-image:latest
,目标标签设为 v1.0
:
docker tag my-image:latest harbor.suanleme.cn/huang5876/my-image:v1.0
验证是否成功:
docker images
输出中应出现新标签的镜像:
REPOSITORY TAG IMAGE ID CREATED SIZE
my-image latest a1b2c3d4e5f6 2 hours ago 1.2GB
harbor.suanleme.cn/huang5876/my-image v1.0 a1b2c3d4e5f6 2 hours ago 1.2GB
4.关键注意事项
- 账户名必须精确匹配
<你的账户>
必须与镜像仓库控制台中显示的登录账号完全一致(区分大小写)
- 可通过控制台 [镜像仓库 > 访问凭证] 查看确认账号
- 镜像层级结构规则
- 完整路径格式:
harbor.suanleme.cn/<账户>/<项目>/<镜像名>:<标签>
如果仓库有项目层级(如团队协作),需包含项目名:
例如:docker tag my-image harbor.suanleme.cn/huang5876/project-a/my-image:v1.0
- 标签命名建议 - 使用语义化版本(如
v1.0.2
)
- 避免使用默认的
latest
标签(易导致版本混乱) - 可包含环境标识(如
dev
、prod
)
5.常见问题排查
- 错误提示 "Repository does not exist" ➠ 检查账户名是否拼写错误 ➠ 确认仓库中是否已手动创建对应项目(部分平台需先创建仓库目录)
- 镜像列表未显示新标签 ➠ 确保
docker tag
命令参数顺序正确 ➠ 验证原镜像是否存在(通过docker images
) - 推送时提示权限不足 ➠ 重新执行
docker login
确保登录状态 ➠ 检查账户是否有该仓库路径的写入权限
步骤 3: 推送镜像
标签添加完成后,使用以下命令推送镜像:
docker push harbor.suanleme.cn/<your-account>/my-image:my-tag
参数解释:docker push harbor.suanleme.cn/<your-account>/my-image:my-tag
harbor.suanleme.cn
镜像仓库的域名地址,指向共绩算力平台的私有镜像仓库存储服务。<your-account>
你的仓库账号(需替换为实际账号)。 ➠ 通过控制台 [镜像仓库 > 访问凭证] 查看确认账号名称(区分大小写)。my-image
推送到仓库后的镜像名称,支持以下两种形式:- 直接命名:与本地镜像同名(如
my-image
) - 层级命名:包含项目/分类(如
project-a/my-image
,需提前在仓库创建对应目录)
- 直接命名:与本地镜像同名(如
my-tag
镜像的版本标签,用于标识不同版本或环境:- 示例:
v1.0
(语义化版本)、prod
(生产环境)、20251001
(日期版本) - 避免使用默认的
latest
标签(易导致版本混乱)。
- 示例:
在推送过程中,会显示上传进度。当推送成功后,可以在“镜像仓库”页面查看该镜像。如果镜像过大,那么推送所需时间可能会比较长。

阿里云容器镜像服务(ACR)使用指南
一、服务准备与实例选择
实例类型选择
- 企业版:适用于生产环境,支持多地域分发、安全扫描、镜像加签、全球同步加速、P2P 分发等功能,提供 99.95% SLA 保障。推荐选择标准版或高级版以支持交付链与大规模分发。
- 个人版:仅限测试或小规模使用,无 SLA 保障,功能受限(如不支持 Helm Chart 管理)。
创建实例
- 操作路径:登录容器镜像服务 ACR,选择地域后创建实例,需配置实例名称、存储类型(默认 OSS 或自定义 Bucket)、安全扫描引擎(Trivy 或云安全引擎)及资源配额。
- 注意事项:
- 企业版需绑定 OSS 服务并设置 VPC 访问控制配额。
- 命名空间与仓库数量受配额限制,建议按团队或项目划分命名空间。
企业版:容器镜像服务
二、镜像仓库配置
官方教程:阿里云【试用教程】在 Dockerfile 中使用构建打包镜像并运行
- 命名空间与仓库创建
- 命名空间:逻辑隔离单元,建议按组织命名(如
dev-team
),一个账号最多创建 3 个(个人版)或更多(企业版)。 - 镜像仓库: 创建步骤:在控制台选择命名空间后,填写仓库名称、类型(私有/公开)、代码源(本地仓库或 Git 平台),并配置构建设置(自动构建、缓存策略)。
- 命名规范:需包含完整路径(如
registry.cn-hangzhou.aliyuncs.com/<命名空间>/<仓库名>:<标签>
),标签建议使用语义化版本(如v1.0-prod
)。
- 命名空间:逻辑隔离单元,建议按组织命名(如
- 访问控制
- 公网/VPC 访问:企业版需在控制台开启公网入口并配置白名单,或通过专有网络实现内网加速。
- 权限管理:通过 RAM 子账号授权,区分命名空间管理员(全权限)、普通成员(读写)和只读用户。
三、镜像操作指南
- 登录凭证配置
- 凭证类型:支持阿里云账号 AccessKey 或临时密码,企业版需在控制台[访问凭证]页面设置固定密码。

- 登录命令:
docker login --username=<账号名> registry.<region>.aliyuncs.com
输入密码后显示 Login Succeeded
即为成功。
- 镜像推送与拉取
- 标签与推送:
docker tag <本地镜像> registry.cn-hangzhou.aliyuncs.com/<命名空间>/<仓库名>:<标签>
docker push registry.cn-hangzhou.aliyuncs.com/<命名空间>/<仓库名>:<标签>
- 拉取镜像:
docker pull registry.cn-hangzhou.aliyuncs.com/<命名空间>/<仓库名>:<标签>
- 注意事项:企业版实例名称需替换为
企业版实例名称-region.cr.aliyuncs.com
。
- 多架构镜像构建
- 适用场景:需支持 x86、ARM 等不同架构。
- 操作步骤:
- 在代码仓库配置多架构构建规则(如
linux/amd64
和linux/arm64
)。 - 触发构建后,同一标签将包含多架构镜像,客户端自动拉取适配版本。
- 在代码仓库配置多架构构建规则(如
四、高级功能与优化
镜像加速器配置
- 作用:加速 Docker Hub 官方镜像拉取,需在
/etc/docker/daemon.json
中添加加速器地址(如https://<加速器地址>.mirror.aliyuncs.com
)并重启 Docker 服务。 - 限制:仅限阿里云公网产品使用,无法保证拉取最新版本,建议指定镜像版本。
- 作用:加速 Docker Hub 官方镜像拉取,需在
安全与合规
- 安全扫描:企业版支持自动扫描漏洞(CVE、恶意代码),并生成修复建议。
- 镜像加签:通过密钥对镜像签名,防止篡改,可配置自动加签规则。
- 操作审计:记录所有镜像操作日志,便于追溯与合规审查。
全球分发与同步
- 多地域复制:企业版支持一键同步镜像至全球地域,通过内网专线降低延迟。
- P2P 加速:千节点级分发时启用 P2P 技术,提升效率 4 倍以上。
生命周期管理
- 自动清理策略:设置保留规则(如保留最近 10 个版本),自动清理旧镜像释放存储空间。
- 交付链集成:高级版支持构建→扫描→加签→分发的自动化流水线,减少人工干预。
五、常见问题与排查
问题现象:unauthorized 或权限不足
- 原因:Docker 客户端未携带有效身份凭证,或用户对目标仓库无操作权限。
- 解决方案:
- 执行
docker logout
退出当前登录状态,重新运行docker login
输入账户密码。 - 若使用私有仓库,需在登录时指定仓库地址(如
docker login harbor.example.com
)。 - 检查账户是否被移出仓库权限组,联系管理员确认访问权限。
- 执行
问题现象:推送失败(Repository does not exist)
- 原因:镜像名称中的命名空间或仓库路径不符合仓库规则,或目标仓库尚未创建。
- 解决方案:
- 镜像名称需严格遵循
仓库域名/命名空间/仓库名:标签
格式(如harbor.com/dev-team/myapp:v1
)。 - 通过仓库管理界面手动创建同名仓库目录(部分私有仓库要求先创建空仓库)。
- 确认账户对目标仓库有
push
权限(权限不足时会伪装为“仓库不存在”错误)。
- 镜像名称需严格遵循
问题现象:镜像拉取超时
- 原因:网络连接不稳定或跨国访问公共仓库速度受限。
- 解决方案:
- 配置镜像加速器:
- 修改 Docker 配置文件
/etc/docker/daemon.json
,添加国内镜像源(如阿里云、腾讯云镜像加速地址)。 - 执行
systemctl reload docker
重启服务生效。
- 修改 Docker 配置文件
- 启用企业版加速功能:
- 私有化部署仓库(如 Harbor)可开启 P2P 分发或全球节点同步功能。
- 临时切换网络环境测试(如从公司内网切换至公网)。
- 配置镜像加速器:
问题现象:安全扫描报错
- 原因:镜像包含高危漏洞或依赖项版本过低。
- 解决方案:
- 使用
docker scan 镜像名
运行安全扫描,查看具体漏洞详情。 - 升级 Dockerfile 中
FROM
指定的基础镜像版本(如FROM alpine:3.19
替代alpine:3.10
)。 - 使用阿里云容器镜像服务提供的「安全镜像」,自动集成漏洞修复补丁。
- 在 CI/CD 流程中集成 Trivy 或 Clair 漏洞扫描工具,阻断不安全镜像流入生产环境。
- 使用
六、最佳实践建议
生产环境规范:
- 使用企业版并启用安全扫描、加签与访问控制。
- 避免使用
latest
标签,采用语义化版本管理。
性能优化:
- 内网推送使用 VPC 域名(如
registry-vpc.cn-hangzhou.aliyuncs.com
)以提升速度。 - 大镜像(如 AI 模型)启用按需加载功能,减少启动时间 60%。
- 内网推送使用 VPC 域名(如
通过以上步骤,可高效利用 ACR 实现镜像全生命周期管理,兼顾安全性与运维效率。如需进一步探索 API 集成或自定义认证,可参考ACR 官方文档。