> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 推送和拉取容器镜像

> 使用 Docker 登录镜像仓库，并推送或拉取容器镜像。

将本地镜像推送到项目后，可以在其他具备访问条件的环境中拉取镜像。

## 操作前确认

* 已有目标地域的镜像仓库项目，且当前账号具备该项目的读写权限。
* 执行命令的环境已安装 Docker。
* 推送镜像时，本地已准备好需要推送的镜像。

## 获取操作命令

* 获取通用登录、推送和拉取的参考命令

  在 **镜像仓库** 页面，单击 **推送 & 拉取**。
* 获取某项目的推送命令

  进入目标项目详情页，在左侧单击 **镜像仓库**，然后单击 **获取推送命令**。
* 获取某镜像的拉取命令

  1. 进入目标项目详情页，在左侧单击 **镜像仓库**。
  2. 找到目标镜像仓库，单击名称。
  3. 在制品列表的 **操作** 列单击 **复制拉取命令**。

## 登录镜像仓库

1. 登录 [GPU 云服务控制台](https://console.siflow.cn/gpu-cloud/home)。
2. 进入 **存储 > 镜像仓库** 页面，选择目标地域。
3. 单击 **推送 & 拉取**。
4. 在 **Docker** 页签获取该地域的仓库地址和登录说明。
5. 在执行镜像操作的环境中登录仓库：

   ```bash theme={null}
   docker login <REGISTRY_ENDPOINT> --username <USERNAME>
   ```

   * `<REGISTRY_ENDPOINT>` 替换为当前地域的仓库地址，例如 `registry-cn-shanghai.siflow.cn`。
   * `<USERNAME>` 替换为镜像仓库登录用户名，格式为 `<用户名>@<租户名>`。
   * 按提示输入对应凭证，默认密码为平台登录密码。

## 推送镜像

登录镜像仓库，为本地镜像添加目标仓库地址、项目路径和标签，并推送到目标项目。

```bash theme={null}
docker tag <LOCAL_IMAGE>:<TAG> <REGISTRY_ENDPOINT>/<PROJECT>/<IMAGE>:<TAG>
docker push <REGISTRY_ENDPOINT>/<PROJECT>/<IMAGE>:<TAG>
```

* `<LOCAL_IMAGE>`：本地镜像。
* `<REGISTRY_ENDPOINT>`：镜像仓库地址。
* `<PROJECT>`：目标项目。
* `<IMAGE>`：目标镜像名称。
* `<TAG>`：镜像标签。

示例：

```bash theme={null}
docker tag myimage:latest registry-cn-shanghai.siflow.cn/project-test/myimage:latest
docker push registry-cn-shanghai.siflow.cn/project-test/myimage:latest
```

推送完成后，在目标地域的 **项目** 页签进入相应项目，然后在 **镜像仓库** 中确认镜像可找到。

## 拉取镜像

在需要使用镜像的环境中登录仓库，然后执行：

```bash theme={null}
docker pull <REGISTRY_ENDPOINT>/<PROJECT>/<IMAGE>:<TAG>
```

* `<REGISTRY_ENDPOINT>`：镜像仓库地址。
* `<PROJECT>`：目标项目。
* `<IMAGE>`：目标镜像名称。
* `<TAG>`：镜像标签。

示例：

```bash theme={null}
docker pull registry-cn-shanghai.siflow.cn/project-test/myimage:latest
```

将示例地址替换为实际仓库地址。拉取失败时，先核对地域、项目路径、镜像名称与标签，以及当前环境使用的凭证是否能够访问该项目。

## 常见问题

> [accordion] 推送镜像时提示 `DENIED: ... exceed the configured upper limit` 怎么办？
>
> 该报错表示目标镜像仓库项目的存储配额不足或已达到上限，镜像仓库拒绝继续写入新的镜像数据。
>
> 这类问题通常不是 Docker 登录状态、镜像标签格式或网络连通性导致的。您可以按以下顺序处理：
>
> 1. 核对镜像地址中的项目名称是否正确，避免把镜像推送到已满额或不符合预期的项目。
> 2. 清理不再需要的镜像版本、标签或其他制品。若项目已配置制品保留策略，建议先试运行并核对影响，再正式执行清理。详情请参见 [配置镜像仓库制品保留策略](https://docs.siflow.cn/gpu-cloud/registry/configure-artifact-retention.md)。
> 3. 如果历史镜像仍需保留，请联系项目管理员调整项目存储配额，或改为推送到有足够配额的项目。
> 4. 释放或调整配额后，重新执行 `docker push`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.