---
title: 绿联NAS安装KSpeeder：解决Docker镜像拉取V2错误
description: 在绿联 UGOS Pro 上用一条 Docker 命令安装 KSpeeder 镜像加速服务，再把它填入绿联 Docker 的加速器配置，解决拉取镜像时的 V2 错误与超时。
outline: deep
category: 教程
date: 2026-10-25
tags:
- KSpeeder
- 绿联
- Docker
- 镜像加速
- NAS
readingTime: 8 分钟
---
# 绿联NAS安装KSpeeder：解决Docker镜像拉取V2错误
> 📺 本图文教程由视频整理而成，对应的参考视频：[绿联NAS安装KSpeeder～解决Docker镜像拉取V2错误～](https://www.bilibili.com/video/BV1taj26RES7)。如需查看更详细、更具体的操作演示，可观看原视频。
> 场景：绿联 NAS（UGOS Pro）拉取 Docker 镜像时报 `V2` 错误或长时间超时，说明默认镜像源已经连不上。本教程先复现问题，再对比三种解决方案，最后用 KSpeeder 做本地镜像加速并验证效果。所有绿联机型通用，ARM 机型（如 DH4300 Plus）与 X86 机型都适用。
> 提示：本教程配套的操作文档，可在[好用斋官网](https://haoyongzhai.com) → [网盘分享](https://haoyongzhai.com/netdisk)（提取码 565）中下载。
## 第一步：复现 V2 错误
用终端工具（如 Tabby）SSH 连上绿联 NAS，先提权到 root：
```bash
sudo -i
```
输入管理员密码后回车。注意 **Linux 输入密码时不显示任何字符**，看不到星号是正常现象，输完直接回车即可。提示符从 `haoyong@DH4300PLUS:~$` 变成 `root@DH4300PLUS:~#`，说明已进入管理员模式。
打开[好用斋官网](https://haoyongzhai.com)，点击「Docker 懒人包」，NAS 系统选择「绿联（UGOS Pro）」，架构按机型选择：
1. DH4300 Plus 为 ARM 架构，选 `ARM64`。
2. 其余机型基本是 X86，选 `X86_64`，兼容性更好——ARM 能装的程序，X86 一定没问题。
列表中的灰色程序表示没有对应的 ARM 镜像、无法安装，本例 47 个程序里只有 2 个不支持。
向下滚动找到 OpenList，点击后右侧生成脚本，切换到「Docker CLI」标签，点击「复制内容」，回到终端右键粘贴并回车：
```bash
docker run -d \
--name openlist \
--restart unless-stopped \
-p 5544:5244 \
-v /volume1/docker/openlist:/opt/openlist/data \
-v /volume1:/volume1:rslave \
--user 0:0 \
-e UMASK=022 \
--network bridge \
openlistteam/openlist:latest
```
等待片刻，报错出现：
```text
docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting header).
```
**只要看到 `/v2/` 这个报错，就可以确定是镜像源连不上**，而不是命令写错了。此时要么更换镜像源，要么让请求走代理。
## 第二步：三种解决思路
| 方案 | 做法 | 特点 |
| ----------------- | ------------------------------------------------ | ----------------------------------------------------- |
| 绿联自带 1ms 加速 | Docker → 镜像 → 齿轮 → 加速器配置，添加 1ms 镜像 | 零安装，几分钟搞定；拉取超大镜像时可能有限制 |
| 代理 | 加速器配置里切到「代理」，填代理地址与端口 | 速度取决于代理质量，且必须先有可用的代理 |
| KSpeeder | 本地起一个加速容器，再把它的地址填进加速器配置 | 需多装一个容器；内置 1ms 并做多源负载均衡，长期最省心 |
不想装额外程序的，直接用第一种即可。KSpeeder 的优势是它本身也内置了 1ms 镜像源，并在多个镜像源之间做负载均衡，连接速度和稳定性通常更好，装一次可以长期使用。
## 第三步：安装 KSpeeder
在 root 提示符下，从懒人包页面复制 KSpeeder 的命令（同样在「Docker CLI」标签），粘贴并回车：
```bash
docker run -d \
--name kspeeder \
--restart unless-stopped \
-p 25443:5443 \
-p 25003:5003 \
-v /volume1/docker/kspeeder/kspeeder-data:/kspeeder-data \
-v /volume1/docker/kspeeder/kspeeder-config:/kspeeder-config \
--network bridge \
registry.kspeeder.com/linkease/kspeeder:latest
```
各参数要点：
| 参数 | 说明 |
| --------------------------- | ------------------------------------------------ |
| `-p 25443:5443` | 真正用于拉取镜像的端口，映射到宿主机 25443 |
| `-p 25003:5003` | 后台管理端口，映射到宿主机 25003 |
| `-v 本地:容器` | 路径映射，**冒号后面不要改**，冒号前面可自行修改 |
| `registry.kspeeder.com/...` | 镜像来自国内源，没有代理、没换镜像源也能拉下来 |
这里不会重复「鸡生蛋」的问题：用来加速的那个镜像本身走国内源，保证第一步一定能成功。
端口映射同理——冒号前面可改，冒号后面固定。如果 25443 或 25003 已被占用，把前面的数字换成别的，但后续访问后台和填写加速地址时都要跟着改。
## 第四步：打开 KSpeeder 后台
打开绿联桌面的 Docker，进入「容器」，可以看到 `kspeeder` 处于运行中。点击「快速访问」，选择 `25003` 端口：
1. 浏览器提示证书不受信任，点「高级」→「继续前往」。
2. 进入 KSpeeder 后台，可以看到实时下载速度、累计加速流量。
3. 后台标注的 Plus 为付费高速通道，免费版已足够日常使用。
## 第五步：把 KSpeeder 设为镜像加速地址
然后回到绿联桌面：Docker →「镜像」→ 右上角齿轮（设置）→「镜像仓库」→ 点击 `DockerHub` 一行的「加速器配置」→「+ 添加」，粘贴地址。
填写的完整地址为：
```text
https://registry.linkease.net:25443/
```
别的内容一律不改。点击「确定」，再点一次「确定」确认。
::: warning 注意
修改加速器配置会**重启 Docker 引擎**，正在运行的容器和下载任务会被中断。建议在没有任务运行时操作。
:::
早期版本的绿联加速器配置不支持带冒号端口的地址，需要额外做反向代理；现在已支持「域名:端口」的形式，直接填即可。
## 第六步：验证加速效果
回到终端，重新粘贴第一步的 OpenList 命令并回车。左侧 KSpeeder 后台会同步显示下载速度，实测瞬时可达 15MB/s，镜像很快下载并解压完成，容器也随之创建。
最后打开浏览器，访问：
```text
http://绿联NAS的IP:5544
```
例如 `http://192.168.31.121:5544`。能打开 OpenList 登录页，说明镜像拉取成功、容器运行正常。
## 总结
1. 看到 `registry-1.docker.io/v2` 连接超时，即可判定为镜像源问题，不必怀疑命令本身。
2. 三种方案按需选择：绿联自带的 1ms 加速最省事，代理依赖网络条件，KSpeeder 一次安装长期受益。
3. 加速地址必须改成 `https://registry.linkease.net:25443/`。
4. 修改加速器会重启 Docker 引擎，操作前先停掉正在进行的任务。
## 参考视频
[绿联NAS安装KSpeeder～解决Docker镜像拉取V2错误～](https://www.bilibili.com/video/BV1taj26RES7)
## 好用斋官网
[好用斋官网](https://haoyongzhai.com)｜[网盘分享](https://haoyongzhai.com/netdisk)
