---
title: 群晖NAS安装KSpeeder：解决Docker镜像无法拉取
description: 在群晖 NAS 上用 Docker 安装 KSpeeder 镜像加速服务，通过反向代理绕过群晖镜像仓库不支持端口的限制，解决 Docker 镜像无法拉取与 V2 错误。
outline: deep
category: 教程
date: 2026-10-21
tags:
- KSpeeder
- 群晖
- Docker
- 镜像加速
- NAS
readingTime: 6 分钟
---
# 群晖NAS安装KSpeeder：解决Docker镜像无法拉取
> 📺 本图文教程由视频整理而成，对应的参考视频：[群晖NAS安装KSpeeder~解决Docker镜像无法拉取V2错误~](https://www.bilibili.com/video/BV1V2ME6AETh)。如需查看更详细、更具体的操作演示，可观看原视频。
> 场景：群晖 NAS 上的 Container Manager 拉取镜像经常超时、报 V2 错误，可以安装一个本地镜像加速服务。KSpeeder 只需要一条 Docker 命令就能跑起来，但它要占用两个端口，而群晖的镜像仓库地址又只能填纯域名、不能带端口，所以还需要额外配一条反向代理。
> 提示：本教程配套的操作文档，可在[好用斋官网](https://haoyongzhai.com) → [网盘分享](https://haoyongzhai.com/netdisk)（提取码 572）中下载。
## 第一步：准备素材
下载本期的操作文档并解压打开。
文档分为四部分：KSpeeder 官方参考文档（[koolcenter.com/t/topic/9498](https://www.koolcenter.com/t/topic/9498)）、参考视频、安装命令、好用斋官网。官方文档用的是群晖图形界面安装容器的方式，喜欢图形界面的同学可以直接看它；本教程用的是命令方式，更省事，也更方便复制粘贴。
前置条件有两个，不清楚的可以先看这两期：
1. 群晖已安装 Container Manager。
2. 群晖已开启 SSH 功能，并能用终端工具连上。
## 第二步：创建数据目录
群晖的权限管理比一般系统严格得多。飞牛、绿联这类系统在执行 `docker run` 时，会自动创建路径映射中缺失的各级目录；群晖不会，**目录必须提前手动建好**，否则容器会因为挂载目录不存在而无法启动。
在终端里提权到 root：
```bash
sudo -i
```
输入密码后回车。注意 **Linux 输入密码时不显示任何字符**，看不到星号是正常的，输完直接回车即可。提示符从 `haoyong@DSM:~$` 变成 `root@DSM:~#`，说明已经拿到管理员权限。
然后创建两个目录，分别对应后面命令里的 data 与 config 挂载：
```bash
mkdir -p /volume1/docker/kspeeder/kspeeder-data
mkdir -p /volume1/docker/kspeeder/kspeeder-config
```
`mkdir -p` 可以「连同上级目录一起创建」：如果 `/volume1/docker/kspeeder` 这一层不存在，它也会一并建好。如果你想把数据放到别的路径，这两条命令和下一步命令里的路径要一起改。
## 第三步：运行 Docker 命令
在 root 提示符下粘贴并执行完整命令：
```bash
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 实际在用的端口。填完点「保存」，然后逐层关闭窗口。
::: warning 端口要成对修改
如果你在第三步把 `25443` 改成了别的端口，这里的「目的地端口」必须改成同一个数字，否则反代指向的端口没有服务在监听。
:::
飞牛和绿联的镜像仓库地址支持「域名 + 冒号 + 端口」的写法，直接填 `https://registry.linkease.net:25443` 就行，不需要这一步反代。
## 第五步：把 KSpeeder 设为镜像仓库
打开套件中心 → 已安装 → Container Manager → 打开，进入「镜像仓库」。
此时页面可能转圈一会儿，然后提示「无法连接到存储库」——**这是正常现象**，说明原来的 Docker Hub 直连已经不通了，正是需要加速的原因。
点击「设置」，里面有两个仓库：上面那个是自带的一批镜像源，速度一般；下面这个 `Docker Hub (v1)` 才是默认使用的仓库。选中下面这个，点「编辑」：
1. 勾选「启用镜像仓库镜像」。
2. 点「新增」，填入 `https://registry.linkease.net`，注意不用带端口。
3. 点「应用」，再点「确定」，等待提示「已更新镜像仓库」。
到这里 KSpeeder 就装完并生效了，之后在群晖里拉取镜像都会走本地加速。
## 第六步：验证加速效果
浏览器访问下面的地址，打开 KSpeeder 后台：
```text
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错误~](https://www.bilibili.com/video/BV1V2ME6AETh)
## 好用斋官网
[好用斋官网](https://haoyongzhai.com)｜[网盘分享](https://haoyongzhai.com/netdisk)
