查看“︁如何在搬瓦工服务器上搭建私有镜像加速器”︁的源代码

在国内网络环境下，拉取 Docker Hub 的官方镜像经常遇到速度极慢、连接超时，甚至完全无法下载的情况。虽然可以使用阿里云、腾讯云等公共加速器，但它们有时也会因为种种原因不稳定。

现在有个比较稳妥的方案，就是用你手中线路优秀的 '''搬瓦工 ( CN2 GIA 线路）'''，搭建一个属于自己的 '''Docker Registry Proxy（镜像缓存代理）'''。

它的工作原理是：

# 本地（NAS/电脑）请求你的 VPS。
# VPS 帮你去 Docker Hub 拉取镜像。
# VPS 将镜像缓存在本地硬盘。
# 下次再拉取同样的镜像，直接从 VPS 缓存读取，速度飞快。

这篇教程将教你在一台全新的 Debian/Ubuntu VPS 上，从零开始部署这个神器。

== 准备工作 ==

* 服务器：一台 搬瓦工 VPS（推荐 Debian 11/12 或 Ubuntu 20.04/22.04）。
* 端口：确保防火墙放行 5000 端口。

----

== 第一步：系统初始化与环境安装 ==
作为一台全新的机器，首先要确保系统软件是最新的，并安装必要的基础工具。
 # 1. 更新软件包列表并升级系统
 sudo apt update && sudo apt upgrade -y
 
 # 2. 安装基础工具 (vim, curl, wget, git)
 sudo apt install -y vim curl wget git apache2-utils</code>
''注意：<code>apache2-utils</code> 是为了后续生成密码文件使用，它包含 <code>htpasswd</code> 工具。''
----

== 第二步：安装 Docker 环境 ==
我们需要官方最新版的 Docker Engine 来运行 Registry 容器。
 # 1. 卸载可能存在的旧版本
 '''for''' pkg '''in''' docker.io docker-doc docker-compose podman-docker containerd runc; '''do''' sudo apt-get remove $pkg; '''done'''
 
 # 2. 添加 Docker 官方 GPG 密钥
 sudo install -m 0755 -d /etc/apt/keyrings
 sudo curl -fsSL <nowiki>https://download.docker.com/linux/debian/gpg</nowiki> -o /etc/apt/keyrings/docker.asc
 sudo chmod a+r /etc/apt/keyrings/docker.asc
 
 # 3. 添加 Docker 软件源
 echo \
   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] <nowiki>https://download.docker.com/linux/$(</nowiki>. /etc/os-release && echo "$ID") \
   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
 # 4. 更新源并安装 Docker
 sudo apt update
 sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
 
 # 5. 启动并设置开机自启
 sudo systemctl start docker
 sudo systemctl enable docker</code>
----

== 第三步：规划目录与配置 Registry ==
我们将使用官方的 <code>registry:2</code> 镜像。核心在于修改它的配置文件，使其工作在“Proxy（代理）”模式，而不是普通的存储模式。

=== 1. 创建工作目录 ===
 sudo mkdir -p /opt/docker-registry/data
 sudo mkdir -p /opt/docker-registry/config
 cd /opt/docker-registry</code>

=== 2. 编写 Registry 配置文件 ===
使用 <code>vim</code> 创建配置文件：
 sudo vim config/config.yml</code>
按 <code>i</code> 进入编辑模式，粘贴以下内容：
 version: 0.1
 log:
   fields:
     service: registry
 storage:
   cache:
     blobdescriptor: inmemory
   filesystem:
     rootdirectory: '''/var/'''lib/registry
   delete:
     enabled: true
 http:
   addr: :5000
   headers:
     X-Content-Type-Options: [nosniff]
 # 核心配置：代理模式
 proxy:
   # 目标地址：Docker Hub 官方地址
   remoteurl: <nowiki>https://registry-1.docker.io</nowiki></code>
配置解读：

* <code>storage</code>: 镜像缓存存储的位置。
* <code>proxy</code>: 这一段告诉 Registry，如果在本地找不到镜像，就去 <code>remoteurl</code> 拉取并缓存下来。

保存并退出（按 <code>Esc</code>，输入 <code>:wq</code>，回车）。
----

== 第四步：配置访问密码（可选但推荐） ==
如果不设置密码，互联网上任何人都能通过你的 IP 消耗你的 VPS 流量。为了安全，我们设置一个简单的 Basic Auth。

=== 1. 生成密码文件 ===
将 <code>your_username</code> 替换为你想要的用户名（例如 <code>admin</code>）：
 # 在 config 目录下生成 htpasswd 文件
 cd /opt/docker-registry/config
 sudo htpasswd -Bc htpasswd your_username</code>
系统会提示你输入并确认密码。

=== 2. 修改 config.yml 启用认证 ===
再次编辑配置文件：
 sudo vim config.yml</code>
在 <code>http:</code> 字段下增加 <code>auth</code> 配置，注意缩进格式：
 http:
   addr: :5000
   headers:
     X-Content-Type-Options: [nosniff]
   # 新增以下内容
   auth:
     htpasswd:
       realm: basic-realm
       path: '''/etc/'''docker'''/registry/'''htpasswd</code>
保存并退出 (<code>:wq</code>)。
----

== 第五步：编写 Docker Compose 启动文件 ==
回到 <code>/opt/docker-registry</code> 根目录，创建启动文件。
 cd /opt/docker-registry
 sudo vim compose.yaml</code>
粘贴以下内容：
 version: '3'
 services:
   registry:
     restart: always
     image: registry:2
     ports:
       - "5000:5000"
     volumes:
       # 挂载我们刚才写的配置文件
       - .'''/config/'''config.yml:'''/etc/'''docker'''/registry/'''config.yml
       # 挂载密码文件
       - .'''/config/'''htpasswd:'''/etc/'''docker'''/registry/'''htpasswd
       # 挂载数据目录（缓存的镜像存这）
       - ./data:'''/var/'''lib/registry</code>
保存并退出 (<code>:wq</code>)。
----

== 第六步：启动服务与测试 ==
 # 启动容器
 sudo docker compose up -d
 
 # 查看日志确保没有报错
 sudo docker compose logs -f</code>
如果看到 <code>listening on [::]:5000</code> 字样，说明服务启动成功。按 <code>Ctrl+C</code> 退出日志查看。
----

== 第七步：在客户端（本机/NAS）使用 ==
由于我们搭建的是 HTTP 服务（没有配置 SSL 证书），Docker 默认禁止连接非 HTTPS 的仓库。我们需要在客户端配置“不安全的注册表”。

=== 1. 修改客户端 Docker 配置 ===
在你的本地电脑、NAS 或另一台国内服务器上：

编辑 <code>/etc/docker/daemon.json</code> (Linux) 或在 Docker Desktop 设置中找到 Daemon 配置。

加入 <code>"insecure-registries"</code> 字段：
 {
   "registry-mirrors": [],
   "insecure-registries": [
     "你的VPS_IP:5000"
   ]
 }</code>
重启本地 Docker：
 sudo systemctl restart docker</code>

=== 2. 测试拉取镜像 ===
现在，尝试通过你的 IP 拉取一个镜像。假设你的 VPS IP 是 <code>1.2.3.4</code>，用户名是 <code>admin</code>，密码是 <code>123456</code>。

先登录（如果设置了密码）：
 '''docker''' login 1.2.3.4:5000 -u admin -p 123456</code>
拉取镜像： 原本的命令是 <code>docker pull nginx</code>，现在需要加上你的 IP 前缀：
 '''docker''' pull 1.2.3.4:5000/library/nginx</code>
''注意：官方镜像（如 nginx, mysql）属于 library 组，所以要加上 <code>/library/</code>。如果是第三方镜像（如 <code>mysql/mysql-server</code>），则直接替换为 <code>1.2.3.4:5000/mysql/mysql-server</code>。''
[[Category:500 常见应用指南 — Application Guides]]