群晖NAS安装KSpeeder：解决Docker镜像无法拉取

📺 本图文教程由视频整理而成，对应的参考视频：群晖NAS安装KSpeeder~解决Docker镜像无法拉取V2错误~。如需查看更详细、更具体的操作演示，可观看原视频。

场景：群晖 NAS 上的 Container Manager 拉取镜像经常超时、报 V2 错误，可以安装一个本地镜像加速服务。KSpeeder 只需要一条 Docker 命令就能跑起来，但它要占用两个端口，而群晖的镜像仓库地址又只能填纯域名、不能带端口，所以还需要额外配一条反向代理。

提示：本教程配套的操作文档，可在好用斋官网 → 网盘分享（提取码 572）中下载。

第一步：准备素材

下载本期的操作文档并解压打开。

文档分为四部分：KSpeeder 官方参考文档（koolcenter.com/t/topic/9498）、参考视频、安装命令、好用斋官网。官方文档用的是群晖图形界面安装容器的方式，喜欢图形界面的同学可以直接看它；本教程用的是命令方式，更省事，也更方便复制粘贴。

前置条件有两个，不清楚的可以先看这两期：

1. 群晖已安装 Container Manager。
2. 群晖已开启 SSH 功能，并能用终端工具连上。

第二步：创建数据目录

群晖的权限管理比一般系统严格得多。飞牛、绿联这类系统在执行 docker run 时，会自动创建路径映射中缺失的各级目录；群晖不会，目录必须提前手动建好，否则容器会因为挂载目录不存在而无法启动。

在终端里提权到 root：

sudo -i

输入密码后回车。注意 Linux 输入密码时不显示任何字符，看不到星号是正常的，输完直接回车即可。提示符从 haoyong@DSM:~$ 变成 root@DSM:~#，说明已经拿到管理员权限。

然后创建两个目录，分别对应后面命令里的 data 与 config 挂载：

mkdir -p /volume1/docker/kspeeder/kspeeder-data
mkdir -p /volume1/docker/kspeeder/kspeeder-config

mkdir -p 可以「连同上级目录一起创建」：如果 /volume1/docker/kspeeder 这一层不存在，它也会一并建好。如果你想把数据放到别的路径，这两条命令和下一步命令里的路径要一起改。

第三步：运行 Docker 命令

在 root 提示符下粘贴并执行完整命令：

docker run -d \
  --name kspeeder \
  --restart unless-stopped \
  -v /volume1/docker/kspeeder/kspeeder-data:/kspeeder-data \
  -v /volume1/docker/kspeeder/kspeeder-config:/kspeeder-config \
  -p 25443:5443 \
  -p 25003:5003 \
  registry.kspeeder.com/linkease/kspeeder:latest

各参数的含义：

参数	说明
-d	容器在后台运行
--name kspeeder	容器名称，可自定义
--restart unless-stopped	重启策略，群晖用这个即可
-v 本地:容器	路径映射，冒号后面不要改，冒号前面可以自行修改
-p 25443:5443	5443 是真正拉取镜像用的端口，映射到宿主机的 25443
-p 25003:5003	5003 是后台管理端口，映射到宿主机的 25003
registry.kspeeder.com/...	镜像地址，走国内镜像源，保证这个「用来加速的镜像」自己能拉下来

端口映射同样是「冒号后面固定、冒号前面可改」。如果 25443 或 25003 已经被占用，把冒号前面的数字换成别的即可，但后面配置反向代理和访问后台时，都要跟着换成新端口。

建议路径和端口都跟教程保持一致：后续再装懒人包等教程时，一旦出问题，方便直接对照排查。

回车后会自动拉取镜像并创建容器，速度很快。可以打开 Container Manager →「容器」，看到 kspeeder 状态为绿色，即表示启动成功。

第四步：设置反向代理

这一步是群晖特有的，也是最容易卡住的地方。

原因是：群晖的镜像仓库地址只能填纯域名，不支持「域名:端口」的形式，而 KSpeeder 实际监听的是 25443 端口。所以需要先在群晖内部做一条反向代理，让 https://registry.linkease.net 的请求跳转到本机的 https://localhost:25443。

操作路径：控制面板 → 登录门户 → 高级 → 反向代理服务器 → 新增，按下表填写：

位置	项目	填写内容
来源	协议	HTTPS
来源	主机名	registry.linkease.net
来源	端口	443
目的地	协议	HTTPS
目的地	主机名	localhost
目的地	端口	25443

规则名称随意填，例如 kspeeder。「启用 HSTS」不用勾选。

这条规则可以理解为一次内部跳转：访问 https://registry.linkease.net（HTTPS 默认端口 443）的请求，会被转发到本机的 25443 端口，也就是 KSpeeder 实际在用的端口。填完点「保存」，然后逐层关闭窗口。

端口要成对修改

如果你在第三步把 25443 改成了别的端口，这里的「目的地端口」必须改成同一个数字，否则反代指向的端口没有服务在监听。

飞牛和绿联的镜像仓库地址支持「域名 + 冒号 + 端口」的写法，直接填 https://registry.linkease.net:25443 就行，不需要这一步反代。

第五步：把 KSpeeder 设为镜像仓库

打开套件中心 → 已安装 → Container Manager → 打开，进入「镜像仓库」。

此时页面可能转圈一会儿，然后提示「无法连接到存储库」——这是正常现象，说明原来的 Docker Hub 直连已经不通了，正是需要加速的原因。

点击「设置」，里面有两个仓库：上面那个是自带的一批镜像源，速度一般；下面这个 Docker Hub (v1) 才是默认使用的仓库。选中下面这个，点「编辑」：

1. 勾选「启用镜像仓库镜像」。
2. 点「新增」，填入 https://registry.linkease.net，注意不用带端口。
3. 点「应用」，再点「确定」，等待提示「已更新镜像仓库」。

到这里 KSpeeder 就装完并生效了，之后在群晖里拉取镜像都会走本地加速。

第六步：验证加速效果

浏览器访问下面的地址，打开 KSpeeder 后台：

http://群晖IP:25003

25003 就是第三步里映射的后台端口。页面会显示当前的下载速度、累计加速流量，以及 Docker 加速配置指南。后续拉镜像时，可以在这里看到实时速度和具体流量。

两个小提醒：

1. 速度显示有延迟。 实际已经开始下载后，后台可能要等十几二十秒才显示数字，看到 0 B/s 不用着急，多等一会儿即可。
2. Plus 会员不必需。 后台标注的 Plus 是付费加速通道，普通用户免费版的速度已经足够日常使用，有需要再支持。

总结

1. 群晖上装容器，先手动 mkdir -p 建好挂载目录，否则容器起不来。
2. 一条 docker run 启动 KSpeeder，端口映射记住 25443→5443（拉镜像）与 25003→5003（后台）。
3. 群晖镜像仓库地址只能填纯域名，所以必须配反向代理把域名 443 转到本机 25443。
4. 最后在 Container Manager 的镜像仓库设置里启用镜像仓库镜像并填入 https://registry.linkease.net。

参考视频

群晖NAS安装KSpeeder~解决Docker镜像无法拉取V2错误~

好用斋官网

好用斋官网｜网盘分享