镜像仓库使用指南

1. 镜像仓库使用指南

1.1 步骤 1: 登录共绩算力镜像站

1. 访问控制台的 https://console.suanli.cn/serverless/image 页面
2. 点击”凭证”
3. 初始化镜像仓库
4. 按照页面上的登录指引操作（运行命令->输入密码）

针对 Windows 和 Mac 系统的终端操作指南：

1.1.1 Windows 系统操作步骤

第一步：打开终端 按下 Win + S 搜索 PowerShell 或 CMD，右键选择 “以管理员身份运行”（避免权限问题）

第二步：执行登录命令 (复制凭证中的登录镜像仓库命令) docker login harborpush.suanleme.cn --username=XXX（换成用户所对应的仓库名称）

系统会提示输入密码： Password:#输入你的仓库密码（输入时不会显示字符，直接盲输后按回车）

成功提示： Login Succeeded

常见问题：

如果提示 docker command not found：需先安装 Docker Desktop for Windows 并确保服务已启动。

密码错误或过期：通过网页端 “重置密码” 后重试。

---

1.1.2 Mac 系统操作步骤

第一步：打开终端 通过 Spotlight（Command + Space）搜索 终端 并打开

第二步：执行登录命令 docker login harborpush.suanleme.cn --username=XXX（换成用户所对应的仓库名称） 输入密码： Password: # 输入密码（无回显，输完直接按回车） 成功提示： Login Succeeded

常见问题： 如果提示权限不足：在命令前加 sudo（需输入 Mac 用户密码）： sudo docker login harborpush.suanleme.cn --username=huang5876 Docker 未运行：需启动 Docker Desktop for Mac 并等待图标变绿。

---

1.1.3 密码重置指引

1. 访问镜像仓库控制台页面，点击 “重置密码”。
2. 按提示通过邮箱或手机验证身份。
3. 设置新密码后，重新执行登录命令。

---

1.2 步骤 2: 为镜像添加标签

1.2.1 为何需要添加标签？

镜像标签（Tag）相当于镜像的”地址 + 版本标识”，目的是将本地镜像与远程仓库路径绑定。共绩算力镜像站要求镜像名称必须包含完整的仓库地址和账户信息，否则无法识别推送目标。

---

1.2.2 完整操作步骤

第一步：查看本地镜像列表

在终端执行以下命令，确认要推送的本地镜像名称和版本：

查看本地所有的镜像

docker images

非 root 用户使用

sudo docker images

输出示例：

REPOSITORY    TAG       IMAGE ID       CREATED         SIZE
my-image     latest    a1b2c3d4e5f6   2 hours ago     1.2GB

Docker 镜像字段解析：

镜像仓库/名称 (REPOSITORY)

表示镜像的完整来源路径，由仓库地址、账户名和镜像名称组成。例如：

• 公共仓库镜像：my-image（默认从 Docker Hub 拉取，格式为仓库名/镜像名）。
• 私有仓库镜像：harborpush.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 基础层时）。

第二步：执行标签添加命令

命令格式：

docker tag <原镜像名称>:<原标签> harborpush.suanleme.cn/<你的账户>/<镜像名称>:<自定义标签>

参数解释：

• <原镜像名称>:<原标签>：本地已有的镜像名称和标签（如 my-image:latest）
• <你的账户>：登录镜像仓库的账号（需在控制台 [镜像仓库 > 访问凭证] 中确认）
• <镜像名称>：推送到仓库后的镜像名称（可自定义，建议与本地镜像同名）
• <自定义标签>：镜像版本标识（如 v1.0、prod）

---

第三步：具体操作示例

假设你的账户是 huang5876，本地镜像为 my-image:latest，目标标签设为 v1.0：

docker tag my-image:latest harborpush.suanleme.cn/huang5876/my-image:v1.0

验证是否成功：

docker images

输出中应出现新标签的镜像：

REPOSITORY                            TAG       IMAGE ID       CREATED         SIZE
my-image                              latest    a1b2c3d4e5f6   2 hours ago     1.2GB
harborpush.suanleme.cn/huang5876/my-image v1.0      a1b2c3d4e5f6   2 hours ago     1.2GB

---

1.2.3 关键注意事项

1. 账户名必须精确匹配 <你的账户> 必须与镜像仓库控制台中显示的登录账号完全一致（区分大小写）

• 可通过控制台 [镜像仓库 > 访问凭证] 查看确认账号

2. 镜像层级结构规则

• 完整路径格式：harborpush.suanleme.cn/<账户>/<项目>/<镜像名>:<标签>

如果仓库有项目层级（如团队协作），需包含项目名：

例如：docker tag my-image harborpush.suanleme.cn/huang5876/project-a/my-image:v1.0

3. 标签命名建议 - 使用语义化版本（如 v1.0.2）

• 避免使用默认的latest 标签（易导致版本混乱）
• 可包含环境标识（如 dev、prod）

---

1.2.4 常见问题排查

• 错误提示 “Repository does not exist” ➠ 检查账户名是否拼写错误 ➠ 确认仓库中是否已手动创建对应项目（部分平台需先创建仓库目录）
• 镜像列表未显示新标签 ➠ 确保 docker tag 命令参数顺序正确 ➠ 验证原镜像是否存在（通过 docker images）
• 推送时提示权限不足 ➠ 重新执行 docker login确保登录状态 ➠ 检查账户是否有该仓库路径的写入权限

---

1.3 步骤 3: 推送镜像

标签添加完成后，使用以下命令推送镜像：

docker push harborpush.suanleme.cn/<your-account>/my-image:my-tag

参数解释：docker push harborpush.suanleme.cn/<your-account>/my-image:my-tag

• harborpush.suanleme.cn 镜像仓库的域名地址，指向共绩算力平台的私有镜像仓库存储服务。
• <your-account> 你的仓库账号（需替换为实际账号）。 ➠ 通过控制台 [镜像仓库 > 访问凭证] 查看确认账号名称（区分大小写）。
• my-image 推送到仓库后的镜像名称，支持以下两种形式：
  • 直接命名：与本地镜像同名（如 my-image）
  • 层级命名：包含项目/分类（如 project-a/my-image，需提前在仓库创建对应目录）
• my-tag 镜像的版本标签，用于标识不同版本或环境：
  • 示例：v1.0（语义化版本）、prod（生产环境）、20251001（日期版本）
  • 避免使用默认的 latest 标签（易导致版本混乱）。

在推送过程中，会显示上传进度。当推送成功后，可以在“镜像仓库”页面查看该镜像。如果镜像过大，那么推送所需时间可能会比较长。

---