一、前言在国内直接拉取 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(wget-qO- https://xuanyuan.cloud/docker.sh)生产环境建议先下载脚本、审阅源码后再执行wgethttps://xuanyuan.cloud/docker.sh-Odocker-install.shlessdocker-install.shbashdocker-install.sh脚本主要能力自动检测系统并安装 Docker写入镜像加速配置包管理器失败时尝试二进制安装在 Windows/macOS 上会提示改用桌面端配置。四、手动配置已安装 Docker服务器已有 Docker 时直接改配置即可无需重装。1. Linuxsudomkdir-p/etc/dockercatEOF|sudotee/etc/docker/daemon.json{ registry-mirrors: [https://docker.xuanyuan.me] } EOFsudosystemctl daemon-reloadsudosystemctl restartdocker验证dockerinfo|grepRegistry Mirrors-A3输出包含docker.xuanyuan.me即生效。专业版将地址替换为你的专属域名例如https://你的专属域名.xuanyuan.run。图文教程Linux 镜像源配置注意registry-mirrors只对docker.ioDocker Hub生效。GHCR、GCR、registry.k8s.io 等需在 containerd / Podman 中单独配置。2. macOS Docker Desktop打开 Docker Desktop → Settings → Docker Engine粘贴{registry-mirrors:[https://docker.xuanyuan.me]}点击Apply Restart。专业版示例{registry-mirrors:[https://你的专属域名.xuanyuan.run]}3. Windows Docker Desktop右下角 Docker 图标 → Settings → Docker Engine修改 JSON 配置内容与 macOS 相同保存并重启。桌面端详细步骤Docker Desktop 配置教程。macOS 用户也可参考 OrbStack 配置。五、K8s / 容器运行时配置Kubernetes 默认使用 containerddaemon.json的registry-mirrors不会作用于集群内拉取需单独配置。1. containerdv1.x 示例将你的专属域名替换为个人中心中的实际域名。containerd v2.x 配置方式不同完整步骤见 containerd 配置教程。containerd config default|sudotee/etc/containerd/config.tomlsudovim/etc/containerd/config.toml在[plugins.io.containerd.grpc.v1.cri.registry.mirrors]下添加[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]sudosystemctl restart containerdsudocrictl pull docker.io/library/nginx:alpineK3s 用户可参考专用教程K3s 镜像源配置。多仓库索引镜像仓库配置总览。2. nerdctlnerdctl 共用 containerd 配置无需额外修改sudonerdctl pull nginx:alpine3. Podmansudovim/etc/containers/registries.conf.d/custom.confunqualified-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 DevContainerDevContainer 配置私有 Harbor 前置加速Harbor 配置教程六、NAS 设备配置NAS 上注册表搜索、套件拉取等场景建议使用专业版专属域名你的专属域名.xuanyuan.run免填账号密码稳定性更好。免费版可用于群晖试配见 群晖免费版配置。群晖 DSM安装 Container Manager或 Docker 套件注册表 → 设置 → 添加镜像仓库方式一推荐URL 填你的专属域名.xuanyuan.run用户名密码留空方式二URL 填docker.xuanyuan.run填写轩辕镜像账户与密码测试连接 → 保存详细图文群晖 NAS 配置教程 | Docker Compose 配置 | 注册表查询失败排查极空间Docker → 镜像 → 仓库 → 设置 → 添加专属域名置顶为默认源 → 保存。详细图文极空间 NAS 配置教程飞牛 fnOSDocker → 镜像仓库设置 → 添加镜像源 → 设为首选 → 保存。详细图文飞牛 fnOS 配置教程威联通 QNAPContainer Station → 存储库 → 添加自定义存储库 → 选择「其他」→ 填写专属域名 → 测试连接 → 保存。详细图文威联通 NAS 配置教程绿联管理后台 → 镜像仓库 → 配置轩辕镜像源 → 保存。详细图文绿联 NAS 配置教程七、镜像拉取示例直接拉取配置了registry-mirrors后可直接用官方镜像名dockerpull nginx:latestdockerpull mysql:8.0免费版前缀拉取无需改 daemon.jsondockerpull docker.xuanyuan.me/library/nginx:latest专业版前缀拉取dockerpull 你的专属域名.xuanyuan.run/library/redis:7.2K8s 镜像containerdsudocrictl pull registry.k8s.io/pause:3.9Docker ComposeCompose V2 可不写version字段。敏感信息放.env勿提交到版本库services:web:image:nginx:latestports:-8080:80db:image:mysql:8.0environment:MYSQL_ROOT_PASSWORD:${MYSQL_ROOT_PASSWORD}# .envMYSQL_ROOT_PASSWORD你的强密码dockercompose up-d更多示例Docker Compose 配置教程八、常见问题1. 配了 registry-mirrorsGHCR / 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.meNAS 日常使用专业版专属域名K8s / CI/CD专业版 containerd 多仓库配置企业生产专业版 本地 Harbor 缓存更多问题查阅 轩辕镜像 FAQ或通过 工单 联系支持。完整教程索引xuanyuan.cloud/usage。
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(wget-qO- https://xuanyuan.cloud/docker.sh)生产环境建议先下载脚本、审阅源码后再执行wgethttps://xuanyuan.cloud/docker.sh-Odocker-install.shlessdocker-install.shbashdocker-install.sh脚本主要能力自动检测系统并安装 Docker写入镜像加速配置包管理器失败时尝试二进制安装在 Windows/macOS 上会提示改用桌面端配置。四、手动配置已安装 Docker服务器已有 Docker 时直接改配置即可无需重装。1. Linuxsudomkdir-p/etc/dockercatEOF|sudotee/etc/docker/daemon.json{ registry-mirrors: [https://docker.xuanyuan.me] } EOFsudosystemctl daemon-reloadsudosystemctl restartdocker验证dockerinfo|grepRegistry Mirrors-A3输出包含docker.xuanyuan.me即生效。专业版将地址替换为你的专属域名例如https://你的专属域名.xuanyuan.run。图文教程Linux 镜像源配置注意registry-mirrors只对docker.ioDocker Hub生效。GHCR、GCR、registry.k8s.io 等需在 containerd / Podman 中单独配置。2. macOS Docker Desktop打开 Docker Desktop → Settings → Docker Engine粘贴{registry-mirrors:[https://docker.xuanyuan.me]}点击Apply Restart。专业版示例{registry-mirrors:[https://你的专属域名.xuanyuan.run]}3. Windows Docker Desktop右下角 Docker 图标 → Settings → Docker Engine修改 JSON 配置内容与 macOS 相同保存并重启。桌面端详细步骤Docker Desktop 配置教程。macOS 用户也可参考 OrbStack 配置。五、K8s / 容器运行时配置Kubernetes 默认使用 containerddaemon.json的registry-mirrors不会作用于集群内拉取需单独配置。1. containerdv1.x 示例将你的专属域名替换为个人中心中的实际域名。containerd v2.x 配置方式不同完整步骤见 containerd 配置教程。containerd config default|sudotee/etc/containerd/config.tomlsudovim/etc/containerd/config.toml在[plugins.io.containerd.grpc.v1.cri.registry.mirrors]下添加[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]sudosystemctl restart containerdsudocrictl pull docker.io/library/nginx:alpineK3s 用户可参考专用教程K3s 镜像源配置。多仓库索引镜像仓库配置总览。2. nerdctlnerdctl 共用 containerd 配置无需额外修改sudonerdctl pull nginx:alpine3. Podmansudovim/etc/containers/registries.conf.d/custom.confunqualified-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 DevContainerDevContainer 配置私有 Harbor 前置加速Harbor 配置教程六、NAS 设备配置NAS 上注册表搜索、套件拉取等场景建议使用专业版专属域名你的专属域名.xuanyuan.run免填账号密码稳定性更好。免费版可用于群晖试配见 群晖免费版配置。群晖 DSM安装 Container Manager或 Docker 套件注册表 → 设置 → 添加镜像仓库方式一推荐URL 填你的专属域名.xuanyuan.run用户名密码留空方式二URL 填docker.xuanyuan.run填写轩辕镜像账户与密码测试连接 → 保存详细图文群晖 NAS 配置教程 | Docker Compose 配置 | 注册表查询失败排查极空间Docker → 镜像 → 仓库 → 设置 → 添加专属域名置顶为默认源 → 保存。详细图文极空间 NAS 配置教程飞牛 fnOSDocker → 镜像仓库设置 → 添加镜像源 → 设为首选 → 保存。详细图文飞牛 fnOS 配置教程威联通 QNAPContainer Station → 存储库 → 添加自定义存储库 → 选择「其他」→ 填写专属域名 → 测试连接 → 保存。详细图文威联通 NAS 配置教程绿联管理后台 → 镜像仓库 → 配置轩辕镜像源 → 保存。详细图文绿联 NAS 配置教程七、镜像拉取示例直接拉取配置了registry-mirrors后可直接用官方镜像名dockerpull nginx:latestdockerpull mysql:8.0免费版前缀拉取无需改 daemon.jsondockerpull docker.xuanyuan.me/library/nginx:latest专业版前缀拉取dockerpull 你的专属域名.xuanyuan.run/library/redis:7.2K8s 镜像containerdsudocrictl pull registry.k8s.io/pause:3.9Docker ComposeCompose V2 可不写version字段。敏感信息放.env勿提交到版本库services:web:image:nginx:latestports:-8080:80db:image:mysql:8.0environment:MYSQL_ROOT_PASSWORD:${MYSQL_ROOT_PASSWORD}# .envMYSQL_ROOT_PASSWORD你的强密码dockercompose up-d更多示例Docker Compose 配置教程八、常见问题1. 配了 registry-mirrorsGHCR / 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.meNAS 日常使用专业版专属域名K8s / CI/CD专业版 containerd 多仓库配置企业生产专业版 本地 Harbor 缓存更多问题查阅 轩辕镜像 FAQ或通过 工单 联系支持。完整教程索引xuanyuan.cloud/usage。
