Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

使用容器注册表

可在使用包命名空间 https://containers.HOSTNAME 的 Container registry 中存储和管理 Docker 和 OCI 映像。

注意:GitHub Enterprise Server 的 Container registry 当前为 beta 版本,可能会有变化。

必须启用 GitHub Packages 和子域隔离才能使用 Container registry。 有关详细信息,请参阅“使用容器注册表”。

关于 Container registry

Container registry 将容器映像存储在组织或个人帐户中,并允许你将映像与存储库相关联。 可以选择是从存储库继承权限,还是独立于存储库设置精细权限。 你也可以匿名访问公共容器映像。

若要在 GitHub Enterprise Server 上使用 Container registry,站点管理员必须首先为实例配置 GitHub Packages 并启用子域隔离。 有关详细信息,请参阅“企业 GitHub Packages 使用入门”和“启用子域隔离”。

关于 Container registry 支持

Container registry 目前支持以下容器映像格式:

在安装或发布 Docker 映像时,Container registry 支持外部层,如 Windows 映像。

向 Container registry 验证

需要访问令牌才能发布、安装和删除专用、内部和公共包。

可使用 personal access token 向 GitHub Packages 或 GitHub Enterprise Server API 进行身份验证。 创建 personal access token 时,可根据需要为令牌分配不同的作用域。 有关 personal access token 的包相关范围的详细信息,请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证,您可以使用:

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • 范围至少为 read:packages 的 personal access token,用于安装与其他专用存储库(GITHUB_TOKEN 无法访问)关联的包。

在 GitHub Actions 工作流中进行身份验证

此注册表支持精细权限。 对于支持精细权限的注册表,如果 GitHub Actions 工作流使用 personal access token 向注册表进行身份验证,则强烈建议更新工作流以使用 GITHUB_TOKEN。 有关更新使用 personal access token 对注册表进行身份验证的工作流的指南,请参阅“升级使用 personal access token 访问注册表的工作流”。

有关 GITHUB_TOKEN 的详细信息,请参阅“工作流中的身份验证”。 有关在操作中使用注册表时的最佳做法的详细信息,请参阅“GitHub Actions 的安全强化”。

还可以选择为 GitHub Codespaces 和 GitHub Actions 单独授予对包的访问权限。 有关详细信息,请参阅“确保 Codespace 具有包的访问权限”和“确保工作流具有包的访问权限”。

使用 personal access token 进行身份验证

请确保在以下示例中将 HOSTNAME 替换为 your GitHub Enterprise Server instance 主机名或 IP 地址。

  1. 针对要完成的任务,新创具有适当作用域的 personal access token。 如果您的组织需要 SSO,则必须为新令牌启用 SSO。

    注意:默认情况下,在用户界面中为 personal access token 选择 write:packages 作用域时,repo 作用域也将被选中。 repo 作用域提供了不必要和广泛的访问权限,我们建议你尤其避免将其用于 GitHub Actions 工作流。 有关详细信息,请参阅“GitHub Actions 的安全强化”。 解决方法是在以下 URL 的用户界面中仅为 personal access token 选择 write:packages 作用域:https://HOSTNAME/settings/tokens/new?scopes=write:packages

    • 选择 read:packages 范围以下载容器映像并读取其元数据。
    • 选择 write:packages 范围以下载和上传容器映像并读写其元数据。
    • 选择 delete:packages 范围以删除容器映像。

    有关详细信息,请参阅“为命令行创建 personal access token”。

  2. 保存 personal access token。 建议将令牌保存为环境变量。

    $ export CR_PAT=YOUR_TOKEN
  3. 使用容器类型的 CLI,登录到 containers.HOSTNAME 上的 Container registry 服务。

    $ echo $CR_PAT | docker login containers.HOSTNAME -u USERNAME --password-stdin
    > Login Succeeded

推送容器映像

此示例推送最新版本的 IMAGE_NAME

$ docker push containers.HOSTNAME/OWNER/IMAGE_NAME:latest

此示例推送映像的 2.5 版本。

$ docker push containers.HOSTNAME/OWNER/IMAGE_NAME:2.5

首次发布包时,默认可见性是私有的。 将包链接到存储库时,包可见性取决于存储库的可见性。 若要更改可见性或设置访问权限,请参阅“配置包的访问控制和可见性”。 可以使用用户界面或命令行将已发布的包链接到存储库。 有关详细信息,请参阅“将存储库连接到包”。

拉取容器映像

通过摘要拉取

为确保始终使用相同的映像,可以通过 digest SHA 值指定要拉取的确切容器映像版本。

  1. 若要查找摘要 SHA 值,请使用 docker inspectdocker pull 并在 Digest: 之后复制 SHA 值

    $ docker inspect containers.HOSTNAME/OWNER/IMAGE_NAME
  2. 按需要在本地删除映像。

    $ docker rmi  containers.HOSTNAME/OWNER/IMAGE_NAME:latest
  3. 拉取映像名称后带有 @YOUR_SHA_VALUE 的容器映像。

    $ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

按名称拉取

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME

按名称和版本拉取

显示按名称和 1.14.1 版本标记拉取的映像的 Docker CLI 示例:

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME:1.14.1
  > 5e35bd43cf78: Pull complete
  > 0c48c2209aab: Pull complete
  > fd45dd1aad5a: Pull complete
  > db6eb50c2d36: Pull complete
  > Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
  > Status: Downloaded newer image for containers.HOSTNAME/orgname/image-name/release:1.14.1
  > containers.HOSTNAME/orgname/image-name/release:1.14.1

按名称和最新版本拉取

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME:latest
  > latest: Pulling from user/image-name
  > Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
  > Status: Downloaded newer image for containers.HOSTNAME/user/image-name:latest
  > containers.HOSTNAME/user/image-name:latest

构建容器映像

此示例生成 hello_docker 映像:

$ docker build -t hello_docker .

标记容器映像

  1. 找到要标记的 Docker 映像的 ID。

    $ docker images
    > REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
    > containers.HOSTNAME/my-org/hello_docker         latest              38f737a91f39        47 hours ago        91.7MB
    > containers.HOSTNAME/my-username/hello_docker    latest              38f737a91f39        47 hours ago        91.7MB
    > hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB
  2. 使用映像 ID 以及所需的映像名称和托管目标标记 Docker 映像。

    $ docker tag 38f737a91f39 containers.HOSTNAME/OWNER/NEW_IMAGE_NAME:latest

标记容器映像

可以使用预定义的注释键向容器映像添加元数据,包括说明、许可证和源存储库。 支持的密钥的值将显示在映像的“包”页面中。

对于大多数映像,可以使用 Docker 标签将注释密钥添加到映像。 有关详细信息,请参阅 Docker 官方文档中的“标签”和 opencontainers/image-spec 存储库中的“预定义的注释密钥”。

对于多架构映像,可以通过将适当的注释密钥添加到映像清单中的 annotations 字段来为映像添加说明。 有关详细信息,请参阅“向多架构映像添加说明”。

Container registry 支持以下注释密钥。

密钥说明
org.opencontainers.image.source与包关联的存储库的 URL。 有关详细信息,请参阅“将存储库连接到包”。
org.opencontainers.image.description纯文本说明,限制在 512 个字符以内。 此说明将显示在包页中的包名称下方。
org.opencontainers.image.licensesSPDX 许可证标识符,如“MIT”,限制在 256 个字符以内。 许可证将显示在包页的“详细信息”边栏中。 有关详细信息,请参阅 SPDX 许可证列表

若要添加密钥作为 Docker 标签,建议在 Dockerfile 中使用 LABEL 指令。 例如,如果你是用户 monalisa,拥有 my-repo,并且映像是根据 MIT 许可证的条款分发的,可以在 Dockerfile 中添加以下行:

LABEL org.opencontainers.image.source=https://HOSTNAME/monalisa/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

或者,可以使用 docker build 命令在生成时向映像添加标签。

$ docker build \
 --label "org.opencontainers.image.source=https://HOSTNAME/monalisa/my-repo" \
 --label "org.opencontainers.image.description=My container image" \
 --label "org.opencontainers.image.licenses=MIT"

向多架构映像添加说明

多架构映像是支持多种体系结构的映像。 它的原理是在单一清单中引用一系列映像,其中每个映像都支持不同的体系结构。

多架构映像的“包”页面中的说明是从映像清单中的 annotations 字段获取的。 与 Docker 标签一样,注释提供了一种将元数据与映像相关联的方法,并支持预定义的注释密钥。 有关详细信息,请参阅 opencontainers/image-spec 存储库中的注释

若要为多架构映像提供说明,请在清单的 annotations 字段中为 org.opencontainers.image.description 键设置一个值,如下所示。

"annotations": {
  "org.opencontainers.image.description": "My multi-arch image"
}

例如,以下 GitHub Actions 工作流步骤生成并推送多架构映像。 outputs 参数设置映像的说明。

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。

- name: Build and push Docker image
  uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
  with:
    context: .
    file: ./Dockerfile
    platforms: ${{ matrix.platforms }}
    push: true
    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image