2026 Docker 国内镜像加速配置教程

一、前言

在国内直接拉取 Docker Hub 等官方仓库，常见速度慢、超时、部署中断等问题。K8s 集群、NAS 容器、CI/CD 流水线都会受此影响。

本文介绍轩辕镜像的免费版与专业版配置方法，覆盖 Linux、Windows、macOS 及常见容器运行时。更完整的图文教程见官网：Docker 镜像访问使用教程。

适用场景：个人学习测试、开发调试、团队 CI/CD、NAS 与 K8s 部署。

二、版本选择（免费版 / 专业版）

轩辕镜像分两个版本，按场景选用即可。

1. 免费版（学习测试）

加速地址：https://docker.xuanyuan.me
说明：无需注册，配置 registry-mirrors 或前缀拉取即可
限制：仅加速 Docker Hub；有请求频次限流；不承诺速度与持续可用性
适用：本地开发、功能验证、临时拉取
详细说明 ：轩辕镜像免费版使用方法

不建议用于生产环境、自动化 CI/CD 或大规模集群。

2. 专业版（日常与生产）

官网：https://xuanyuan.cloud
能力：支持 Docker Hub、GHCR、GCR、registry.k8s.io、NVCR 等多仓库；专属域名免登录拉取
计费：按流量计费，拉取失败不计费
适用：NAS 长期使用、K8s、常态化 CI/CD、企业生产
配置方式 ：
- 专属域名（推荐）：专属域名配置教程
- 登录拉取：docker.xuanyuan.run + 镜像账户密码，见登录配置教程

三、一键脚本配置

官方脚本支持 15 种主流 Linux 发行版 （含 Ubuntu、Debian、Rocky Linux、openEuler、统信 UOS、银河麒麟、Anolis 等），可自动安装 Docker、写入镜像源，支持 x86_64 与 ARM。安装说明：Linux 系统安装指南。

测试环境

bash 复制代码

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

生产环境

建议先下载脚本、审阅源码后再执行：

bash 复制代码

wget https://xuanyuan.cloud/docker.sh -O docker-install.sh
less docker-install.sh
bash docker-install.sh

脚本主要能力：自动检测系统并安装 Docker；写入镜像加速配置；包管理器失败时尝试二进制安装；在 Windows/macOS 上会提示改用桌面端配置。

四、手动配置（已安装 Docker）

服务器已有 Docker 时，直接改配置即可，无需重装。

1. Linux

bash 复制代码

sudo mkdir -p /etc/docker

cat <<EOF | sudo tee /etc/docker/daemon.json
{
  "registry-mirrors": ["https://docker.xuanyuan.me"]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

验证：

bash 复制代码

docker info | grep "Registry Mirrors" -A 3

输出包含 docker.xuanyuan.me 即生效。

专业版将地址替换为你的专属域名，例如 https://你的专属域名.xuanyuan.run。

图文教程：Linux 镜像源配置

注意：registry-mirrors 只对 docker.io（Docker Hub） 生效。GHCR、GCR、registry.k8s.io 等需在 containerd / Podman 中单独配置。

2. macOS Docker Desktop

打开 Docker Desktop → Settings → Docker Engine，粘贴：

json 复制代码

{
  "registry-mirrors": ["https://docker.xuanyuan.me"]
}

点击 Apply & Restart。

专业版示例：

json 复制代码

{
  "registry-mirrors": ["https://你的专属域名.xuanyuan.run"]
}

3. Windows Docker Desktop

右下角 Docker 图标 → Settings → Docker Engine，修改 JSON 配置，内容与 macOS 相同，保存并重启。

桌面端详细步骤：Docker Desktop 配置教程。macOS 用户也可参考 OrbStack 配置。

五、K8s / 容器运行时配置

Kubernetes 默认使用 containerd，daemon.json 的 registry-mirrors 不会作用于集群内拉取，需单独配置。

1. containerd（v1.x 示例）

将 你的专属域名 替换为个人中心中的实际域名。containerd v2.x 配置方式不同，完整步骤见 containerd 配置教程。

bash 复制代码

containerd config default | sudo tee /etc/containerd/config.toml
sudo vim /etc/containerd/config.toml

在 [plugins."io.containerd.grpc.v1.cri".registry.mirrors] 下添加：

toml 复制代码

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
  endpoint = ["https://你的专属域名.xuanyuan.run", "https://registry-1.docker.io"]

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"]
  endpoint = ["https://你的专属域名-k8s.xuanyuan.run"]

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."ghcr.io"]
  endpoint = ["https://你的专属域名-ghcr.xuanyuan.run"]

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
  endpoint = ["https://你的专属域名-gcr.xuanyuan.run"]

# 旧版仓库，已废弃，仅兼容老集群
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."k8s.gcr.io"]
  endpoint = ["https://你的专属域名-k8s.xuanyuan.run"]

bash 复制代码

sudo systemctl restart containerd
sudo crictl pull docker.io/library/nginx:alpine

K3s 用户可参考专用教程：K3s 镜像源配置。多仓库索引：镜像仓库配置总览。

2. nerdctl

nerdctl 共用 containerd 配置，无需额外修改：

bash 复制代码

sudo nerdctl pull nginx:alpine

3. Podman

bash 复制代码

sudo vim /etc/containers/registries.conf.d/custom.conf

toml 复制代码

unqualified-search-registries = ["docker.io"]

[[registry]]
prefix = "docker.io"
location = "registry-1.docker.io"
  [[registry.mirror]]
  location = "你的专属域名.xuanyuan.run"

[[registry]]
prefix = "registry.k8s.io"
location = "registry.k8s.io"
  [[registry.mirror]]
  location = "你的专属域名-k8s.xuanyuan.run"

[[registry]]
prefix = "ghcr.io"
location = "ghcr.io"
  [[registry.mirror]]
  location = "你的专属域名-ghcr.xuanyuan.run"

详细说明：Podman 配置教程。

4. 其他开发者场景

VS Code DevContainer：DevContainer 配置
私有 Harbor 前置加速：Harbor 配置教程

六、NAS 设备配置

NAS 上注册表搜索、套件拉取等场景，建议使用专业版专属域名 （你的专属域名.xuanyuan.run），免填账号密码，稳定性更好。免费版可用于群晖试配，见群晖免费版配置。

群晖 DSM

安装 Container Manager（或 Docker 套件）
注册表 → 设置 → 添加镜像仓库
方式一（推荐）：URL 填 你的专属域名.xuanyuan.run，用户名密码留空
方式二：URL 填 docker.xuanyuan.run，填写轩辕镜像账户与密码
测试连接 → 保存

详细图文：群晖 NAS 配置教程 | Docker Compose 配置 | 注册表查询失败排查

极空间

Docker → 镜像 → 仓库 → 设置 → 添加专属域名，置顶为默认源 → 保存。

详细图文：极空间 NAS 配置教程

飞牛 fnOS

Docker → 镜像仓库设置 → 添加镜像源 → 设为首选 → 保存。

详细图文：飞牛 fnOS 配置教程

威联通 QNAP

Container Station → 存储库 → 添加自定义存储库 → 选择「其他」→ 填写专属域名 → 测试连接 → 保存。

详细图文：威联通 NAS 配置教程

绿联

管理后台 → 镜像仓库 → 配置轩辕镜像源 → 保存。

详细图文：绿联 NAS 配置教程

七、镜像拉取示例

直接拉取

配置了 registry-mirrors 后，可直接用官方镜像名：

bash 复制代码

docker pull nginx:latest
docker pull mysql:8.0

免费版前缀拉取（无需改 daemon.json）：

bash 复制代码

docker pull docker.xuanyuan.me/library/nginx:latest

专业版前缀拉取：

bash 复制代码

docker pull 你的专属域名.xuanyuan.run/library/redis:7.2

K8s 镜像（containerd）：

bash 复制代码

sudo crictl pull registry.k8s.io/pause:3.9

Docker Compose

Compose V2 可不写 version 字段。敏感信息放 .env，勿提交到版本库：

yaml 复制代码

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}

bash 复制代码

# .env
MYSQL_ROOT_PASSWORD=你的强密码

docker compose up -d

更多示例：Docker Compose 配置教程

八、常见问题

1. 配了 registry-mirrors，GHCR / K8s 镜像还是失败？

registry-mirrors 仅作用于 Docker Hub。第三方仓库需在 containerd 或 Podman 中按仓库单独配置；免费版不支持多仓库加速。

参考：registry-mirrors 不生效 | 支持的仓库列表

2. 出现 429 Too Many Requests？

免费版 （报错 URL 含 docker.xuanyuan.me）：单次限流约 6 小时自动恢复；持续触发可能延长至 72 小时。暂停批量重试，等待恢复。
专业版：异常高频请求约 24 小时自动解除。

若已配专业版却仍看到 docker.xuanyuan.me，常见原因是镜像标签不存在导致客户端回退到免费源。

详见：429 限流处理

3. NAS 配置后没有效果？

确认使用专属域名，且账户有可用流量（流量耗尽会返回 402）
重启容器套件后重试
威联通若报「存储库提供商不匹配」，可检查 DNS 与流量状态

各品牌详细排查见对应 NAS 教程（第六节链接）。

4. 证书或 HTTPS 报错？

检查专属域名是否正确、流量是否充足。勿随意关闭 TLS 校验或添加 insecure-registries，生产环境应使用平台提供的合法证书域名。

九、选型参考

场景	建议
本地学习、临时测试	免费版 `docker.xuanyuan.me`
NAS 日常使用	专业版专属域名
K8s / CI/CD	专业版 + containerd 多仓库配置
企业生产	专业版 + 本地 Harbor 缓存

更多问题查阅轩辕镜像 FAQ，或通过工单联系支持。完整教程索引：xuanyuan.cloud/usage。