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

1

前期准备：专属域名与 Portainer 环境

在开始 Portainer 配置之前，请先确认以下条件已经满足：

• 已在服务器上安装好 Docker，并确保可以正常拉取镜像。
• 已部署 Portainer（社区版或企业版均可），并能通过浏览器访问 Portainer Web 控制台（例如 https://portainer.example.com或通过服务器 IP + 端口访问）。
• 已在轩辕镜像控制台中开通并记下您的 专属域名，例如：
  • 主专属域名：xxx.xuanyuan.run （对应 docker.io）
  • GHCR 专属域名：xxx-ghcr.xuanyuan.run （对应 ghcr.io，可选）
  • GCR / Quay / NVCR 等专属域名：如 xxx-gcr.xuanyuan.run、xxx-quay.xuanyuan.run 等（可选）

2

在 Portainer 中新增加速镜像仓库（docker.io）

这里以 docker.io 为例，在 Portainer 的 Registries（镜像仓库）功能中新增一个指向轩辕镜像专属域名的仓库， 后续创建容器时选择该仓库即可走加速。

1. 使用管理员账号登录 Portainer Web 控制台。
2. 在左侧菜单中进入 “Registries / 镜像仓库”（部分版本在 Settings → Registries 中）。
3. 点击页面右上角的 “Add registry / 添加仓库”。
4. 在弹出的表单中，选择或填写以下信息（不同 Portainer 版本字段略有差异，可按含义对应）：

3

在 Portainer 中选择加速镜像仓库并创建容器

完成仓库创建后，在 Portainer 中新建容器或 Stacks 时，只需选择刚才配置的加速仓库，然后填写原始的镜像名称即可。

1. 进入对应的 Environment / 环境，在左侧菜单中选择 Containers 或 Stacks。
2. 点击 “Add container / 新建容器”（或在 Stack 中填写 compose 文件）。
3. 在镜像输入区域旁边（部分版本在 “Registry” 下拉框中），选择刚才创建的 docker.io (xuanyuan) 仓库。
4. 在镜像名称中，填写 原始镜像路径，例如：
   • 官方 nginx：library/nginx:latest
   • MySQL：mysql:8
   Portainer 会自动使用您选择的加速仓库作为前缀，即相当于拉取 xxx.xuanyuan.run/library/nginx:latest 等镜像。
5. 填写容器名称、端口映射、环境变量等其他信息，点击 “Deploy the container / 部署” 即可。

4

关键界面示例（截图说明）

下方三张截图展示了在 Portainer 中配置和使用轩辕镜像专属域名的关键界面，您可以对照自己的环境一步步核对设置是否正确。

① Registries 列表：新增使用轩辕镜像的镜像仓库

图 1：在 Portainer 的 Registries 页面中，可以看到额外新增的使用轩辕镜像加速的 docker.io 仓库（示例为登录验证方式，同样支持免登录专属域名方式）。

② Registry 详情：以 docker.xuanyuan.run 登录验证方式为例

图 2：示例中使用的是登录验证方式：Registry URL 为 https://docker.xuanyuan.run，并在 Authentication 中填写了镜像账户与镜像密码。 如果您使用专属域名免登录方式，只需将 URL 换成 https://xxx.xuanyuan.run，并关闭认证即可。

③ 创建容器：选择加速仓库并填写镜像名称

图 3：在新建容器界面中，从 Registry 下拉框中选择刚才新增的加速仓库（无论是登录验证方式还是免登录专属域名方式），然后在镜像名称中填写原始路径（如 library/nginx:latest），Portainer 会自动拼接专属域名前缀。

5

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

若在 Portainer 中拉取镜像失败或速度异常，可以按下面的顺序快速排查问题所在。