自建GitHub镜像站实战：从Nginx反代到Cloudflare Workers

1. 为什么我会去搭一个自己的GitHub镜像站

先说个真实经历。之前我在公司内网服务器上做持续集成，每次构建都要从 GitHub 拉代码。白天还好，一到下午和晚上，git clone 和 git pull 就开始抽风，一个几十 MB 的仓库能卡到超时，最后只能让同事手动把仓库上传到内网。那段时间我一直在找各种临时办法——今天用这个镜像站，明天换那个加速地址，后天镜像站本身又把仓库文件给截断了。折腾了半个月，我终于意识到：与其天天求人，不如自己搭一个 GitHub 镜像站。

这篇文章就是把我从选型、规划到最终落地全过程的经验整理出来。我会讲清楚镜像站的不同形态分别适合什么场景，也会给出可以直接抄的 Nginx 配置、Cloudflare Workers 脚本，以及搭建完之后的日常维护和排错思路。无论你是个人开发者想解决自己频繁访问 GitHub 时的不稳定问题，还是团队里负责基础设施建设、想给内网同学提供一个稳定的代码拉取入口，这篇文章都适用。读完你至少能判断出自己到底需要哪种方案，并且能照着配置把它跑起来。

先说结论：自建镜像站并没有想象中那么复杂。它本质上就是"帮别人去 GitHub 上取资源，再把取到的内容转交给你"。但不同的取法、不同的转交方式，决定了这个站最终是轻量够用还是稳定扛打。下面我把整个思考过程和实操细节都展开讲。

2. 镜像站的几种形态，先弄清楚你要的是哪一种

很多人一听"搭镜像站"，第一反应是搞一台大带宽服务器，装个 Nginx 把所有流量转发到 GitHub。这确实是方案之一，但绝对不是唯一的方案，而且对大多数人来说也不是最优解。我见过不少一上来就买服务器、结果搭完发现访问量小得可怜、带宽和磁盘全浪费的例子。所以选型之前，先把形态理清楚。

2.1 全站反向代理型：最正统的镜像站

这种方案的思路很直白：你提供一个域名，用户访问这个域名时，Nginx 把请求原封不动转发到 github.com，拿到响应后再返回给用户。GitHub 页面上的仓库列表、代码浏览、Issue、Release 下载，全都能通过这一层中转来访问。

优点是功能完整，几乎等于一个"换了个域名的 GitHub"。缺点是你要处理的东西很多：DNS 解析、TLS 证书、缓存策略、页面里的链接改写、多域名转发（GitHub 的资源分散在 raw.githubusercontent.com、codeload.github.com、objects.githubusercontent.com 等多个域名下），以及大文件下载时的连接稳定性。这套方案适合团队内网长期使用，也适合对 GitHub 访问体验有硬性要求的场景。

2.2 边缘函数型：不想买服务器的人选这个

如果你只是自己用，或者给几个人用，完全没必要养一台服务器。用 Cloudflare Workers 这类边缘函数就能实现一个轻量镜像站。它的原理是在 Cloudflare 的边缘节点上跑一段 JavaScript，收到请求后帮你把请求转发给 GitHub，再把响应原样返回。

这个方案几乎零成本（免费额度对个人足够），部署也简单，而且因为 Cloudflare 本身有全球节点，速度通常比单点服务器更快。缺点也明显：免费版对单次请求的响应体大小有限制，碰到大文件、大仓库归档包容易失败；另外你部署的是公开代码，容易被别人薅来当公共镜像用，消耗你的免费额度。

2.3 静态资源取巧型：只解决下载问题

如果你真正烦的不是浏览 GitHub 页面，而是 raw 文件下载慢、Release 资源拉不动，那甚至不需要搭一个"站"。把静态资源 URL 替换成 jsDelivr 之类的公共 CDN，就能解决大部分问题。

jsDelivr 可以加载 GitHub 仓库里的文件，格式是 https://cdn.jsdelivr.net/gh/用户名/仓库名@版本号/文件路径。它自带全球 CDN 加速，而且对开源项目免费。缺点是它不是完整镜像——你只能拿到仓库里的文件内容，不能浏览仓库页面，也不能 clone 整个仓库。另外它对文件大小有限制（超过 20MB 的文件不会缓存）。所以这个方案只能作为补充，不能替代真正的镜像站。

2.4 内部 DNS 改写型：最讨巧但不是镜像站

还有一种思路是直接在内部 DNS 或操作系统的 hosts 文件里，把 github.com 以及其他 GitHub 子域名解析到固定的、访问质量更好的 IP 地址。这严格来说不算镜像站，但很多人把它和镜像站混为一谈。

它的本质是改善 DNS 解析路径。GitHub 本身在全球有多个节点，不同地区访问同一个域名时，DNS 返回的 IP 可能不一样，解析到离你更近或网络质量更好的节点，访问体验会明显提升。这个方案的优点是几乎零成本、零维护，缺点是 IP 地址会有变动、不同网络环境下效果天差地别，而且只优化连接路径，不解决带宽瓶颈。作为临时手段可以，长期依赖不推荐。

做一个简单的对比总结：

以我个人的经验，绝大多数人的真实需求落在"自己用"和"小团队用"之间，所以本文后面会重点讲 Nginx 方案和 Cloudflare Workers 方案。前者做主力，后者做应急备份。

3. 动手前要准备的几件事

方案定下来之后，先别急着开终端。有几件前置工作没做好，后面会反复返工。

3.1 域名与证书

镜像站必须有一个自己的域名，原因很简单：如果你直接拿 IP 访问，GitHub 返回的资源链接都是带域名的，浏览器和 git 客户端会不认。而且你还要给这个域名配 TLS 证书，否则现代操作系统和浏览器会拦截大部分请求。

证书申请我建议直接用 Let's Encrypt，免费、自动续期，配合 certbot 或 acme.sh 都行。唯一要注意的是：国内某些网络环境下，从服务器上发起证书签发请求时，DV 校验过程可能不稳定。解决办法是给你的服务器配置一个可靠的 DNS 服务商，并保证 80 端口能从外网访问，你只需要在签发时放行一次即可。

3.2 服务器选型与带宽评估

Nginx 反向代理方案对服务器性能的要求其实很低——GitHub 页面本身是动态生成的，你的服务器只是做转发和短时缓存，CPU 和内存消耗都不大。真正的瓶颈在带宽。

我自己常用的评估方法是：如果你主要是个人使用，看代码、下小文件，一台 1 核 1G 内存、带宽 5Mbps 的小机器就绰绰有余。如果是要给十几个人同时用，尤其是有人会在上面做 git clone 和 git pull，带宽建议至少 30Mbps 起步，磁盘至少留 50G 给缓存。为什么缓存这么重要？因为同一份代码仓库、同一个 Release 文件，很可能在一周内被多人反复拉取，命中缓存就不需要再次请求 GitHub，响应速度和带宽消耗都会好看很多。

3.3 磁盘与缓存目录规划

缓存目录建议单独挂载，别和系统盘混在一起。我踩过一次坑：默认把缓存放在 /var/cache/nginx 下，结果系统盘被撑满，Nginx 直接罢工。后来我把缓存目录挪到独立的数据盘上，顺便设置了 max_size 和 inactive 参数，控制缓存总量和过期时间，这个问题才算根治。后面正文部分会给出完整配置。

4. Nginx 反向代理方案：生产环境可用的完整配置

这是本文最核心的部分。我会先给出一套能直接跑起来的基础配置，然后解释每个关键配置项的原理，再补充分域名转发和链接改写这些容易被忽略的细节。

4.1 基础 server 块配置

以我用得最顺手的配置为例，假设你的镜像域名叫 gh.example.com：

nginx复制proxy_cache_path /data/nginx-cache/github levels=1:2 keys_zone=github_cache:512m max_size=50g inactive=30d use_temp_path=off;

server {
    listen 443 ssl http2;
    server_name gh.example.com;

    ssl_certificate     /etc/letsencrypt/live/gh.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gh.example.com/privkey.pem;

    # 只对 GET 和 HEAD 做缓存
    proxy_cache github_cache;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    proxy_cache_valid 200 206 302 10m;
    proxy_cache_valid 404 1m;
    proxy_cache_lock on;
    proxy_cache_lock_timeout 5s;

    location / {
        proxy_pass https://github.com;
        proxy_set_header Host github.com;
        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;

        # 与 GitHub 建立连接的 TLS 参数
        proxy_ssl_server_name on;
        proxy_ssl_name github.com;

        # 超时参数，宁可长一点，别让大仓库下载中途断掉
        proxy_connect_timeout 10s;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;

        # 大文件临时缓冲调整
        proxy_max_temp_file_size 2048m;
    }
}

解释几个容易被忽略的点：

第一，proxy_cache_path 里的 levels=1:2 表示缓存文件分两级存放，避免单个目录里文件太多导致查找变慢。keys_zone 后面跟的 512m 是内存中的缓存索引大小，对 GitHub 这种海量 URL 的场景，512M 够用。max_size=50g 是缓存总容量上限，inactive=30d 表示 30 天没被访问的缓存会被清理。

第二，proxy_cache_key 我特意把 $request_method 放进去，是因为 POST 请求（比如登录、提 Issue）绝不能命中缓存。虽然 Nginx 默认不会缓存 POST，但写清楚更保险。

第三，proxy_pass https://github.com 这一行，表面上是把请求转发过去，但有一个关键点：你访问的是 gh.example.com，而 Nginx 转发时需要使用 SNI 与 GitHub 的服务器完成 TLS 握手。所以必须有 proxy_ssl_server_name on 和 proxy_ssl_name github.com。如果不设置这两行，有的网络环境下握手会失败，表现为白屏或 502。这是我最开始搭镜像站时踩到的一个坑，排查了很久才定位到。

4.2 多域名转发：GitHub 的资源不只在一个域名下

很多人以为配好 github.com 就完事了，直到打开一个仓库页面，发现头像加载不出来、Release 下载链接点不动，才发现问题。原因是 GitHub 把资源分散到了多个域名下：

所以你的镜像站最好把这几个域名也一起反代。每个域名单独写一个 server 块，配置基本一样，只改域名和 proxy_pass。我简单列一个模板：

nginx复制server {
    listen 443 ssl http2;
    server_name raw.gh.example.com;

    ssl_certificate     /etc/letsencrypt/live/gh.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gh.example.com/privkey.pem;

    location / {
        proxy_pass https://raw.githubusercontent.com;
        proxy_set_header Host raw.githubusercontent.com;
        proxy_ssl_server_name on;
        proxy_ssl_name raw.githubusercontent.com;
        proxy_read_timeout 300s;
    }
}

这里有个细节：raw.githubusercontent.com 下的 URL 通常不带版本号之类的动态参数，而且是纯静态文件，缓存策略可以激进一点。你可以把 proxy_cache_valid 设长一些，比如 200 30d，这样同一个文件只要被缓存一次，后续访问全部走本地磁盘，速度和稳定性都提升一大截。

另外，GitHub 页面上返回的 HTML 里，资源 URL 会写成 https://raw.githubusercontent.com/... 这种绝对路径。如果你只反代了 github.com，用户复制下来的链接还是会指向 GitHub 官方域名，直连又变慢。解决办法就是在 HTML 返回时做文本替换，也就是下面要说的 sub_filter。

4.3 页面内链接改写：让浏览器认你的域名

sub_filter 是 Nginx 内置的一个模块，可以在响应内容返回给用户之前，把字符串替换掉。我的做法是把页面 HTML 里的 GitHub 官方域名全部替换成自己的镜像域名：

nginx复制location / {
    sub_filter_once off;
    sub_filter 'https://github.com/' 'https://gh.example.com/';
    sub_filter 'https://raw.githubusercontent.com/' 'https://raw.gh.example.com/';
    sub_filter 'https://codeload.github.com/' 'https://codeload.gh.example.com/';
    sub_filter 'https://objects.githubusercontent.com/' 'https://objects.gh.example.com/';
}

sub_filter_once off 表示对响应体里所有匹配的地方都做替换，而不是只替换第一次出现的。

这里有个比较隐蔽的坑：GitHub 的 HTML 是压缩传输的，也就是 Content-Encoding 为 gzip 或 br。如果打开压缩，sub_filter 就匹配不到内容，替换不生效。所以你需要把对应响应也做压缩处理。最省事的办法是在服务端关闭响应压缩或统一做解压再压缩，但我个人更推荐直接让 Nginx 在替换前解压、替换后再压缩。这一套逻辑 Nginx 原生不太好做，我当时用了一个取巧的办法：在 sub_filter 的这个 location 里不设置 gzip 相关指令，让 Nginx 对上游的压缩响应自动处理，实测大多数情况下 sub_filter 能正常工作，但偶尔会出现替换不干净。后来我在 Nginx 前加了一层内容透明代理才彻底解决。

如果你不想引入额外组件，还有个折中方案：只保证 git 操作和文件下载能用，页面浏览的链接改写做多少算多少。毕竟对多数人来说，镜像站最大的价值是 git clone 和 Release 下载，页面浏览只是附带的。

4.4 git 客户端的智能替换：一份配置管所有仓库

镜像站搭好之后，真正用得最顺手的一个技巧是 git 的 url.insteadOf 配置。它能让你的所有 git 命令自动把 github.com 开头的 URL 替换成镜像域名，极其省心。

在本地执行：

bash复制git config --global url."https://gh.example.com/".insteadOf "https://github.com/"

之后你再执行 git clone https://github.com/octocat/Hello-World.git，git 实际访问的地址会是 https://gh.example.com/octocat/Hello-World.git，但远端地址显示的还是原来的 GitHub 地址，团队协作时别人拉你的仓库也不会出问题。

这个配置只对 https:// 协议的 URL 生效，SSH 协议的地址不受影响。如果你的镜像站也反代了 SSH 端口，理论上也能配，但 SSH 需要额外的密钥管理和防火墙策略，非必要不建议在镜像站上开这个口子。

4.5 私有仓库与缓存安全的边界

镜像站最怕的一件事：缓存了带认证信息的私有仓库内容，然后被另一个没有权限的人通过缓存访问到。Nginx 默认对带 Authorization 请求头的请求是不做缓存的，这个行为是安全的。但如果你手动加了更激进的缓存策略，比如对 200 全部缓存，就必须小心了。

我的建议是，如果镜像站只服务公共仓库，那就完全没问题。如果团队成员需要拉私有仓库，建议在 Nginx 配置里加上：

nginx复制proxy_no_cache $http_authorization;
proxy_cache_bypass $http_authorization;

这两行的作用是：一旦请求带 Authorization 头，既不走缓存，也不写缓存。这样能保证私有仓库的内容永远不会被存入公共缓存。

5. Cloudflare Workers：不买服务器也能搭的轻量镜像

如果你只是个人使用，或者不想维护一台服务器，Cloudflare Workers 是很好的选择。我把它定位为"轻量应急方案"，它的使用场景是：配合 Nginx 方案做备用链路，或者作为日常主力但心态上接受偶尔的大文件下载失败。

5.1 为什么选 Workers

Workers 的好处是部署在全球边缘节点上，用户访问镜像域名时，请求从最近的地方进 Cloudflare 网络，再转发到 GitHub。免服务器、免域名备案、免 TLS 证书管理，Cloudflare 免费套餐的额度对个人使用来说非常充裕。

它的坏处是免费套餐对单次请求的响应体大小有限制。如果需要经常拉大仓库，走这个方案会很难受。我的建议是：Worker 镜像站只用于浏览、看 Issue、拉小文件。

5.2 一个可直接部署的 Worker 脚本

在 Cloudflare Workers 里新建一个脚本，替换成下面的内容：

javascript复制export default {
  async fetch(request) {
    const url = new URL(request.url);
    const targetHost = 'github.com';
    const targetUrl = 'https://' + targetHost + url.pathname + url.search;

    const headers = new Headers(request.headers);
    headers.set('Host', targetHost);

    // 构造转发请求
    const init = {
      method: request.method,
      headers: headers,
      body: ['GET', 'HEAD'].includes(request.method) ? undefined : request.body,
      redirect: 'manual'
    };

    const response = await fetch(targetUrl, init);

    // 处理重定向：把 Location 里的 github.com 替换成自己的镜像域名
    const newHeaders = new Headers(response.headers);
    const location = newHeaders.get('Location');
    if (location) {
      const selfHost = url.host;
      newHeaders.set('Location', location.replace(targetHost, selfHost));
    }

    return new Response(response.body, {
      status: response.status,
      statusText: response.statusText,
      headers: newHeaders
    });
  }
};

这里我做了两件核心事。第一，把请求的 Host 头改成 github.com，这样 GitHub 的服务器会认为请求是发给它自己的，返回正常页面。第二，处理重定向——GitHub 经常会把带 www 的地址重定向到 github.com，或者把某些路径重定向到其他子域名，如果你不做替换，用户访问镜像域名时会被踢回 GitHub 官方域名。

部署之后，你在 Cloudflare 控制台的 Workers 页面绑定自己的域名（比如 gh.example.com），再把 DNS 解析指过去，一个零成本的镜像站就跑起来了。

5.3 实用规避：哪些请求不适合走 Worker

免费 Worker 对响应体大小的硬限制绕不过去，所以我通常会在 Worker 脚本里加一个路径判断：针对 archive 和 releases/download 这类大文件路径，直接返回一个提示页或重定向回 GitHub 官方地址，避免请求失败后用户一头雾水。判断逻辑很简单：

javascript复制if (url.pathname.includes('/archive/') || url.pathname.includes('/releases/download/')) {
  return new Response('Large file downloads are not supported on this mirror. Please use official GitHub.', { status: 403 });
}

我知道直接返回 403 有点粗暴，但比起让用户等半天然后看到 Worker 错误页，这个处理反而更友好。如果你的 Worker 绑定的是专业套餐，对响应体大小的限制会宽松很多，大文件问题就不存在了。

6. 搭好之后的事：缓存维护、故障排查和安全边界

镜像站搭完、curl 能通、git clone 能成功，这只是开始。真正让它稳定运行一年、两年，需要处理的是后面这些问题。

6.1 缓存命中和过期策略怎么调

GitHub 页面的更新频率差异很大：仓库 README、文件列表会随提交变化，Release 文件和归档包则很少变动。所以缓存策略要按路径区分，而不是一刀切。

我现在用的策略是：

• HTML 页面（路径不带 .git、不带 /releases/）：缓存 10 分钟。太短会导致大量请求穿到 GitHub，起不到缓存作用；太长会导致页面内容陈旧。
• 静态资源（raw 下的文件、头像、githubassets 下的样式脚本）：缓存 7 到 30 天。
• Release 附件和归档包（/releases/download/、/archive/）：缓存 7 天。文件本身几乎不变，但为了及时拿到新版本，7 天比较稳妥。

配置上就是针对不同 location 写不同的 proxy_cache_valid。另外，我每周会跑一次磁盘占用检查：

bash复制du -sh /data/nginx-cache/github

如果发现缓存目录膨胀得很快，就看是不是有爬虫或误配置导致大量 URL 被写入了缓存。

6.2 常见故障：502 和超时

镜像站最常见的故障是 502 Bad Gateway。原因多半是上游连接失败，也就是你的服务器在访问 GitHub 时网络不稳定。排查思路是先在服务器上直接测：

bash复制curl -I https://github.com

如果这里就卡住或失败，说明问题出在上游网络，而不是 Nginx 配置。这种情况下可以给你的镜像站加一条备用上游——比如让 Nginx 在 proxy_pass 失败时切换到另一个域名的同 IP 转发，或者用 proxy_next_upstream 配置重试。

超时问题则更隐蔽。表现是用户下载一个大文件，下到一半连接断了。排查后发现是 proxy_read_timeout 太短。GitHub 的大文件走的是动态生成 + 重定向，中途可能会出现长时间的等待，Nginx 默认 60 秒的读超时不够用。我把 proxy_read_timeout 调到 300 秒之后，问题基本消失。

6.3 安全边界：别让镜像站变成公共节点

镜像站最容易忽略的问题是被人当作公共节点来用。一旦你的域名被公开出去，流量很快就上去，带宽被吃满，自己的正常使用反而受影响。

我的做法是在 Nginx 层做简单的访问控制：

nginx复制location / {
    allow 192.168.0.0/16;
    allow 10.0.0.0/8;
    deny all;
}

把访问限制在公司内部 IP 段或自己家的 IP 段。如果团队成员分布在多个地方，就用 HTTP Basic Auth，弱一点但能挡掉大部分顺手来薅的人。Cloudflare Workers 方案则可以用 Cloudflare Access 做身份验证，功能更完整。

我不建议把这套镜像站开放成公共互联网服务。原因有三：第一，带宽成本不可控；第二，GitHub 本身有使用条款，大量转发其内容到公网存在合规风险；第三，维护公共镜像需要做内容监控和滥用防护，工作量完全不是自用级别的。

6.4 一个长期运行的镜像站还需要什么

镜像站跑起来之后，有几件事值得长期做。

日志要定期看。Nginx 的 access log 里会暴露很多问题——某个路径频繁 404，可能是你的链接改写没覆盖到；某个 IP 疯狂拉取，可能是别人在拿你的站当下载器。我用一条命令快速统计访问量最高的路径：

bash复制awk '{print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20

证书要自动续期。Let's Encrypt 证书有效期是 90 天，光靠记日历肯定不靠谱。用 certbot 的 --installer nginx 模式，配合 systemd timer 或 crontab，让它每两个月自动跑一次续期。

监控要简单但不能没有。我写了一个最简单的健康检查脚本，每 5 分钟访问一次镜像站的首页，如果连续三次失败就重启 Nginx 服务并给自己发一条通知。这个脚本用 shell 写不超过 20 行，却是这套系统里性价比最高的东西。

最后说一个我在实际使用中体会到的小技巧：不要把镜像站当成唯一的访问路径。我本地仍然保留着直连 GitHub 的习惯，偶尔直连顺畅的时候就直接走官方，镜像站作为备用。这样既减少了镜像站的负载，也避免了对单一方案的过度依赖。镜像站真正的作用是兜底——在直连不稳定、临时需要快速拉取代码的场合，它让你不至于又被卡在"等待网络超时"的循环里。