xuanyuan_docker_proxy/usage/unraid-docker-guide.md

Unraid Docker 镜像源配置教程

在线版：https://xuanyuan.cloud/usage/unraid

在 Unraid Web 界面通过终端写入 Docker 镜像加速配置，使用轩辕镜像专属域名提升 docker.io 镜像拉取速度。

目录

• 适用场景
• 获取专属域名
• 终端配置镜像源
• 重启 Docker 服务
• 验证与使用
• 配置说明
• 流量耗尽提示

适用场景

本教程适用于已安装 Docker 插件的 Unraid 系统（通常为 Unraid 6.x 及以上），通过 Web 终端配置 registry-mirrors 接入轩辕镜像专属加速域名。

配置完成后，在 Unraid 的 Apps 页面搜索并下载 Docker 镜像时，系统会优先通过轩辕镜像加速拉取 docker.io 仓库镜像。

💡 其他 NAS 可参考群晖、飞牛等教程；多仓库前缀规则见专属域名拉取教程。

获取专属域名

登录网站后，在左侧菜单栏的「专属域名」中获取您的专属域名，格式为：***.xuanyuan.run

💡 请将 ***.xuanyuan.run 替换为您的专属域名。登录网站后，点击左侧菜单栏的「专属域名」即可获取。推荐使用专属加速域名，详见专属域名拉取教程。

终端配置镜像源

1. 打开 Unraid Web 管理页面，点击右侧菜单栏中的终端图标（>_）
2. 进入终端页面后，执行下方命令写入镜像加速配置

mkdir -p /etc/docker
tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": ["https://***.xuanyuan.run"]
}
EOF

此命令会将配置写入 /etc/docker/daemon.json

⚠️ 若 daemon.json 已存在且含其他配置项，请先执行 cat /etc/docker/daemon.json 备份，再手动合并 registry-mirrors 字段，避免覆盖原有设置。

重启 Docker 服务

写入配置后需重启 Docker 服务才能生效。请返回 Unraid Web 页面按以下步骤操作：

1. 点击顶部菜单栏的设置（Settings）
2. 找到并点击Docker
3. 将启用 Docker（Enable Docker）改为否，点击应用（Apply），等待 Docker 服务停止
4. 再次将启用 Docker改为是，点击应用，等待 Docker 服务启动完成

验证与使用

Docker 重启完成后，即可通过 Apps 页面搜索并下载镜像：

1. 打开 Unraid 的 Apps 页面
2. 搜索需要的镜像（例如 nginx）
3. 点击安装/下载，系统会通过轩辕镜像加速拉取

也可在终端中验证配置是否已加载：

cat /etc/docker/daemon.json

docker info | grep -A 5 "Registry Mirrors"

配置说明

• HTTPS 协议头：镜像源地址须为完整 URL，例如 https://***.xuanyuan.run，缺少 https:// 可能导致配置无效
• 仅对 docker.io 生效：registry-mirrors 只加速 Docker Hub（docker.io）镜像；GHCR、GCR 等仓库需使用专属域名完整路径拉取，参见专属域名拉取教程
• 配置持久性：Unraid 重启后 /etc/docker/daemon.json 通常保留；若升级系统后失效，请重新检查并重启 Docker

流量耗尽提示

当您的流量用尽时，拉取镜像会显示以下错误，请及时充值：

docker pull docker.xuanyuan.run/redis
Using default tag: latest
Error response from daemon: unknown: {"errors":[{"code":"PAYMENT_REQUIRED","message":"capacity has use up","detail":[{"Type":"repository","Name":"library/*","Action":"pull"}]}]}

💡 当您拉取镜像时返回 402 Payment Required 或 PAYMENT_REQUIRED 错误，表示流量已耗尽。请立即充值流量包以继续使用镜像服务。