让 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 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
Singularity / Apptainer Docker 镜像源配置教程
教程简介
适用场景
1关于 Singularity 和 Apptainer
Apptainer 是 Singularity 项目的社区分支，两者功能基本相同，命令也基本兼容。本教程同时适用于 Singularity 和 Apptainer。
请使用以下命令查看版本：
singularity --version
或（如果使用的是 Apptainer）：
apptainer --version
2安装 Singularity/Apptainer
如果您的系统尚未安装 Singularity 或 Apptainer，可以使用以下方法安装：
Ubuntu/Debian（推荐使用 Apptainer）：
sudo add-apt-repository ppa:apptainer/ppa -y sudo apt update sudo apt install -y apptainer
CentOS/RHEL：
sudo yum install -y epel-release sudo yum install -y singularity
从源码编译安装：
# 从源码编译安装（适用于高级用户） # 参考官方文档：https://apptainer.org/docs/admin/main/installation.html
💡提示：更多安装方法请参考官方文档：Apptainer 安装文档或Singularity 安装文档
3专属域名方式（推荐）
若您已分配专属域名，此方式无需设置环境变量，直接在 docker:// 地址中指定专属域名即可，比环境变量登录更简单。
基本用法：
singularity pull myapp.sif docker://***.xuanyuan.run/library/nginx:alpine
或使用 Apptainer 命令：
apptainer pull myapp.sif docker://***.xuanyuan.run/library/nginx:alpine
💡重要提示：请将命令中的 *** 替换为您的专属域名前缀。例如，如果您的专属域名为 123abc.xuanyuan.run，则应将 *** 替换为 123abc。
多仓库镜像拉取示例：
优势：无需设置环境变量或登录凭据，直接在命令中指定专属域名即可。适合无 shell 登录需求、批量脚本、多 registry 后缀（GHCR、GCR 等）场景。
4环境变量登录方式（不推荐，仅支持 docker.io）
若您尚未分配专属域名，可在 HPC 作业脚本中通过环境变量向 Singularity/Apptainer 传递凭据，拉取 docker://docker.xuanyuan.run/...（docker.io）镜像。此方式不推荐，且不支持 GHCR、GCR 等其他 registry，请优先使用上方专属域名方式。
在本站完成注册并充值流量包后，在个人中心「镜像仓库信息」中获取镜像账户和镜像密码。
1. 设置环境变量（推荐 SingularityCE 变量名）：
export SINGULARITY_DOCKER_USERNAME=镜像账户 export SINGULARITY_DOCKER_PASSWORD=镜像密码
2. 拉取镜像：
singularity pull test.sif docker://docker.xuanyuan.run/library/nginx:latest
或使用 Apptainer 命令：
apptainer pull test1.sif docker://docker.xuanyuan.run/library/redis:latest
Apptainer 兼容变量名：
# 使用 Apptainer 时也可改用以下变量名（可消除兼容提示） export APPTAINER_DOCKER_USERNAME=镜像账户 export APPTAINER_DOCKER_PASSWORD=镜像密码
镜像账户和镜像密码可在登录后，在左侧菜单栏「个人中心」→「用户信息」→「镜像仓库信息」中查看。
⚠️不支持 docker login：Singularity/Apptainer 不会自动读取 ~/.docker/config.json 中的 Docker 凭据，请勿照搬 Docker CLI 的 docker login 流程。
💡变量名提示：若使用 Apptainer 且已设置 SINGULARITY_DOCKER_*，可能出现 SINGULARITY_DOCKER_* is set, but APPTAINER_DOCKER_* is preferred 提示，Apptainer 仍会使用已设置的凭据，可忽略；若希望消除提示，可改用上方 APPTAINER_DOCKER_USERNAME/PASSWORD。
安全提示：环境变量会出现在进程列表中，HPC 共享节点请谨慎使用；脚本场景可在拉取完成后执行 unset SINGULARITY_DOCKER_USERNAME SINGULARITY_DOCKER_PASSWORD，或仅在作业脚本内设置。
适用范围：仅支持 docker.xuanyuan.run（docker.io）；其他 registry 请使用上方专属域名后缀方式。
5验证配置是否生效
拉取镜像后，可以通过以下方式验证配置是否生效：
- 观察拉取速度，如果明显快于直接拉取官方源，说明配置生效
- 检查镜像文件是否成功下载到本地（
ls -lh test.sif） - 专属域名方式：在网络抓包工具中查看是否访问了您的专属域名
- 环境变量登录（docker.io）：确认未出现 UNAUTHORIZED 或 402 错误
专属域名示例：
singularity pull test.sif docker://***.xuanyuan.run/library/alpine:latest
环境变量登录示例（docker.io）：
singularity pull test.sif docker://docker.xuanyuan.run/library/nginx:latest
拉取成功后，可以使用 ls -lh test.sif 查看镜像文件。
6常见问题
- 专属域名拼写错误
- 专属域名没有流量
- 镜像账户或密码错误（环境变量登录）
- 镜像路径不正确
- 网络连接问题
- 检查命令中的域名是否正确
- 前往充值页面充值流量包
- 确认镜像路径格式正确
- 检查网络连接
- 仍在使用官方源地址
- 专属域名配置错误
- 确认命令中使用的是专属域名
- 检查域名配置是否正确
镜像拉取常见问题
功能
错误码
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
"Docker访问体验非常流畅，大镜像也能快速完成下载。"