Harbor Docker 镜像源配置教程（基于轩辕镜像专属域名）

适用于已自建 Harbor 仓库的用户，通过将轩辕镜像专业版专属域名配置为 Harbor 的远程仓库端点，一次性打通 docker.io / ghcr.io / gcr.io / quay.io / nvcr.io 等常见镜像源的加速访问。

1
前期准备：确认轩辕镜像专属域名

在将 Harbor 配置为代理仓库之前，请先在轩辕镜像控制台确认您的各类专属域名（专业版支持免登录拉取），后续将在 Harbor 中直接作为远程仓库的端点 URL 使用：

常见专属域名类型：

主专属域名：例如 ***.xuanyuan.run，用于加速 docker.io 镜像
GHCR 专属域名：例如 ***-ghcr.xuanyuan.run，用于加速 ghcr.io 镜像
GCR 专属域名：例如 ***-gcr.xuanyuan.run，用于加速 gcr.io 镜像
其他仓库专属域名：如 ***-quay.xuanyuan.run （对应 quay.io）、 ***-nvcr.xuanyuan.run （对应 nvcr.io）等

您可以在登录轩辕镜像官网后，进入左侧菜单「专属域名」页面查看上述域名。专业版专属域名支持免登录拉取，无需在 Harbor 中配置任何账号密码，非常适合作为 Harbor 的远程仓库代理端点。

2
在 Harbor 中配置 docker.io 镜像代理

这里以 docker.io 为例，演示如何在 Harbor 中创建一个 Proxy Repository，将主专属域名配置为远程端点。

操作路径：

登录 Harbor 管理后台（平台域名如 harbor.example.com）。
左侧菜单进入 「仓库管理」→「远程仓库」。
点击右上角「新建远程仓库」，按照下表填写关键字段。

字段	推荐填写
远程仓库类型	Proxy Repository
仓库名称	建议填写：`docker.io`（仅作为 Harbor 内部区分使用）
提供商	选择 Docker Hub
端点 URL（Endpoint URL）	填写： `https://*.xuanyuan.run` （请将 `*.xuanyuan.run` 替换为您的主专属域名）
认证	无需填写账号密码，保持为空（专属域名免登录）
缓存与同步	可按需勾选「缓存镜像」、「自动同步」等，以减少重复拉取延迟

关键字段填写（精简版）：

类型：Proxy Repository
仓库名称：docker.io
提供商：Docker Hub
端点 URL：https://***.xuanyuan.run
认证：不勾选、不填写任何账号密码

为什么不需要账号密码？专业版专属域名本身已经和您的帐户绑定，并支持免登录鉴权，所以 Harbor 只需把请求转发到专属域名即可，无需再配置额外 credential，极大简化了 Harbor 的接入成本。

3
在 Harbor 中配置其他镜像源代理（以 GHCR 为例）

对于 ghcr.io、gcr.io、quay.io、nvcr.io 等其他镜像源，思路与 docker.io 完全一致：在 Harbor 中新建一个对应的 Proxy Repository，并将对应的专属域名写入端点 URL。

以 GHCR 为例的推荐配置：

远程仓库类型：Proxy Repository
仓库名称：可填 ghcr.io
提供商：GitHub Container Registry
端点 URL：https://***-ghcr.xuanyuan.run（替换为您的 GHCR 专属域名）
认证：无需填写账号密码
缓存策略：可按项目需要勾选镜像缓存 / 自动同步

常见镜像源与专属域名对应关系：

原始镜像源	Harbor 端点 URL 示例（专属域名）
docker.io	https://***.xuanyuan.run
ghcr.io	https://***-ghcr.xuanyuan.run
gcr.io	https://***-gcr.xuanyuan.run
quay.io	https://***-quay.xuanyuan.run
nvcr.io	https://***-nvcr.xuanyuan.run

常见镜像源端点写法：

docker.io → https://***.xuanyuan.run
ghcr.io → https://***-ghcr.xuanyuan.run
gcr.io → https://***-gcr.xuanyuan.run
quay.io → https://***-quay.xuanyuan.run
nvcr.io → https://***-nvcr.xuanyuan.run

配置思路统一：对于每一个外部镜像源（docker.io / ghcr.io / gcr.io / quay.io / nvcr.io 等），都在 Harbor 中建立一个对应名称的 Proxy Repository，并将“端点 URL”指向对应的轩辕镜像专属域名即可。 Harbor 之后会统一从您的 Harbor 域名对外提供镜像拉取服务。

4
通过 Harbor 代理拉取镜像（命令示例）

完成 Harbor 远程仓库配置后，后续只需要面向 Harbor 自身拉取镜像即可。Harbor 会在后台通过轩辕镜像专属域名去访问外部源。

通用命令模板：

docker pull harbor.example.com/[远程仓库名称]/[镜像路径]:[标签]

其中 harbor.example.com 为您的 Harbor 域名，[远程仓库名称] 为上文配置的 Proxy Repository 名称，如 docker.io 或 ghcr.io。

示例 1：通过 Harbor 拉取 docker.io 的 nginx

docker pull harbor.example.com/docker.io/library/nginx:latest

对应的原始地址为 docker.io/library/nginx:latest，Harbor 会自动通过主专属域名去拉取并缓存。

示例 2：通过 Harbor 拉取 ghcr.io 的镜像

docker pull harbor.example.com/ghcr.io/owner/image:tag

对应的原始地址为 ghcr.io/owner/image:tag，Harbor 会通过您配置的 GHCR 专属域名代理访问。

建议您在项目中统一使用 Harbor 域名（如 harbor.example.com/docker.io/...），而不要混用多个外部 Registry 域名，这样更便于权限控制、审计和缓存命中。

5
连通性验证与常见问题排查

当您发现 Harbor 拉取失败或下载速度异常时，可以按照以下步骤快速自查问题来源：是 Harbor 配置问题、网络问题，还是专属域名自身不可达。

1）在 Harbor 服务器上测试专属域名连通性

curl -v https://***.xuanyuan.run/v2/

若返回 HTTP 200 或 HTTP 401 状态码均属于正常：401 表示服务可达、但未携带完整镜像路径，是专属域名免登录模式下的常见返回。

2）查看 Harbor 日志

若 curl 正常但通过 Harbor 拉取失败，请在 Harbor 服务器上检查核心服务日志，关注是否有连接外部端点失败或 401/402/5xx 等信息：

Harbor 部署为 Docker Compose / Helm 时，可分别查看 jobservice、core、registry 等组件的日志
重点检查远程仓库配置名对应的错误堆栈，确认是否拼写错误、端点 URL 填错，或者专属域名解析失败

3）网络与防火墙排查

确认 Harbor 所在服务器可以正常访问 *.xuanyuan.run 域名（无公司防火墙、代理、DNS 污染等拦截）
如存在企业代理，建议先将 Harbor 节点配置为直连互联网，或在代理中允许直连专属域名

拉取频繁失败的典型原因：端点 URL 填写了错误的专属域名、Harbor 中误配置了认证信息、或 Harbor 所在机器无法访问外网。建议先用 curl 单独验证专属域名，再结合 Harbor 日志定位具体仓库与请求路径。

轩辕镜像配置手册

探索更多轩辕镜像的使用方法，找到最适合您系统的配置方式

Docker 配置

登录仓库拉取

通过 Docker 登录认证访问私有仓库

专属域名拉取

无需登录使用专属域名

K8s Containerd

Kubernetes 集群配置 Containerd

K3s

K3s 轻量级 Kubernetes 镜像加速

Dev Containers

VS Code Dev Containers 配置

Podman

Podman 容器引擎配置

Singularity/Apptainer

HPC 科学计算容器配置

其他仓库配置

ghcr、Quay、nvcr 等镜像仓库

Harbor 镜像源配置

Harbor Proxy Repository 对接专属域名

Portainer 镜像源配置

Portainer Registries 加速拉取

Nexus 镜像源配置

Nexus3 Docker Proxy 内网缓存

系统配置

Linux

在 Linux 系统配置镜像服务

Windows/Mac

在 Docker Desktop 配置镜像

MacOS OrbStack

MacOS OrbStack 容器配置

Docker Compose

Docker Compose 项目配置

NAS 设备

群晖

Synology 群晖 NAS 配置

飞牛

飞牛 fnOS 系统配置镜像

绿联

绿联 NAS 系统配置镜像

威联通

QNAP 威联通 NAS 配置

极空间

极空间 NAS 系统配置服务

网络设备

爱快路由

爱快 iKuai 路由系统配置

宝塔面板

在宝塔面板一键配置镜像

需要其他帮助？请查看我们的常见问题Docker 镜像访问常见问题解答或提交工单

镜像拉取常见问题

使用与功能问题

配置了专属域名后，docker search 为什么会报错？

docker search 限制

Docker Hub 上有的镜像，为什么在轩辕镜像网站搜不到？

站内搜不到镜像

机器不能直连外网时，怎么用 docker save / load 迁镜像？

离线 save/load

docker pull 拉插件报错（plugin v1+json）怎么办？

插件要用 plugin install

WSL 里 Docker 拉镜像特别慢，怎么排查和优化？

WSL 拉取慢

轩辕镜像安全吗？如何用 digest 校验镜像没被篡改？

安全与 digest

第一次用轩辕镜像拉 Docker 镜像，要怎么登录和配置？

新手拉取配置

轩辕镜像合规吗？轩辕镜像的合规是怎么做的？

镜像合规机制

错误码与失败问题

docker pull 提示 manifest unknown 怎么办？

manifest unknown

docker pull 提示 no matching manifest 怎么办？

no matching manifest（架构）

镜像已拉取完成，却提示 invalid tar header 或 failed to register layer 怎么办？

invalid tar header（解压）

Docker pull 时 HTTPS / TLS 证书验证失败怎么办？

TLS 证书失败

Docker pull 时 DNS 解析超时或连不上仓库怎么办？

DNS 超时

Docker 拉取出现 410 Gone 怎么办？

410 Gone 排查

出现 402 或「流量用尽」提示怎么办？

402 与流量用尽

Docker 拉取提示 UNAUTHORIZED（401）怎么办？

401 认证失败

遇到 429 Too Many Requests（请求太频繁）怎么办？

429 限流

docker login 提示 Cannot autolaunch D-Bus，还算登录成功吗？

D-Bus 凭证提示

为什么会出现「单层超过 20GB」或 413，无法加速拉取？

413 与超大单层

账号 / 计费 / 权限

轩辕镜像免费版和专业版有什么区别？

免费版与专业版区别

轩辕镜像支持哪些 Docker 镜像仓库？

支持的镜像仓库

镜像拉取失败还会不会扣流量？

失败是否计费

麒麟 V10 / 统信 UOS 提示 KYSEC 权限不够怎么办？

KYSEC 拦截脚本

如何在轩辕镜像申请开具发票？

申请开票

怎么修改轩辕镜像的网站登录和仓库登录密码？

修改登录密码

如何注销轩辕镜像账户？要注意什么？

注销账户

配置与原理类

写了 registry-mirrors，为什么还是走官方或仍然报错？

mirrors 不生效

怎么用 docker tag 去掉镜像名里的轩辕域名前缀？

去掉域名前缀

如何拉取指定 CPU 架构的镜像（如 ARM64、AMD64）？

指定架构拉取

用轩辕镜像拉镜像时快时慢，常见原因有哪些？

拉取速度原因

查看全部问题→

用户好评

来自真实用户的反馈，见证轩辕镜像的优质服务

oldzhang

运维工程师

Linux服务器

"Docker访问体验非常流畅，大镜像也能快速完成下载。"