GHCR 是什么？GitHub 容器镜像仓库技术介绍

1. GHCR 是什么

GHCR 全称是 GitHub Container Registry ，也就是 GitHub 容器镜像仓库。

它的地址是：

bash 复制代码

ghcr.io

GHCR 可以理解为：

复制代码

GitHub 官方提供的 Docker 镜像仓库

它主要用来：

复制代码

保存 GitHub Actions 构建出来的 Docker 镜像
让服务器可以通过 docker pull 拉取镜像
支持版本管理、权限控制和自动化部署

在完整 CI/CD 流程中，它的位置是：

复制代码

GitHub 代码仓库
  ↓
GitHub Actions 自动构建
  ↓
GHCR 保存镜像
  ↓
服务器拉取镜像
  ↓
Docker / Docker Compose 启动服务

对于实际项目部署场景，GHCR 的意义是：

复制代码

以后前端、后端代码推送到指定分支后，
GitHub Actions 自动打包成镜像，
镜像放到 ghcr.io，
服务器只需要拉取镜像并重启容器，
不需要在服务器上重新编译项目。

一句话概括：

GitHub 存代码，GHCR 存镜像，服务器运行镜像。

通俗说，GHCR 就是 GitHub 提供的一个 Docker 镜像仓库，类似于：

镜像仓库	说明
Docker Hub	常见的公共 Docker 镜像仓库
GHCR	GitHub 官方的容器镜像仓库
阿里云 ACR	阿里云容器镜像服务
腾讯云 TCR	腾讯云容器镜像服务

GitHub 官方文档说明，Container registry 使用 ghcr.io，可以用来存储和分发容器镜像，并且支持更细粒度的权限控制。GitHub 旧的 Docker registry docker.pkg.github.com 已经被 Container registry 替代。

2. GHCR 解决什么问题

假设有一个前端项目或者后端项目，需要用 Docker 部署。

正常流程是：

复制代码

写代码
  ↓
提交到 GitHub
  ↓
GitHub Actions 自动构建 Docker 镜像
  ↓
把镜像推送到 GHCR
  ↓
服务器 docker pull 拉取镜像
  ↓
docker run / docker compose 启动服务

GHCR 在这里扮演的角色就是：

复制代码

存放 Docker 镜像的仓库

它不是运行服务的地方，也不是服务器。它只是帮你保存镜像。

可以类比成：

复制代码

GitHub 仓库：存代码
GHCR：存 Docker 镜像
云服务器：真正运行容器

3. 为什么 GitHub Actions 经常和 GHCR 一起用

因为 GitHub Actions 本身就在 GitHub 上运行，GHCR 也是 GitHub 生态里的镜像仓库。

所以它们配合起来很自然：

复制代码

GitHub Actions 负责自动构建
GHCR 负责保存构建后的镜像
服务器负责拉取镜像并运行

GitHub 官方的 Docker 镜像发布文档也推荐使用 GitHub Actions 构建并发布镜像到 Container registry，也就是 ghcr.io。常见 Action 包括：

复制代码

docker/login-action
docker/setup-buildx-action
docker/build-push-action
docker/metadata-action

比如前端项目可能会构建出这样的镜像：

bash 复制代码

ghcr.io/<github-user-or-org>/<frontend-image-name>:<tag>

后端项目可能会构建出这样的镜像：

bash 复制代码

ghcr.io/<github-user-or-org>/<backend-image-name>:<tag>

服务器部署时，只需要：

bash 复制代码

docker pull ghcr.io/<github-user-or-org>/<frontend-image-name>:<tag>
docker pull ghcr.io/<github-user-or-org>/<backend-image-name>:<tag>

然后再启动容器即可。

4. GHCR 和 GitHub 仓库的关系

很多人容易混淆：

复制代码

GitHub Repository ≠ GHCR Package

它们不是同一个东西。

GitHub Repository

GitHub 仓库保存的是源码，例如：

复制代码

前端代码
后端代码
Dockerfile
docker-compose.yml
GitHub Actions workflow
README.md

GHCR Package

GHCR 保存的是构建后的 Docker 镜像，例如：

复制代码

前端 Nginx 镜像
后端应用镜像
网关镜像
任务服务镜像

二者关系是：

复制代码

代码仓库里面有 Dockerfile
GitHub Actions 根据 Dockerfile 构建镜像
构建完成后推送到 GHCR
GHCR 中产生一个 package

GitHub Packages 支持将 package 关联到仓库，也可以设置 package 的可见性和访问权限。部分 package 支持细粒度权限控制，可以按用户、组织或仓库关联来管理访问。

5. GHCR 的镜像命名规则

GHCR 镜像通常长这样：

bash 复制代码

ghcr.io/<用户名或组织名>/<镜像名>:<标签>

例如：

bash 复制代码

ghcr.io/example-org/example-frontend:prod

拆开看：

部分	含义
`ghcr.io`	GHCR 镜像仓库地址
`example-org`	GitHub 用户名或组织名
`example-frontend`	镜像名称
`prod`	镜像标签 tag

再比如：

bash 复制代码

ghcr.io/example-org/example-backend:latest

其中 latest 是镜像标签，表示默认或者最新版本。

但生产部署时，不建议只依赖 latest，最好使用明确标签，例如：

复制代码

prod
v1.0.0
20260529
sha-xxxxxxx

这样可以更方便地定位版本，也方便后续回滚。

6. GHCR 的权限问题

GHCR 镜像可以是：

类型	说明
Public	公开镜像，别人可以直接拉取
Private	私有镜像，需要登录和授权才能拉取
Internal	组织内部可见，常见于企业或组织场景

如果是公开镜像，服务器上可以直接：

bash 复制代码

docker pull ghcr.io/<owner>/<image>:<tag>

如果是私有镜像，服务器需要先登录：

bash 复制代码

docker login ghcr.io

然后输入 GitHub 用户名和 Token。

GitHub 文档说明，访问私有、内部或公开 package 的发布、安装、删除等操作通常需要访问令牌。对于 Container registry，可以使用 personal access token classic 认证。

常见权限大概是：

操作	需要什么权限
拉取公开镜像	通常不需要登录
拉取私有镜像	需要 token
推送镜像	需要写 package 权限
删除镜像	需要更高权限
GitHub Actions 推送	通常用 `GITHUB_TOKEN`

7. GHCR 在 GitHub Actions 里的典型流程

一个典型的 GitHub Actions 构建流程是：

复制代码

1. checkout 拉取代码
2. setup-buildx 初始化 Docker Buildx
3. login-action 登录 ghcr.io
4. metadata-action 生成镜像标签
5. build-push-action 构建并推送镜像

workflow 里一般会看到类似这些配置：

yaml 复制代码

permissions:
  contents: read
  packages: write

这表示：

权限	作用
`contents: read`	允许 Actions 读取仓库代码
`packages: write`	允许 Actions 把镜像推送到 GHCR

然后登录 GHCR：

yaml 复制代码

registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

这里的意思是：

复制代码

用当前触发 Actions 的 GitHub 用户身份，
配合 GITHUB_TOKEN 登录 GHCR。

GitHub 官方文档中也提到，可以在 Actions 中使用 GITHUB_TOKEN 认证到 GitHub Packages，并将容器镜像发布到 ghcr.io。

8. GHCR 和 Docker Hub 的区别

对比项	GHCR	Docker Hub
所属平台	GitHub	Docker
地址	`ghcr.io`	`docker.io`
和 GitHub Actions 集成	非常方便	也可以，但需要配置 Docker Hub token
和 GitHub 仓库关联	原生支持	不如 GHCR 直接
权限控制	和 GitHub 用户、组织、仓库权限结合较好	独立账号权限体系
国内拉取速度	可能不稳定	也可能不稳定
适合场景	GitHub 项目自动构建镜像	通用 Docker 镜像分发

对 GitHub Actions 自动构建项目来说，GHCR 的优势是：

复制代码

代码在 GitHub
构建在 GitHub Actions
镜像也放在 GitHub GHCR
权限和自动化链路都在一个平台里