Docker 镜像加速站搭建：基于 KSpeeder 多源私有缓存服务

一、项目简介

　　KSpeeder是一款高性能的Docker镜像智能加速工具，通过在本地或局域网内部署代理服务，解决因网络限制导致的镜像拉取缓慢、超时、失败等问题。

核心特性

智能并发拉取：可同时配置多个上游镜像源，并发拉取镜像层，大幅提升速度，无需境外服务器
断点续传与容错：支持自动断点续传，上游源故障时无缝切换
局域网共享：单次部署，团队共享，可作为局域网加速网关
标准兼容：完全兼容Docker Registry协议，无缝接入现有工作流

二、快速部署

2.1 使用Docker Compose部署

sudo tee ./docker-compose.yml > /dev/null <<'EOF'
services:
  kspeeder:
    image: registry.kspeeder.com/linkease/kspeeder:latest
    container_name: kspeeder
    ports:
      - "5443:5443"   # 主服务端口（HTTPS）
      - "5003:5003"   # 管理监控端口
    volumes:
      - ./kspeeder-data:/kspeeder-data     # 数据存储目录
      - ./kspeeder-config:/kspeeder-config # 配置文件目录
    restart: unless-stopped
    network_mode: bridge
EOF

2.2 启动并设置开机自启

# 1. 确保Docker守护进程开机自启
sudo systemctl enable docker

# 2. 启动KSpeeder容器
sudo docker compose up -d

# 3. 验证容器状态
sudo docker ps

三、基础配置

3.1 端口说明

端口	用途
`5443`	KSpeeder主服务端口（HTTPS）
`5003`	管理监控端口

3.2 数据卷说明

卷路径	用途
`/kspeeder-data`	镜像缓存数据存储
`/kspeeder-config`	配置文件目录（含`kspeeder.yml`）

四、客户端配置

4.1 配置Docker使用加速器

写入Docker配置文件：

sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
  "registry-mirrors": ["https://registry.linkease.net:5443"]
}
EOF

# 重启Docker使配置生效
sudo systemctl restart docker

4.2 验证配置

# 查看镜像加速器地址是否生效
sudo docker info | grep -A 1 "Registry Mirrors"

# 测试拉取镜像
sudo docker pull registry.linkease.net:5443/library/alpine

五、局域网共享加速

5.1 方案一：Hosts文件直连

在需要使用加速的客户端上，修改hosts文件将域名指向KSpeeder服务器。

# 假设KSpeeder服务器内网IP为192.168.25.209
echo "192.168.25.209 registry.linkease.net" | sudo tee -a /etc/hosts

5.2 方案二：添加不安全的私有仓库

sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
  "registry-mirrors": ["https://192.168.25.209:5443"],
  "insecure-registries": ["192.168.25.209:5443"]
}
EOF

sudo systemctl restart docker

5.3 方案三：Nginx反向代理（正式环境）

准备好域名和SSL证书，可通过Nginx提供更规范的HTTPS服务。

创建Nginx配置：

sudo tee /etc/nginx/conf.d/hub.conf > /dev/null <<'EOF'
server {
    listen 443 ssl;
    server_name hub.hx99.net;

    ssl_certificate /etc/nginx/ssl/hub.hx99.net_bundle.crt;
    ssl_certificate_key /etc/nginx/ssl/hub.hx99.net.key;

    location / {
        # 代理到内网的KSpeeder服务
        proxy_pass https://192.168.25.209:5443/;
        
        # 【关键】传递KSpeeder期望的Host头
        proxy_set_header Host registry.linkease.net;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 忽略上游证书错误（因内网IP证书通常不匹配）
        proxy_ssl_verify off;
        proxy_ssl_server_name on;
        proxy_ssl_name registry.linkease.net;  # 指定上游证书域名
        
        # 禁用缓冲以提高流式传输效率
        proxy_buffering off;
        proxy_request_buffering off;
    }
}
EOF

验证并重载Nginx：

sudo nginx -t && sudo systemctl reload nginx

验证代理服务：

curl https://hub.hx99.net/v2/

✅ 正常响应：显示 {} 表示服务正常运行。

客户端配置：

Docker加速器地址修改：

sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
  "registry-mirrors": ["https://hub.hx99.net"]
}
EOF

#重启
sudo systemctl restart docker

# 测试拉取
sudo docker pull hub.hx99.net/library/alpine

Docker 镜像加速源一键配置脚本：

https://gitee.com/cncsrf/internal-apt-yum/blob/master/docker.sh

六、高级配置

6.1 自定义上游镜像源

KSpeeder支持同时配置多个上游镜像源，实现并发拉取。配置文件位于./kspeeder-config/kspeeder.yml。

具体参照：https://www.koolcenter.com/t/topic/62

修改配置文件(注意路径和前面对应)：

sudo tee ./kspeeder-config/kspeeder.yml > /dev/null <<'EOF'
# KSpeeder 上游镜像源配置
mirrors:
  - url: "https://docker.1ms.run"
  - url: "https://docker.m.daocloud.io"
  - url: "https://docker.m.ixdev.cn"
  - url: "https://dockerproxy.net"
  - url: "https://docker.1panel.live"
EOF

重启容器使配置生效：

docker restart kspeeder

6.2 验证多源并发

拉取一个大镜像观察速度提升：

# 拉取一个较大的镜像进行测试
time sudo docker pull hub.hx99.net/library/node:18

七、运维与排错

7.1 常用管理命令

# 查看日志
sudo docker logs kspeeder

# 实时追踪日志
sudo docker logs -f kspeeder

# 重启服务
sudo docker compose restart

# 停止服务
sudo docker compose down

# 更新镜像（拉取新版本后重启）
sudo docker compose pull
sudo docker compose up -d

7.2 常见问题排查

现象	可能原因	解决方法
`dial tcp 127.0.0.1:5443: connect: connection refused`	KSpeeder容器未运行	`sudo docker ps`检查容器状态
`x509: certificate signed by unknown authority`	证书信任问题	添加`"insecure-registries": ["hub.hx99.net"]`到`daemon.json`
`403 Forbidden`	Host头传递错误	检查Nginx配置中的`proxy_set_header Host`
拉取速度无明显提升	上游源配置过少	在`kspeeder.yml`中添加更多上游源

八、总结

通过本文档，已完成：

✅ KSpeeder服务的快速部署
✅ Docker客户端配置与验证
✅ 局域网共享加速的两种实现方案
✅ 多上游源配置与并发拉取优化

KSpeeder作为团队内部的Docker加速器，可显著提升镜像拉取效率，保障CI/CD流程稳定性。如有更多需求，请参考官方文档。