让 AI 帮你使用轩辕镜像？ · 展开查看说明
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可：
请先完整阅读并严格遵守以下文档中的全部规则与要求：
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。 若 AI 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
Docker Compose 镜像源配置教程
教程简介
适用场景
背景说明
Docker 默认使用官方镜像仓库，在国内大陆访问时速度较慢，容易出现连接超时、拉取失败等问题。
轩辕镜像支持 9 个主流镜像仓库：
轩辕镜像提供高速稳定的镜像服务，支持 Docker 和 Compose 环境，无需额外插件，全面兼容 Docker 镜像拉取逻辑。
💡适用场景：希望通过 docker-compose 管理容器，并全局启用轩辕镜像功能的用户
Compose 转换工具（新手推荐）
如果你刚接触 Docker Compose，建议先从工具页完成配置再回到教程落地。下面两个入口分别覆盖「可视化生成」和「YAML 一键转换」场景，适合不同阶段的用户使用。
Compose 综合工具页（默认入口）
该页面默认进入可视化模式，可通过表单配置镜像、端口、卷、环境变量、重启策略、GPU 和资源限制等参数，实时生成 docker-compose.yml。
页面内置常用模板，并支持与 Docker Run 工具双向衔接（Compose 可转 Run，Run 也可带参数回填），更适合从零搭建或边配边看的新手。
打开 Compose 综合工具页YAML 一键转换模式
该入口直接打开 tab=yaml 模式：粘贴现有 Compose 文件后可一键转换为轩辕版本，自动处理镜像地址，并保留 services、volumes、networks、depends_on 等原有结构。
你还可以按需勾选 NPM/PIP/Golang/Yarn/HuggingFace 加速配置，转换后支持在线复制和下载 YAML，适合已有项目做批量改造或迁移。
打开 YAML 一键转换模式1获取专属域名
登录网站后，点击左侧菜单栏的「专属域名」菜单即可获取您的专属域名：
格式示例：https://***.xuanyuan.run
其中 *** 为您专属域名，请替换下文命令中的 *** 部分。
2配置 Docker Daemon 镜像源
推荐方案：一键安装配置脚本
该脚本支持多种Linux发行版，支持一键安装 docker、docker-compose 并且一键配置轩辕镜像源。
或者手动编辑（或创建）Docker 的配置文件 /etc/docker/daemon.json：
echo '{
"insecure-registries": ["***.xuanyuan.run"],
"registry-mirrors": ["https://***.xuanyuan.run"]
}' | sudo tee /etc/docker/daemon.json > /dev/null⚠️请将 *** 替换为您的专属域名。登录网站后，点击左侧菜单栏的「专属域名」菜单即可获取。
3重新加载 Daemon 并重启 Docker 服务
重新加载 systemd daemon 配置：
sudo systemctl daemon-reload
重启 Docker 服务：
sudo systemctl restart docker
可选：查看 Docker 配置是否加载成功
docker info | grep -A 10 "Registry Mirrors"
输出中应包含您的专属地址，例如：
https://***.xuanyuan.run/
使用 Docker Compose 拉取镜像
一旦系统级 Docker 配置完成，Docker Compose 将自动使用轩辕镜像镜像拉取，无须单独配置 Compose 文件。
示例 docker-compose.yml：
version: "3.8"
services:
web:
image: nginx:latest
ports:
- "8080:80"
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: root运行命令：
docker compose up -d
镜像将自动通过 https://***.xuanyuan.run 拉取，无需额外设置。
验证镜像拉取是否优化访问
执行以下命令查看实际使用的拉取源：
docker pull mysql:8.0
再查看系统日志：
journalctl -u docker.service -n 50
如果看到如 connecting to https://***.xuanyuan.run/v2/ 的字样，说明配置已生效。
常见问题解答
Q: 为什么配置了 registry-mirrors，还是走 docker.io？
很多用户反馈，已经在 Docker 中配置了镜像源（registry-mirrors），但拉取镜像时仍然访问官方源（docker.io）。
拉取报错如下：
Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client. Timeout exceeded while awaiting headers)这是因为 Docker 的镜像拉取机制是优先尝试使用镜像源，而不是强制始终使用。部分镜像的 tag 或 namespace 特殊（如 docker-library），可能仍绕过镜像源。
常见原因：
专属域名没有可用流量
如果你使用专属域名，但该地址没有充值流量，当 Docker 客户端请求镜像源时，服务端会返回 402 Payment Required 错误，Docker 就会直接回退到官方仓库 docker.io 拉取镜像。
解决方案： 请前往充值页面充值相应的流量包，确保您的专属域名有足够的流量支持镜像服务。
如何确认专属域名可用
建议先用下列方式测试：
docker pull ***.xuanyuan.run/mysql如果能正常拉取，说明专属域名可用且有流量。
解决方法：
强烈建议手动修改 docker-compose.yml 中的镜像地址为专属域名，如：
version: "3.8"
services:
web:
image: ***.xuanyuan.run/library/nginx:latest
ports:
- "8080:80"
db:
image: ***.xuanyuan.run/library/mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootDockerfile 示例
Dockerfile 里是这样写的：
FROM centos VOLUME ["volume01" "volume02"] CMD echo '----end----' CMD /bin/bash
这里 FROM centos 表示基础镜像是从 Docker Hub 官方仓库拉取的 centos 镜像。
如果你要指定用 轩辕镜像仓库地址，只要在 FROM 里写完整的专属域名镜像地址即可，例如：
假设你的镜像仓库地址是 ***.xuanyuan.run/centos:7
那么 Dockerfile 改成：
FROM ***.xuanyuan.run/centos:7 VOLUME ["volume01" "volume02"] CMD echo '----end----' CMD ["/bin/bash"]
这样 docker build 时就不会去官方 Docker Hub 拉，而是从你指定的 轩辕镜像源 拉。
附加建议
若在 CI/CD 环境中（如 GitLab CI、GitHub Actions）使用 Docker Compose，可通过替换 Compose 文件中的镜像前缀（如 docker.io/nginx → ***.xuanyuan.run/nginx）来实现更强制性的访问优化。
技术支持
如遇配置问题，请 提交工单 寻求技术支持。
镜像拉取常见问题
功能
错误码
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
"Docker访问体验非常流畅，大镜像也能快速完成下载。"