`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`）。完整步骤见 第一次跑通。

```bash
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.` 后：

```bash
./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/` 创建（名称可自定，后面命令保持一致）：

| 仓库名示例 | 类型 | 干什么 |
| --- | --- | --- |
| `docker-hosted` | HOSTED | `docker push` 的唯一目标 |
| `dockerhub-proxy` | PROXY | 缓存 Docker Hub（远程 URL：`https://registry-1.docker.io`；建议配 Hub 账号） |
| `docker-group`（可选） | GROUP | 聚合上面两个，做一个拉取入口 |

![Docker 私服拓扑：开发机 push 到 HOSTED，pull 经可选 GROUP 聚合 HOSTED 与 PROXY](https://developer.qcloudimg.com/http-save/yehe-1099973/b97c4c9341b41f6e3c8ac2b5167ee7ea.png)
镜像写成 `主机/仓库名/镜像:标签`，例如 `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

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

## 3. 登录和证书

### HTTP（与快速开始一致）

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

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

然后登录：

```bash
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`。

| 现象 | 先查什么 |
| --- | --- |
| `x509` / 握手失败 | HTTP 是否漏配 `insecure-registries`；HTTPS 时证书链是否完整 |
| `unauthorized` / `authentication required` | 是否已 login；密码位是否为令牌；主机是否为私服域名 |

## 4. 推送内部镜像

```bash
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 里同样三步即可：

```bash
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. 拉取镜像

```bash
# 内部镜像
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` 同类配置）。

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

```yaml
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。

## 报错速查

| 报错 | 常见原因 | 怎么处理 |
| --- | --- | --- |
| `denied` | 无 Write，或 push 到了 GROUP/PROXY | 改 ACL；只推 HOSTED；见 push denied |
| `manifest unknown` | 仓库名 / 镜像 / tag 错；漏了 `library/` | 核对「接入配置」与命名 |
| pull 大镜像超时 | 反代超时或 body 限制太小 | 调大 `proxy_read_timeout` 与上传大小 |
| 登录成功但 push 401 | 令牌过期，或环境变了没重新 login | 重新 `docker login` |

字段级说明见 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 限流拖垮构建。

## 参考文章

- [第一次跑通](https://www.anguskit.com/zh/docs/repo/get-started/quickstart)
- [安装与部署](https://www.anguskit.com/zh/docs/repo/manual/02-installation)
- [Docker / OCI 格式](https://www.anguskit.com/zh/docs/repo/manual/05-formats/02-docker)
- [清理策略](https://www.anguskit.com/zh/docs/repo/manual/10-cleanup)
- [docker push denied 排查](https://www.anguskit.com/zh/blog/docker-push-denied-troubleshooting)
- [Jenkins 构建测试发布](https://www.anguskit.com/zh/blog/jenkins-pipeline-build-test-publish-artifacts)
- [入库门禁与 SBOM](https://www.anguskit.com/zh/blog/supply-chain-gate-sbom)

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

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

私有化部署后接 Docker：建 HOSTED/PROXY/GROUP，处理 login 与 x509，完成 push、pull、CI 与 Kubernetes 拉取。

数据库

本文详解Docker推送被拒(denied)与拉取报x509错误的排查方法，通过AngusRepo社区版私有化部署，覆盖安装、建仓、令牌登录、推送拉取全流程，并包含CI/Kubernetes集成及报错速查表，解决私服配置问题。

代码解释

Kubernetes

Windows

Docker

MySQL

Nginx

2026上云采购 | AI焕新·智启新局

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

私有 Docker 仓库怎么用：从安装到登录、推送和证书-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐