ghcr.io（GitHub Container Registry，GHCR）完整介绍

GHCR = GitHub 官方容器镜像仓库，域名 ghcr.io，属于 GitHub Packages 的一部分，用来存放 OCI / Docker 容器镜像，替代旧版 docker.pkg.github.com。

镜像地址格式：ghcr.io/用户名/组织名/镜像名:标签
示例：ghcr.io/nginx/nginx:1.25

✅ 核心特性

OCI 标准兼容

支持 Docker V2 镜像、OCI 镜像/制品，Podman、containerd、skopeo 都可以正常使用；还支持多架构镜像（amd64/arm64）、镜像签名、SBOM、漏洞扫描。

权限模型（最大亮点）

镜像归属在个人账号 / Organization 组织级别，不再强制绑定单个代码仓库：

可以私有代码仓库，镜像对外公开；也可以代码公开，镜像私有（权限解耦）
可以继承仓库权限，也可以独立设置包权限，支持团队细粒度授权
公开镜像匿名拉取，不需要登录（这点和老的 docker.pkg.github.com 不一样）

和 GitHub Actions 深度集成

CI/CD 流水线内置 GITHUB_TOKEN，不需要手动维护静态密钥，流水线内直接登录、构建、推送镜像，是 GitHub 项目最主流的镜像方案。

计费规则（2026）
公开镜像：存储、流量全部免费，无拉取次数限制（对比 Docker Hub 每6小时200次拉取限制，非常适合CI）
私有镜像：Free 计划提供 500MB 免费存储；超出部分按量计费：$0.25/GB/月 存储 + 出站流量费用

注意：未打 tag（untagged）的镜像默认90天后自动删除；带tag镜像永久保留，可手动配置保留策略

📝 基础使用命令

1. 登录 ghcr.io（本地电脑，使用 Classic PAT）

先在 GitHub 创建 Classic PAT，勾选权限：write:packages read:packages delete:packages

# PAT 放到环境变量
export CR_PAT="你的token"
# 登录 ghcr.io
echo $CR_PAT | docker login ghcr.io -u GitHub用户名 --password-stdin

2. 打标签 & 推送镜像

# 给本地镜像打 ghcr 标签
docker tag myapp:v1 ghcr.io/yourname/myapp:v1
# 推送到 ghcr
docker push ghcr.io/yourname/myapp:v1

3. 拉取镜像

# 公开镜像，匿名直接拉
docker pull ghcr.io/yourname/myapp:v1
# 私有镜像：需要登录 PAT 后拉取

GitHub Actions 流水线最简示例（build & push）

- name: Login to GHCR
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- name: Build and push
  uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: ghcr.io/${{ github.repository_owner }}/myapp:${{ github.sha }}

✅ 优点

公开镜像无拉取限速，CI/CD 批量构建不会被限流，开源项目首选
与 GitHub 代码、PR、Dependabot、漏洞扫描打通，镜像可关联源码
权限灵活：镜像和仓库权限独立；支持组织、团队权限管理
原生支持 OCI 制品：镜像、SBOM、签名、Helm Chart 都可以存
多架构镜像原生支持，Buildx 无缝推送

⚠️ 缺点与坑点

国内访问不稳定：ghcr.io 在国内直连经常超时、拉取慢，一般需要代理/镜像中转
免费私有存储额度很小（500MB），大镜像容易超限产生费用
Web UI 简陋，镜像浏览能力弱，不像 Docker Hub 有丰富的镜像详情页
私有镜像删除、垃圾回收需要手动配置，不带 tag 的镜像90天自动清理，容易丢失历史层
认证：本地操作需要 Classic PAT（fine-grained token 也支持packages权限），K8s 拉私有镜像需要把 PAT 放到 Secret

🆚 GHCR vs Docker Hub

项目	ghcr.io	Docker Hub
公开镜像拉取限制	无次数限制	免费账号6h最多200次拉取
权限	镜像归属组织/个人，可与代码仓库解耦	镜像归属组织，仓库与包绑定更强
CI集成	GitHub Actions原生GITHUB_TOKEN	需要单独维护docker密钥
私有免费额度	500MB	1个私有仓库无限镜像
生态	适合GitHub项目	镜像数量最多，通用生态

🧩 适用场景

✅ 推荐：开源项目、GitHub Actions CI/CD、GitHub 团队内部容器镜像
❌ 不推荐：国内集群直接拉取（网络问题）、大规模私有镜像仓库（成本不如阿里云ACR/腾讯TCR）

常见问题

403 forbidden：PAT 权限不足，缺少 write:packages；或者Actions没有包权限
404 not found：镜像私有，未登录；或者镜像命名大小写错误（ghcr.io大小写敏感）
国内拉取失败：需要镜像中转（如使用阿里云镜像同步，或者配置代理）

如果你需要，我可以给你一份：

K8s 拉取 ghcr.io 私有镜像 Secret 配置模板
自动清理 ghcr.io 旧镜像的 GitHub Action 脚本
国内 ghcr.io 镜像中转同步方案

需要哪个？