GitHub镜像站搭建指南：用Nginx缓存加速源码与Release下载

做开发这些年，我发现一个特别常见的现象：明明源码在GitHub上放得好好的，可一到关键时候，clone个仓库慢得像蜗牛爬，发布包里动辄几百MB的依赖资源，下载到一半还给你断连。尤其是一个团队里几个人同时拉同一份代码，简直是在浪费生命。后来我索性把常用的GitHub资源做成了一套GitHub镜像站，团队内部、个人电脑、CI流程全都往这个通道上走，速度快了不少，带宽也省下来了。这篇文章不纸上谈兵，直接把我自己搭的一套镜像站方案完整拆开：怎么选型、怎么配转发、怎么加缓存、怎么让它在实际下载中真的又快又稳，踩过的坑也会一并写出来。无论你是刚接触GitHub的新手，还是负责团队基础设施的工程师，按着这篇文章的思路往下走，基本都能落地。

1. 先想清楚：镜像站到底解决什么问题

1.1 三个最痛的场景

先说最常见的情况。项目拉到后期，大家基本都被三类事情卡过时间。

一是大文件与发布包下载。GitHub Releases里放了不少二进制包、安装包、模型文件，动不动几百MB。这些文件不走Git协议，全是HTTP流式下载，如果链路质量一般，速度会忽高忽低。我之前碰到过一个内网团队，每次部署都要从Releases里拉一个600多MB的软件包，十几个人排队下载，一整天都在等。

二是团队重复拉取。三五个开发每天反复clone同一个仓库，每个人的机器都各自向GitHub发起一次完整请求。同一个仓库，同一条网络链路，同一个文件，被几十次重复下载，时间和带宽全浪费了。更无奈的是，这种浪费没有上限，新同事入职第一天就要把整套仓库克隆一遍。

三是CI/CD构建机需要拉源码。构建机每次构建都要重新从GitHub拉仓库，如果构建节点多，同一个源码包会在很短时间内被多个节点同时请求，构建排队时间肉眼可见地涨。构建失败重试时，仓库又要重新拉一遍。

镜像站的价值，就是把“每个人独立从GitHub拉取”变成“先从就近镜像拉，镜像服务器自己负责和GitHub保持同步”。把原本各走各路的请求，折叠成一个共享出口，在资源密集型研发场景里非常划算。这就好比你家里给每个房间都单独接了水管，水量自然紧张；不如先在小区入口修一个蓄水池，大家从这个池子里取水，水源压力就小很多。

1.2 三种形态怎么选

成熟一点的团队往往不止做一种镜像，但我建议你先从最低成本的开始。大致有这三类：

• 加速下载型：以转发加缓存为主，核心是缓存静态文件。部署简单，适合个人或团队内部。Git clone类操作也能覆盖，但需要把raw域名也一起处理。
• 仓库备份型：把某个开源仓库定期同步到自己的托管平台，比如Gitee、自建GitLab等，平时就用自己的仓库地址clone。可靠性高，但同步存在一定延迟。
• 企业缓存型：类似本地Git缓存服务，粒度更细，支持仓库级缓存和认证，适合构建机多的团队。部署成本高一点。

我把它们放在一起做了个对比。

我最终实践下来，最出效果的是“加速下载型”加一层“仓库备份”的组合。前者解决重文件下载，后者解决日常clone源码。这两种都不难，下面重点讲。

1.3 选型决策回看

早期我也做过一个过度设计：一开始就想上一套企业级Git缓存系统，结果配置了两个星期，团队成员还是习惯用原始地址。后来我调整了策略，先用一个最简单的Nginx转发跑起来，观察一周访问日志，发现流量集中在Releases下载和少量仓库的clone，这才明确优化方向。如果你刚接触这个领域，建议也别一上来就追求完美。先抓主要矛盾，能下载、能缓存、速度起来，就够了。

2. 核心细节与关键选型

2.1 域名、证书与解析顺序

镜像站必须绑定一个正式的域名。IP直连不是不行，但涉及SSL证书和SNI时非常麻烦。我用的是自己名下的二级域名，给镜像站单独开一个子域，例如mirror.example.com，同时给raw下载另开一个raw-mirror.example.com。域名解析先做好，把两个子域都指向服务器的公网IP，等解析生效后再去申请证书。

证书这块直接用Let's Encrypt免费证书，三个月自动续期，配合certbot的定时任务就能无感运行。申请证书时注意可以用DNS-01或HTTP-01，但多域名证书要用-D配合。我习惯给两个子域签一张SAN证书，这样管理起来省事。

这里有一个非常隐蔽的细节：GitHub的仓库页和raw下载是不同域名。如果只转发github.com，那么你在页面上点“Download ZIP”时，跳转链接可能指向codeload.github.com，这又是一层。所以在规划阶段，就把镜像域名的“影子域名”想好：一个主域名对github.com，一个raw域名对raw.githubusercontent.com，必要时再加一个codeload域名对codeload.github.com。否则配置到一半发现缺域名，来回补配置很容易漏。

2.2 转发工具选型：Nginx还是Caddy

这类需求最主流的方案是Nginx，配置语法大家都熟，缓存模块也完善。Caddy的优点是自动申请和续期证书，少写不少基础代码，但它在细粒度缓存策略上不如Nginx直观。我最后选了Nginx。如果你不想自己维护证书，可以在Nginx前面再套一层Caddy，让Caddy只负责终止TLS和转发，但那种组合更多余。直接Nginx加上certbot，简洁可靠。

我的取舍逻辑很简单：镜像站是长期运行的基础设施，Nginx更稳、排查手段更多。特别是proxy_cache机制，Nginx的命中状态能直接在响应头里看。Caddy虽然能配http.cache，但生态和文档还是差一截。

2.3 缓存策略设计

缓存是镜像站的核心，做得不好就只是“转发”，没有速度优势。我把缓存对象分成三类：

• Releases包、zip/tar包等大文件：这些是静态的，内容基本不变，可以放心缓存，缓存时间设置长一些，比如7天。
• 仓库页面HTML：需要看到更新，所以缓存时间要短，比如几十秒或直接关闭HTML缓存。如果你只是给内部拉代码，我建议干脆不缓存仓库首页那些HTML，避免看到旧版本。
• raw源文件、API响应：适中缓存，1到10分钟之间，避免过于频繁地穿透到源站。

在Nginx里，我用proxy_cache_path定义一个共享缓存目录，再按不同location设定proxy_cache_valid。具体参数在第3章的配置里会看到。这里先提一个坑：千万别把动态路径和静态文件放在同一个缓存层级里，否则一个带认证的请求被缓存下来，之后所有人拿到的都是过期内容。

2.4 动态请求与静态请求的分离

我在生产上见过不止一次翻车现场：把GitHub页面完整转发到内网镜像，结果页面上的HTML被长期缓存，README永远是三天前的。为什么？因为页面HTML里包含大量的动态元素，比如“Star数”“最近提交时间”，它们每次请求都可能不同。镜像站真正回报率高的是那些“不变资源”：Release压缩包、仓库内静态文件、raw文件。

所以我在设计时就做了切割：转发github.com的配置里，对HTML几乎不做长缓存；对Release下载路径做出长达7天的缓存。这样既不会误导用户，又能在重负载时保住下载通道的速度。这个思想也可以推广到其他任何“缓存型镜像”项目，不只是GitHub镜像站。

2.5 安全与防滥用

镜像站一旦用起来，很容易被搜索引擎或同事扩散出去，变成公共下载站。流量暴涨是小问题，源站可能因此限制你的IP，那才是大问题。我的建议：能内网就内网，开放到公网至少要做访问频率限制；限速条目也要配置，避免单用户把带宽吃满。可以在header里加一个“只允许指定Referer”的单级限制，但别只依赖header，因为命令行下载工具根本不带Referer。下面这些防护点我会在配置里逐个落地：

• limit_conn限制单IP并发连接数。
• limit_req限制请求频率。
• limit_rate对下载速度做上限。
• 配合Nginx的access_log做流量统计。

3. 从零动手：加速下载型镜像站实操

3.1 准备工作

一台能正常访问GitHub的服务器，这个是前提。如果只在内网使用，2核2G就够；如果要服务更多同事或CI节点，建议4核8G起。域名提前规划好，并完成DNS解析。系统用Ubuntu或Debian都可以，下面以Ubuntu 20.04为例。磁盘建议单独挂一个数据盘给缓存目录，因为缓存文件增长非常快。我第一次只用系统盘，两周后就报警了。

apt update apt install -y nginx nginx-extras certbot python3-certbot-nginx curl wget

nginx-extras是可选，但多了一些headers和缓存相关的扩展，建议装上。certbot用于申请证书，初学者建议直接用它绑定的Nginx插件，一条命令完成证书和Nginx配置改写。

3.2 准备证书

先用certbot把证书申请好。假设域名为mirror.example.com和raw-mirror.example.com：

certbot certonly --webroot -w /var/www/html \ -d mirror.example.com -d raw-mirror.example.com

成功后证书会放在/etc/letsencrypt/live/目录下。如果你不想手动配webroot，也可以直接运行：

certbot run -a standalone -d mirror.example.com -d raw-mirror.example.com

但standalone模式要求暂时停掉Nginx，或者先停掉80端口占用。我习惯用webroot方式，不影响在线服务。

3.3 转发配置：核心server块

下面是我实际用的核心配置，去掉无关冗余后是这个样子：

proxy_cache_path /data/cache levels=1:2 keys_zone=github_cache:10m max_size=20g inactive=7d use_temp_path=off; limit_conn_zone $binary_remote_addr zone=concurrent:10m; limit_req_zone $binary_remote_addr zone=req:10m rate=5r/s; server { listen 443 ssl http2; server_name mirror.example.com; ssl_certificate /etc/letsencrypt/live/mirror.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/mirror.example.com/privkey.pem; # 正常页面入口，对HTML短缓存 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_ssl_server_name on; proxy_ssl_name github.com; proxy_set_header Accept-Encoding ""; proxy_cache github_cache; proxy_cache_valid 200 301 30s; proxy_cache_key "$host$scheme$request_uri"; add_header X-Cache-Status $upstream_cache_status; limit_req zone=req burst=10 nodelay; } # Release大文件走长缓存 location ~* \.(zip|tar|gz|tgz|exe|dmg|pkg|deb|rpm|jar|whl|bin)$ { proxy_pass https://github.com; proxy_set_header Host github.com; proxy_set_header X-Real-IP $remote_addr; proxy_ssl_server_name on; proxy_ssl_name github.com; proxy_set_header Accept-Encoding ""; proxy_cache github_cache; proxy_cache_valid 200 301 7d; proxy_cache_key "$host$scheme$request_uri"; add_header X-Cache-Status $upstream_cache_status; limit_conn concurrent 5; limit_rate 100m; } }

有几个细节要重点解释。

第一，proxy_pass指向https://github.com后，客户端看到的URL还是mirror.example.com/xxx。但页面里如果硬编码了github.com绝对路径，浏览器会直接请求原始域名，绕开镜像。这也是为什么我建议镜像站只负责下载路径，不去转发完整页面。

第二，proxy_set_header Accept-Encoding ""的作用是关闭上游压缩。Nginx缓存的是上游返回的原始字节，如果源站根据客户端的不同Accept-Encoding返回不同内容，缓存键就会分裂。关掉压缩后，缓存命中率一下就上来了。

第三，add_header X-Cache-Status让响应头里带上缓存命中状态。我习惯在所有缓存配置里都加上这个头，排查问题太方便了，一个curl -I就能知道是命中还是穿透。

3.4 raw下载加速服务配置

git clone时从GitHub拉大对象，走的主要是raw.githubusercontent.com或codeload.github.com。给raw做一个独立子域，配置思路一样：

server { listen 443 ssl http2; server_name raw-mirror.example.com; ssl_certificate /etc/letsencrypt/live/mirror.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/mirror.example.com/privkey.pem; location / { proxy_pass https://raw.githubusercontent.com; proxy_set_header Host raw.githubusercontent.com; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_ssl_server_name on; proxy_ssl_name raw.githubusercontent.com; proxy_set_header Accept-Encoding ""; proxy_cache github_cache; proxy_cache_valid 200 301 24h; proxy_cache_key "$host$scheme$request_uri"; add_header X-Cache-Status $upstream_cache_status; } }

如果你愿意深度定制，还可以把仓库页和raw内容合并到同一个子域，用不同路径区分，比如/mirror/raw/。但这样会牵扯到Git内部把URL写进.git/config，改动成本高。我最终选了子域方案，直观、清晰、维护成本低。

3.5 用户侧使用方式

镜像站搭好之后，日常使用很简单。

浏览器下载Release包时，把下载URL里的github.com替换成mirror.example.com即可。举个例子，原地址是https://github.com/owner/repo/releases/download/v1.0/pkg.tar.gz，改成https://mirror.example.com/owner/repo/releases/download/v1.0/pkg.tar.gz，请求就会落到镜像站。首次请求穿透到GitHub并缓存，之后所有人命中的都是镜像本地文件。

git clone时，修改仓库的remote地址。可以一条命令切换到镜像：

git remote set-url origin https://raw-mirror.example.com/owner/repo.git

团队内部可以把这条命令写成一个config脚本，一键切换。也有人在.gitconfig里用url替换规则，把github.com统一映射到镜像地址，这个方案最省事：

git config --global url."https://raw-mirror.example.com/".insteadOf "https://github.com/"

这样一来，所有git命令里的github.com都被替换为镜像地址，团队成员无感就用了。

3.6 缓存清理与数据维护

缓存目录是/data/cache。跑几周后，几十GB很正常。我写了一个每天凌晨跑的cron脚本，清理7天未访问的缓存文件：

find /data/cache -type f -mtime +7 -delete

执行前建议先看看目录大小：

du -sh /data/cache

proxy_cache_path里已经有inactive=7d和max_size=20g，Nginx自己也会做回收，但cron是双保险。另外，清理缓存并不会影响命中率，因为Nginx会重新请求源站并把最新内容写回缓存。

3.7 与CI/CD构建机的联动

如果团队有CI/CD环境，镜像站接入的价值更大。以Jenkins为例，可以在构建脚本里把下载GitHub依赖的URL统一替换成镜像地址。也可以用环境变量管理，让构建脚本从配置中心读取镜像前缀。GitHub Actions如果想用这个镜像，需要在自建的runner上配置而不是在云端runner上，因为云端runner天然就在GitHub内部路线，再用镜像反而是绕远。

这里我分享一个真实做法：我自己的构建节点，所有pip、npm安装都走内部PyPI/npm缓存，只有源码包下载走GitHub镜像站。源码包路径通过替换规则统一改写，构建脚本几乎不用改。

3.8 自动化部署脚本参考

如果不想手动执行那么多命令，把整个过程写成一个脚本也是可以的。下面是一个简化的思路：

#!/bin/bash set -e DOMAIN=mirror.example.com RAW_DOMAIN=raw-mirror.example.com CACHE_DIR=/data/cache apt update apt install -y nginx nginx-extras certbot python3-certbot-nginx mkdir -p "$CACHE_DIR" # 写入上面两段Nginx配置后执行： nginx -t && systemctl reload nginx # 申请证书 certbot certonly --webroot -w /var/www/html -d "$DOMAIN" -d "$RAW_DOMAIN" # 配置自动续期 echo "0 3 * * * root certbot renew --quiet" >> /etc/crontab # 配置缓存清理 echo "5 4 * * * root find $CACHE_DIR -type f -mtime +7 -delete" >> /etc/crontab

脚本看起来简单，但实际落地时最关键的是Nginx配置文件的完整性，以及certbot的webroot路径要对。生产环境我建议一步步执行，脚本只做备份和重复部署用，别第一次就在生产服务器上直接跑。

4. 常见问题与排查技巧实录

4.1 502 Bad Gateway

现象是访问镜像站时直接报502。排查顺序：先curl -I https://mirror.example.com/，再直接在服务器上curl -I https://github.com确认源站通。如果是转发配置问题，多半是域名解析失败。Nginx转发到https时，上游域名必须能解析，可以在nginx.conf的http块里加：

resolver 8.8.8.8 114.114.114.114 valid=30s ipv6=off;

同时把proxy_pass里的域名解析提前，避免每次请求都重新解析。另一种常见原因：上游SSL握手失败，此时一定要保证proxy_ssl_server_name on;，否则SNI不携带目标域名，GitHub会找不到对应虚拟主机。

4.2 证书或Host头问题

如果你的镜像站访问时出现证书错误，多半是Nginx在向GitHub发起上游连接时，没有正确携带SNI或Host头。除了proxy_ssl_server_name on;，有时候还需要显式设置proxy_ssl_name github.com;。Host头也同样要用proxy_set_header Host github.com;。如果忘记这两项，表现是报错诡异的SSL错误、或者返回GitHub的404页面。

这类问题最容易发生在debug阶段，因为浏览器看到的镜像是自己的域名，证书校验是通过的，但后端连接到GitHub时用的是默认的逻辑，导致SNI不对。

4.3 缓存不命中或命中率低

可以加add_header X-Cache-Status，然后观察响应头。如果总是MISS，说明缓存键和请求路径不匹配。常见原因有两个：一个是带了动态cookie或query串导致缓存键变化；另一个是Accept-Encoding不同导致缓存键分裂。cookie问题可以通过proxy_cache_key只取URI解决，但我不建议忽略cookie，否则可能泄漏认证信息；自己的内网镜像可以把认证相关的路径排除掉。

真正让命中率下降的往往是Accept-Encoding，我上面已经提过，记得关掉压缩。还有一个容易被忽略的点：如果源站返回302跳转，Nginx默认不缓存302，而GitHub某些Release下载会先302到CDN。需要给302也设置一个合理的缓存时间，比如proxy_cache_valid 302 10s，或者直接让用户跟随跳转。

4.4 前端页面资源加载不全

如果你把github.com整个页面转发到自己的镜像域名，页面里的脚本、样式、图片却还是github.com的绝对地址，浏览器会被CSP和混合内容策略拦截。这是转发GitHub这种重前端站点的固有问题，没有一劳永逸的解法。我身边常见的做法是：镜像站只管静态文件和Release大文件，页面访问还是直接用GitHub本身。既绕开麻烦，又保住下载加速的核心诉求。

如果想要完整保存一个GitHub页面的快照，可以用wget镜像整站，但那是另一套逻辑，这里不展开。

4.5 日志监控与性能观测

镜像站跑起来之后，不能只看“能不能用”，还要知道“有没有效”。我在nginx.conf里自定义了一个日志格式，把上游缓存状态也记进去：

log_format cache_log '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent $request_time ' '"$upstream_cache_status" "$http_referer"'; access_log /var/log/nginx/access.log cache_log;

然后可以用一条awk统计命中率：

awk '{print $8}' /var/log/nginx/access.log | sort | uniq -c

这里的$8对应upstream_cache_status，如果HIT占比超过80%，说明缓存策略是健康的。如果MISS很多，就去查是不是被大量未命中的query串打穿。

4.6 常见问题速查表

5. 写在最后的一点体会

这套镜像站跑了大半年，我最有体感的不是数字上速度快了多少倍，而是“流量可控”和“资源可复用”这两个点。其实方案本身不复杂，难就难在你要清楚自己到底想解决哪一类问题：是偶尔下载一个包还是团队频繁合作。如果只是临时拉一次，没必要折腾；但如果是长期项目，花一个晚上把缓存、限速、监控都配好，后面省下来的时间绝对不止这个数。

最后再提醒一句：缓存目录一定要勤看，磁盘被打满的教训我踩过一次。某次凌晨收到磁盘报警，爬起来清了两小时缓存，那经历真不想来第二遍。如果你也在维护类似的镜像服务，欢迎交流各自的缓存策略和防滥用经验。