私有 Docker 仓库怎么用：从安装到登录、推送和证书

docker push 报 denied，或 docker pull 报 x509——多半不是镜像坏了，而是私服还没接对：服务没起来、仓库类型不对、没 login，或主机名指错了。

下面用 AngusRepo 社区版私有化部署，按操作顺序走完一遍：安装 → 建仓与令牌 → 登录 → 推送 → 拉取（含 CI / Kubernetes）。命令里的主机写成 repo.example.com，换成你的域名即可。denied 逐步拆解见 push denied 排查。

1. 安装（得到可打开的控制台）

前提：Docker Engine + Compose v2；约 2 核 / 4 GB；放行 80；gm.example.com 与 repo.example.com 已解析到本机（试用可写 /etc/hosts）。完整步骤见 第一次跑通。

curl --fail --location --progress-bar -o AngusRepo-Community-1.0.0.zip \
  https://repo.anguskit.com/raw/raw-public/AngusKit/repo/AngusRepo-Community-1.0.0.zip
unzip AngusRepo-Community-1.0.0.zip
cd AngusRepo-1.0.0
./install.sh

向导与快速开始对齐：Compose；Access 选 2（捆绑反代）；TLS 选 4（HTTP :80）；Database 选 Compose 内 MySQL；Public DNS name 填后缀如 example.com。出现 Install finished. 后：

./bin/angusctl.sh doctor   # 看到 doctor: OK

浏览器打开 http://gm.example.com/ 登录，再打开 http://repo.example.com/。

Windows 用 curl.exe + .\install.bat。需要 HTTPS 时见 安装与部署。

下文默认 HTTP 私有化：开发机 Docker 通常要配 insecure-registries。控制台能打开后，先建仓库和令牌，再执行 docker login。

2. 建仓、令牌与镜像命名

推送只能进 HOSTED；PROXY、GROUP 只读。在 http://repo.example.com/ 创建（名称可自定，后面命令保持一致）：

镜像写成 主机/仓库名/镜像:标签，例如 repo.example.com/docker-hosted/myapp:1.0.0。

不要手写 /v2。经 PROXY/GROUP 拉 Docker Hub 官方镜像时加上 library/（如 …/library/nginx:1.27）。

具体 URL 以控制台「接入配置」为准；独立端口等见 Docker 格式手册。

同一控制台继续准备：

• [ ] 创建访问令牌（只显示一次，立刻保存）
• [ ] 推送账号对 docker-hosted 有 Write；拉取账号对入口仓有 Read

export REPO_USER="admin"              # 控制台用户名，不是令牌名称
export REPO_TOKEN="your_access_token" # 密码位一律填令牌
export REPO_HOST="repo.example.com"   # 换成你的 repo.<域名>

3. 登录和证书

HTTP（与快速开始一致）

无证书时 Docker 默认走 HTTPS，会失败。在守护进程加上不安全仓库后重启：

{
   
  "insecure-registries": ["repo.example.com"]
}

然后登录：

echo "$REPO_TOKEN" | docker login "$REPO_HOST" \
  --username "$REPO_USER" \
  --password-stdin

用 --password-stdin，避免令牌进 shell 历史。

改成 HTTPS 之后

配好可信证书后，从 insecure-registries 去掉该主机，再重新 docker login。证书链不完整时仍会出现 x509: certificate signed by unknown authority。

4. 推送内部镜像

docker build -t myapp:1.0.0 .

docker tag myapp:1.0.0 "$REPO_HOST/docker-hosted/myapp:1.0.0"
docker push "$REPO_HOST/docker-hosted/myapp:1.0.0"

目标必须是 HOSTED。往 GROUP 或 PROXY 推，会得到 denied。

CI 里同样三步即可：

echo "$REPO_TOKEN" | docker login "$REPO_HOST" \
  --username "$REPO_USER" --password-stdin
docker build -t "$REPO_HOST/docker-hosted/myapp:$VERSION" .
docker push "$REPO_HOST/docker-hosted/myapp:$VERSION"

流水线阶段编排可另见 Jenkins 构建测试发布。推送被拒逐步查：push denied。

5. 拉取镜像

# 内部镜像
docker pull "$REPO_HOST/docker-hosted/myapp:1.0.0"

# 经 PROXY 拉公共基础镜像（注意 library/）
docker pull "$REPO_HOST/dockerhub-proxy/library/nginx:1.27"

# 若建了 GROUP，可统一从一个入口拉
docker pull "$REPO_HOST/docker-group/myapp:1.0.0"
docker pull "$REPO_HOST/docker-group/library/nginx:1.27"

Kubernetes

节点要能解析 REPO_HOST。HTTP 私服时，节点上的 Docker / containerd 也需信任该仓库（与 insecure-registries 同类配置）。

kubectl create secret docker-registry repo-cred \
  --docker-server="$REPO_HOST" \
  --docker-username="$REPO_USER" \
  --docker-password="$REPO_TOKEN" \
  --namespace=default

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      imagePullSecrets:
        - name: repo-cred
      containers:
        - name: myapp
          image: repo.example.com/docker-hosted/myapp:1.0.0

6. 日常维护（推拉跑通之后）

清理 tag — 镜像体积涨得快。建议每镜像保留最近 N 个 tag，并按名称清掉 *-dev、pr-*。先 Dry Run 再执行，见 清理策略。

PROXY 与限流 — Docker Hub 匿名拉取约 100 次/6h。给 dockerhub-proxy 配 Hub 账号；生产镜像钉死版本号，少用 latest（缓存后不会自动跟着上游变）。

入库检查 — 上传时有轻量门禁；需要更细的漏洞 / 许可证分析时再接外部扫描或安全产品。打开阻断前先处理误报，避免拦停正常拉取。概念见 入库门禁与 SBOM。

报错速查

字段级说明见 Docker / OCI 格式手册。

FAQ

能不能往 GROUP 里 push？

不能。GROUP / PROXY 只读，推送必须指向 HOSTED。

镜像名要不要写 /v2？

不要。客户端会自己走协议路径；写进镜像名会路径错误。

HTTP 环境必须配 insecure-registries 吗？

是。无证书时 Docker 默认 HTTPS，不配往往直接 x509 或握手失败。上了可信证书后应去掉该项。

小结

• 安装并打开控制台 → 建 HOSTED（必选）、PROXY、可选 GROUP → 发令牌。
• docker login 后只向 HOSTED 推送；拉取可走 HOSTED、PROXY 或 GROUP。
• HTTP 试用配 insecure-registries；HTTPS 后去掉；镜像名不要手写 /v2。
• 跑通后配清理策略和 PROXY 凭据，避免磁盘与 Hub 限流拖垮构建。

参考文章

• 第一次跑通
• 安装与部署
• Docker / OCI 格式
• 清理策略
• docker push denied 排查
• Jenkins 构建测试发布
• 入库门禁与 SBOM