尧图网站建设 
先说结论GitHub镜像站这事儿绝大多数人一听就觉得是“大佬专属技能”实际上只要搞清楚原理一台低配服务器加Nginx就能把八成需求跑起来。我前后帮三个团队搭过同类服务从最初的网页能打开到release文件稳定下载再到git clone不再断流每一步都踩过不少坑。这篇文章就把我这套完整的搭建流程、配置文件和排障思路直接摊开写出来你照着一步步做就能从零跑起来。这套方案适合谁适合那些GitHub网页经常打不开、clone仓库要等半天、release包下载总在中途断掉的人也适合公司内部需要给研发团队共享一个稳定入口的运维同学。核心思路很简单用一台网络质量较好的服务器作为中转把GitHub的页面流量和下载流量“原样搬”到你自己域名下再用Nginx做缓存和超时优化让原本走不动的链路变得顺畅。全程不涉及那些灰色手段所有技术点都是标准的Web反向代理与缓存合规也干净。1. 镜像站到底在解决什么问题1.1 为什么直接访问GitHub经常掉链子大家口中“打不开”的GitHub本质是一组分布在全球的域名系统包括网页端github.com、文件下载端codeload.github.com、对象存储端objects.githubusercontent.com、用户头像avatars.githubusercontent.com等。这些域名背后的服务器有些在海外有些在CDN节点上国内网络访问时容易受跨境链路质量影响高峰期丢包率会明显上升。这不是GitHub本身挂了而是网络链路不稳定。表现就是网页转圈圈、clone卡在“Receiving objects”、release压缩包下载到一半连接重置。镜像站就是绕开这条糟糕链路你访问自己服务器上搭的反代服务由这台网络质量更可控的服务器代替你去和GitHub“对话”再把结果原样回传给你。对用户来说域名变了体验却接近直连顺畅的状态。1.2 镜像站的本质反向代理加缓存很多非技术朋友听到“镜像”就以为是“复制了GitHub所有代码”其实完全不是。绝大多数GitHub镜像站尤其咱们自己搭的这种做的是反向代理客户端的请求打到你的Nginx上Nginx作为中间人转发到GitHub官方服务器拿到响应后再返回给客户端。为什么用反向代理而不是同步仓库同步镜像比如代码托管平台那种自动import仓库只能解决“仓库里默认分支的代码”这一个场景而日常开发中更重要的问题是网页跳转、Issue渲染、Release下载、raw文件直链、git协议交互。这些都要求“实时数据”同步方案处理不了。反向代理则什么都不用存来一个请求转发一个请求最简单也最接近原始体验。缓存则是锦上添花。release压缩包、npm包、release-assets这类不常变化的文件Nginx可以在中转时留一份本地副本下次有人再下载同版本直接由你服务器发出去速度快且省流量。但要注意html页面和API结果不建议开长效缓存否则你会看到各种灵异问题。1.3 几种主流架构对比选错方向会事倍功半在自己动手之前我建议先把方案选型搞清楚。网上流传的有这么几类路子各有优劣方案类型代表实现优点缺点适合场景Nginx反代全站自己配Nginx可控性最强能精确处理每个域名和路径配置量大需要自己维护有服务器、想长期自用Cloudflare Worker反代改版ghproxy类项目部署快全球CDN节点多免费额度够用免费版限流下载大文件不稳临时用、请求量不大基于Cloudflare Pages/Tunnel借助CF edge不用买服务器绑定自定义域名方便免费频率限制严格重负载会429个人学习、轻量访问公网仓库同步Gitee导入等全站可访问镜像仓库只能同步仓库不是全站release和Issue缺失代码浏览与下载release替代自建下载加速器容器跑一个gh-proxy容器专门针对github.com和raw.githubusercontent.com下载加速网页浏览体验弱跳转逻辑不完整只想要clone和下载提速我自己最终选了Nginx自建原因很实际Cloudflare免费版对单IP的限速非常严格测下来下载大文件时经常跑到一半被断而Caddy虽然配置简单但我想用sub_filter对HTML内容里的各种github.com链接做替换Nginx配合编译好的http_sub_module最顺手。另外Nginx的proxy_cache缓存大文件时表现也比Caddy更稳。如果你只是临时给朋友开几天那Worker方案确实快但想长期、安静、稳定地用还是得自己掌握Nginx那套。2. 动手前的基础准备与选型2.1 服务器怎么选带宽和区域是硬指标镜像站最耗资源的地方不在CPU而在出网带宽。买服务器前先想清楚你是自己一个人用还是给一个研发小组用一个人用1核1G内存、带宽5Mbps可能都够如果十几个人同时clone大仓库那带宽反而是第一瓶颈。区域的优先级高于一切。我这里不方便评价具体地区的网络环境但可以给你一个选型方法在目标服务器上执行三次curl -o /dev/null -s -w %{speed_download} https://codeload.github.com/测一下从这台服务器到GitHub官方下载端的实际速度。我实测过几个区域差异非常大有的能稳定跑到几十MB/s有的只有几百KB/s。建议你买服务器前先借用同区域的测试IP试一下或者买那种支持24小时无理由退款的产品开机后先测速速度不行马上退款换区域。存储推荐SSD且容量至少留50GB以上空间来做缓存。Nginx缓存release文件时一个大仓库的tag包可能有几百MB容量太小的机器缓存一会儿就满了命中率上不来。2.2 域名、证书与DNS三个环节缺一不可域名是必须的。用IP直接访问会带来几个麻烦HTTPS证书不好签、浏览器直接标“不安全”、后续子域名拆分比如raw.你的域名.com也做不了。域名不贵买个便宜后缀就够用。证书我用Let‘s Encrypt配合acme.sh自动续期三个月一续配置一次就不用管了。域名解析选哪家不重要阿里云、腾讯云、Cloudflare都行。但有两个操作细节要提一下如果你域名在国内备案的机器上使用A记录解析到国内IP可能会有备案核查问题具体按你的实际情况操作解析记录建议设置一个泛解析*这样后面想加raw、codeload、objects这些二级子域名时不用每次都去控制台新增记录。Nginx里我会按二级域名拆分不同location一个主域名github.example.com用来跑网页反代另外用raw.example.com和dl.example.com分别处理raw文件与release下载。这样职责清晰也方便针对不同流量配置不同的缓存策略。2.3 先列一份需求清单再决定要代理哪些域名这一步特别关键很多人搭完发现“网页能开了但clone还是慢”就是因为没搞清楚GitHub的下载流量不在网页域名上。我建议把自己的需求列成清单使用场景对应的GitHub域名你的镜像站怎么处理浏览仓库、Issue、PRgithub.com主域名反代并替换页面内链接git clone / pushgithub.com走主域名/git路径Nginx透传Smart HTTP协议下载release压缩包codeload.github.com单独子域名反代开缓存下载release内的assetsobjects.githubusercontent.com跟随跳转或单独反代下载raw文件raw.githubusercontent.com单独子域名反代开缓存请求REST APIapi.github.com如需使用单独子域名谨慎缓存用户头像资源avatars.githubusercontent.com建议回源不缓存或短缓存我见过有人只反代了github.com结果页面里所有clone链接都变成github.com/xxx/xxx.git点开还是要走原来的烂网络这就是典型的“拆东墙补西墙”。正确做法是页面里的所有链接都用sub_filter替换成你的镜像域名用户点到的所有资源都走你的服务器中转才叫真正的镜像。3. Nginx反向代理镜像核心配置3.1 安装Nginx时提前编译好两个关键模块如果你直接用系统自带的nginx比如apt install nginx大概率缺少http_sub_module和http_proxy_module的部分高级特性。尤其是sub_filterGitHub页面里的链接替换全靠它没这个模块你就没法做透明的“换链”操作。我在Ubuntu 20.04/22.04上推荐编译安装。先装依赖apt update apt install build-essential libpcre3-dev libssl-dev zlib1g-dev -y wget https://nginx.org/download/nginx-1.24.0.tar.gz tar zxvf nginx-1.24.0.tar.gz cd nginx-1.24.0编译参数里一定要带这几个模块./configure \ --prefix/etc/nginx \ --sbin-path/usr/sbin/nginx \ --modules-path/usr/lib/nginx/modules \ --conf-path/etc/nginx/nginx.conf \ --with-http_ssl_module \ --with-http_sub_module \ --with-http_gzip_static_module \ --with-http_v2_module \ --with-stream \ --with-stream_ssl_module make make install这里多说一句为什么我要--with-stream。后面如果要给git的SSH协议22端口也做镜像跳转stream模块可以做四层透明转发。虽然平时git用HTTPS就够但总有同事习惯用SSH协议拉代码有备无患。3.2 网页反代主配置换链是灵魂网页反代的难点不在“转发”而在“让用户看起来没离开GitHub”。GitHub页面会动态生成大量绝对链接图片、CSS、JS、仓库地址全指向github.com或avatars.githubusercontent.com等。你需要在返回给用户前把响应内容里的这些域名全部替换成你的镜像域名。关于换链核心配置如下server { listen 443 ssl http2; server_name github.example.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; # 关键替换HTML响应中的域名链接 sub_filter_once off; sub_filter https://github.com https://github.example.com; sub_filter https://codeload.github.com https://dl.example.com; sub_filter https://raw.githubusercontent.com https://raw.example.com; sub_filter https://objects.githubusercontent.com https://objects.example.com; sub_filter https://avatars.githubusercontent.com https://avatars.example.com; sub_filter_types text/html text/css application/javascript application/json; 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 https; # 防断连核心参数 proxy_connect_timeout 10s; proxy_send_timeout 60s; proxy_read_timeout 60s; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; # 关闭缓存保证页面实时性 proxy_no_cache 1; proxy_cache_bypass 1; } }proxy_pass https://github.com;这里有个细节不要在URI末尾加斜杠也不要带变量。否则Nginx可能把请求路径处理逻辑搞乱Git登录后的回调地址会错乱。保留默认的”把完整URI透传给上游“行为是最稳的。proxy_set_header Host github.com这行也容易被忽略。GitHub是根据Host头来识别你想访问哪个站点的如果你把Host留成你自己的域名GitHub会返回404或者跳转。那github.com的IP是怎么解析的Nginx默认用系统DNS解析但系统DNS有时候给出的不是最优IP。我建议在nginx.conf的http块里显式配置resolver 8.8.8.8 1.1.1.1 valid300s ipv6off; resolver_timeout 5s;再加一条proxy_ssl_server_name on; proxy_ssl_name github.com;。这是因为GitHub的SSL证书是针对github.com域名的Nginx和上游建立TLS连接时必须发送正确的SNI否则证书校验失败报SSL: certificate verify failed。3.3 release下载与raw文件子域名配置GitHub的release下载链路比较特殊浏览器请求codeload.github.com/owner/repo/tar.gz/refs/tags/v1.0.0会先返回302跳转到objects.githubusercontent.com/...。反代时如果你直接把proxy_pass指向https://codeload.github.comNginx会原样把302回给客户端客户端再去请求objects.githubusercontent.com但前面又说这个域名没被镜像等于白干。所以我的做法是在处理dl.example.com时把上游域名的跳转也一起“劫持”过来。两个方案方案一直接用Nginx跟随重定向。在location里加proxy_intercept_errors off;然后额外加一层location匹配objects.example.com把这一层也反代到objects.githubusercontent.com。这要求你在页面换链时已经把对象域名换成objects.example.com用户点击下载后实际请求落到你的服务器上。方案二顺手在nginx里直接改写Location头server { listen 443 ssl http2; server_name dl.example.com objects.example.com; location / { proxy_pass https://codeload.github.com; proxy_set_header Host codeload.github.com; proxy_ssl_server_name on; proxy_ssl_name codeload.github.com; proxy_redirect https://objects.githubusercontent.com/ https://objects.example.com/; proxy_redirect https://codeload.github.com/ https://dl.example.com/; proxy_intercept_errors on; error_page 301 302 307 handle_redirect; } location handle_redirect { proxy_pass https://objects.githubusercontent.com$request_uri; proxy_set_header Host objects.githubusercontent.com; proxy_ssl_server_name on; proxy_ssl_name objects.githubusercontent.com; proxy_redirect https://objects.githubusercontent.com/ https://objects.example.com/; } }proxy_redirect这条配置的作用是上游返回302时Nginx会把响应头里的Location也按规则改写。这样用户即使看到302浏览器地址栏也不会跳成GitHub官方域名而是一直停留在你的镜像域名上。raw文件子域名相对单纯一点server { listen 443 ssl http2; server_name raw.example.com; 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_redirect https://raw.githubusercontent.com/ https://raw.example.com/; proxy_cache github_raw_cache; proxy_cache_key $uri$is_args$args; proxy_cache_valid 200 6h; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; add_header X-Cache-Status $upstream_cache_status; } }raw文件绝大多数是源码文件不经常变化6小时缓存完全没问题。add_header X-Cache-Status是为了方便自己调试每次请求看响应头就能判断是HIT还是MISS排查问题时特别有用。3.4 git clone加速原理与配置优化镜像站的最终考验是git clone。Git的HTTP协议不是简单的GET它需要先请求一个info/refs的端点获取分支引用然后通过git-upload-pack和git-receive-pack两个端点传输对象数据。Nginx反代需要把这类POST请求原样透传。在刚才的主域名配置里location /就已经覆盖了这些路径。但有几个坑必须填第一个坑是URL转换。用户使用镜像域名clone时他把原始URL里的github.com/owner/repo.git换成github.example.com/owner/repo.git即可Nginx会把请求完整转发到https://github.com/owner/repo.git。这没问题。但很多用户会直接在页面里看到GitHub帮我们生成好的一行命令比如git clone https://github.com/owner/repo.git这个原始URL已经被sub_filter替换成了镜像域名所以页面里复制的命令直接可用。第二个坑是大仓库的POST body限制。git push时要上传大量数据Nginx默认的client_max_body_size是1m你push几百MB的提交时一定会报413 Request Entity Too Large。我在主站配置里统一加一行client_max_body_size 2048m; proxy_request_buffering off;这里proxy_request_buffering off是让Nginx把客户端数据边收边发给上游而不是攒满整个请求体再转发。不然既占内存对大文件push也不友好。第三个坑是超时时间不要太短。Git clone空仓库时服务器端可能长时间没有数据输出如果proxy_read_timeout只有60秒拉一个1GB大仓库时很容易在某个节点触发上游超时。我自己一般给到600sproxy_connect_timeout 15s; proxy_send_timeout 600s; proxy_read_timeout 600s;还有一个很大的提速点浅克隆。很多场景下我们根本不需要仓库的全部分支历史只要默认分支最新代码。可以跟团队明确一下用git clone --depth1替代完整克隆镜像站压力小一大截下载速度也快好几倍。我这边在内部文档里直接把浅克隆设为推荐操作。3.5 大文件缓存让重复下载走上快车道release下载场景里重复下载相同版本是非常普遍的。比如一个新版本发布团队10个人先后都要下载如果每次都回源你服务器和GitHub之间的带宽完全不够用。加一块Nginx缓存能有效解决。缓存配置可以放在http块proxy_cache_path /data/nginx_cache levels1:2 keys_zonegithub_dl_cache:10m max_size80g inactive14d use_temp_pathoff;重点是levels1:2的目录分级、max_size上限和inactive清理时间。我建议max_size设置成你磁盘容量的60%左右留出余量给系统日志和临时文件inactive选14天比较合适release包生命周期也就这一两周。然后在dl.example.com的server块里启用location ~* \.(tar\.gz|zip|tgz|bz2|exe|dmg|deb|rpm)$ { proxy_pass https://codeload.github.com; proxy_set_header Host codeload.github.com; proxy_cache github_dl_cache; proxy_cache_valid 200 14d; proxy_cache_lock on; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; add_header X-Cache-Status $upstream_cache_status; }proxy_cache_lock on这行太重要了。不加它当10个人同时请求同一个大文件时Nginx会同时回源10次把上游带宽打满不说你服务器的CPU也会被白白耗掉。加了这个参数同一时刻只有一个回源请求其他人排队等待第一个结果写进缓存后再直接命中。我实测过缓存命中之后大文件的下载速度基本取决于你服务器到用户之间的带宽和GitHub官方链路完全无关了。如果你用的是带BGP线路的机器体验会非常接近本地下载。4. 上线后的维护与提速技巧4.1 缓存命中率观测与预热搭好之后别急着甩给同事用先用你自己账号把常用的仓库、release包访问一遍让缓存预热。看缓存命中率最直接的方式是看响应头的X-Cache-StatusMISS这一次走了上游GitHub还没缓存HIT这次是你本地缓存直接返回速度快UPDATING缓存正在后台刷新当前请求用了旧缓存EXPIRED缓存过期需要回源。我这边的经验是发布新版本时自己先手动下载一次release包让缓存先热起来。不然同事同时抢着下载第一次全MISS体验还是卡。对于页面HTML我不建议开缓存。GitHub的页面包含大量动态内容README渲染、文件列表、star数缓存容易造成页面过时。但你可以在Nginx层面把静态资源.css、.js、.png单独设一条location给静态资源做缓存这个提升很明显。4.2 再提速调整TCP与HTTP参数Nginx默认的内核参数不是为镜像站这种“高并发长连接”场景设计的。我调过几个参数后页面加载速度和下载稳定性都有改善在nginx.conf的http块里加keepalive_timeout 20s; keepalive_requests 1000; tcp_nopush on; tcp_nodelay on; sendfile on;tcp_nopush与tcp_nodelay看起来矛盾但配合使用其实效果很好前者优化大文件发送后者优化小数据包低延迟。在高带宽机器上sendfile能直接把文件从磁盘读到网卡走内核零拷贝CPU占用明显下降。系统层面可以加大连接队列长度sysctl -w net.core.somaxconn65535 sysctl -w net.ipv4.tcp_max_syn_backlog65535有朋友问我需不需要上CDN我的看法是如果你的用户群体和你服务器所在区域比较集中CDN的意义不大反而多一层回源增加延迟但用户分布在全国各地的话靠一台服务器很难保证所有人快套一层CDN、把缓存命中率做上去确实能解决跨区域延迟问题。CDN配置时记得把缓存规则针对大文件做特殊调整否则CDN节点全回源到你服务器你还得再买带宽。4.3 防止镜像站被滥用限流与安全加固镜像站一搭好如果你把域名公开出去很快就会被全网扫描到然后被当成免费代理乱用。我最开始吃过这个亏一个晚上跑掉几十GB流量原因就是有人在用我这个镜像下大文件。几个实用手段第一请求限流。对每个IP限制请求速率limit_req_zone $binary_remote_addr zonegithub_limit:10m rate5r/s; location / { limit_req zonegithub_limit burst20 nodelay; }这个rate5r/s表示平均每秒最多5个请求burst20是允许瞬时突发20个对正常浏览完全够用但机器脚本会被拦下来。第二限制单IP的并发连接数limit_conn_zone $binary_remote_addr zoneperip:10m; limit_conn perip 10;防止有人开几十个线程同时从你这里拉文件。第三更保险的做法是启用Basic Auth只有团队内部分享用户名密码的人能用。这个看需求如果只是自己用我建议直接开location / { auth_basic GitHub Mirror; auth_basic_user_file /etc/nginx/.htpasswd; }用openssl passwd -apr1生成密码放到.htpasswd即可。公开镜像站的流量控制难度指数级上升不如一开始就限制使用范围。5. 常见问题排查实录与避坑清单5.1 现象一网页打开白屏或样式丢失这个八成是sub_filter没生效。很多人编译Nginx时没带http_sub_module或者用了系统默认的nginx包配置里写了sub_filter但Nginx启动时直接报错根本没加载。先确认模块nginx -V 21 | grep sub看到--with-http_sub_module才算OK。还有一个坑是sub_filter_types没加application/javascript现在GitHub的JS都是text/javascript、application/javascript混合类型漏掉就只替换HTML不替换JS页面里很多功能按钮点起来会404。5.2 现象二能打开网页但git clone还是直连github.com排查思路很简单——打开页面右键查看源码搜索一下github.com。如果还能搜到原始域名说明sub_filter没生效或没匹配到。常见原因有二一是页面某些响应是gzip压缩的Nginx的sub_filter默认只对未经压缩的响应做替换需要在http块里加proxy_set_header Accept-Encoding identity;禁用上游压缩二是你设置的sub_filter_types不够全漏了JSON类型。GitHub的部分接口返回是JSON格式原始内容里也有仓库地址这种不替换的话依赖接口路径的前端交互组件会继续指回官方域名。加上后基本能根治。5.3 现象三release下载到一半断了这种问题首先看是不是缓存目录满了。Nginx写缓存失败时会回源但本身传输也会受影响。我遇到过/data/nginx_cache这个目录所在的磁盘满了Nginx报cache lock错误下载直接404。另外注意proxy_cache_lock和proxy_cache_use_stale的配合。如果上游网络抖动导致回源失败默认配置会把错误直接抛给用户我加了proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504后Nginx会在回源失败时尝试用旧缓存兜底至少用户还能拿到文件只是可能不是最新版本。对release包来说旧版本其实也能用。5.4 快速排查速查表异常现象优先排查项避坑操作HTTPS证书报错SSL证书文件路径、有效期加定时任务自动续期或用acme.sh hook重载nginx页面能开但图片裂sub_filter未替换avatars域名确认配置了avatars.example.com反代clone提示401/403Host头没有透传proxy_set_header Host github.com;不可省push超过1MB报413client_max_body_size太小设为2048m并关掉request_buffering间歇性502上游超时参数太短proxy_read_timeout调大到600s502频繁出现在缓存场景proxy_cache_lock并发确认use_temp_pathoff避免缓存写临时目录sub_filter部分生效上游gzip未禁用加proxy_set_header Accept-Encoding identity;下载速度无法跑满本地vCPU/磁盘瓶颈大文件走sendfile on;确保磁盘IO够5.5 一个容易被忽略的坑API与登录场景镜像站做反代时GitHub的登录功能是没法直接用的。GitHub登录涉及cookie、CSRF token、OAuth回调全部绑定官方域名单纯用Nginx反代和换链没法把整套登录逻辑搬到你的域名下面。所以镜像站通常只能服务公开仓库的浏览、clone、下载这些场景fork、star、issue评论、登录后操作都会有各种异常。我建议你在使用文档里写清楚“本镜像站仅用于公开仓库的浏览与下载登录与写操作请使用官方地址。”这样能避免团队里有同事踩到“发现自己登不上镜像站”的坑。如果你确实想给团队提供稳定的代码拉取渠道比反代更稳的思路是我上面提过的方案组合网页浏览走镜像站代码下载优先用release缓存clone时推荐git clone --depth1遇到私有仓库就仍然走官方客户端配合认证。把这个组合写进团队开发规范里避免大家遇到问题再来问你。5.6 我的几点实操心得最后分享几个我自己摸出来的小技巧。第一个Nginx配置改完先做语法检查和reload这已经成了肌肉记忆nginx -t nginx -s reload但reload只对新连接生效旧的长连接还会保留一会儿如果改的是缓存或限流参数建议直接systemctl restart nginx别省这个事。第二个日志一定不要省。我在nginx.conf里单独给镜像站配了一份访问日志字段带上$upstream_cache_status、$upstream_response_time和$request_time。排障时一眼能看出是上游慢还是本地慢。log_format mirror $remote_addr [$time_local] $request $status $body_bytes_sent $request_time $upstream_response_time $upstream_cache_status; access_log /var/log/nginx/mirror_access.log mirror;第三个别忘了监控磁盘和流量。我写过一个简单的cron脚本每天检查缓存目录占用率超过阈值自动清掉inactive时间最长的文件find /data/nginx_cache -type f -atime 14 -delete比自己盯着磁盘容量踏实多了。镜像站这个东西说到底是给“链路质量不理想环境下的开发工作”提供一个工程化兜底。你把这套流程跑通后再遇到GitHub访问问题心里就有底了不用到处找别人搭的公共镜像自己手里的这套随时能用、能调、能修。后续如果你想加raw文件加速、release大文件缓存甚至团队内部分发都是一样的思路往下扩展就行。 自建GitHub镜像站：Nginx反向代理与缓存加速的完整实践指南
先说结论GitHub镜像站这事儿绝大多数人一听就觉得是“大佬专属技能”实际上只要搞清楚原理一台低配服务器加Nginx就能把八成需求跑起来。我前后帮三个团队搭过同类服务从最初的网页能打开到release文件稳定下载再到git clone不再断流每一步都踩过不少坑。这篇文章就把我这套完整的搭建流程、配置文件和排障思路直接摊开写出来你照着一步步做就能从零跑起来。这套方案适合谁适合那些GitHub网页经常打不开、clone仓库要等半天、release包下载总在中途断掉的人也适合公司内部需要给研发团队共享一个稳定入口的运维同学。核心思路很简单用一台网络质量较好的服务器作为中转把GitHub的页面流量和下载流量“原样搬”到你自己域名下再用Nginx做缓存和超时优化让原本走不动的链路变得顺畅。全程不涉及那些灰色手段所有技术点都是标准的Web反向代理与缓存合规也干净。1. 镜像站到底在解决什么问题1.1 为什么直接访问GitHub经常掉链子大家口中“打不开”的GitHub本质是一组分布在全球的域名系统包括网页端github.com、文件下载端codeload.github.com、对象存储端objects.githubusercontent.com、用户头像avatars.githubusercontent.com等。这些域名背后的服务器有些在海外有些在CDN节点上国内网络访问时容易受跨境链路质量影响高峰期丢包率会明显上升。这不是GitHub本身挂了而是网络链路不稳定。表现就是网页转圈圈、clone卡在“Receiving objects”、release压缩包下载到一半连接重置。镜像站就是绕开这条糟糕链路你访问自己服务器上搭的反代服务由这台网络质量更可控的服务器代替你去和GitHub“对话”再把结果原样回传给你。对用户来说域名变了体验却接近直连顺畅的状态。1.2 镜像站的本质反向代理加缓存很多非技术朋友听到“镜像”就以为是“复制了GitHub所有代码”其实完全不是。绝大多数GitHub镜像站尤其咱们自己搭的这种做的是反向代理客户端的请求打到你的Nginx上Nginx作为中间人转发到GitHub官方服务器拿到响应后再返回给客户端。为什么用反向代理而不是同步仓库同步镜像比如代码托管平台那种自动import仓库只能解决“仓库里默认分支的代码”这一个场景而日常开发中更重要的问题是网页跳转、Issue渲染、Release下载、raw文件直链、git协议交互。这些都要求“实时数据”同步方案处理不了。反向代理则什么都不用存来一个请求转发一个请求最简单也最接近原始体验。缓存则是锦上添花。release压缩包、npm包、release-assets这类不常变化的文件Nginx可以在中转时留一份本地副本下次有人再下载同版本直接由你服务器发出去速度快且省流量。但要注意html页面和API结果不建议开长效缓存否则你会看到各种灵异问题。1.3 几种主流架构对比选错方向会事倍功半在自己动手之前我建议先把方案选型搞清楚。网上流传的有这么几类路子各有优劣方案类型代表实现优点缺点适合场景Nginx反代全站自己配Nginx可控性最强能精确处理每个域名和路径配置量大需要自己维护有服务器、想长期自用Cloudflare Worker反代改版ghproxy类项目部署快全球CDN节点多免费额度够用免费版限流下载大文件不稳临时用、请求量不大基于Cloudflare Pages/Tunnel借助CF edge不用买服务器绑定自定义域名方便免费频率限制严格重负载会429个人学习、轻量访问公网仓库同步Gitee导入等全站可访问镜像仓库只能同步仓库不是全站release和Issue缺失代码浏览与下载release替代自建下载加速器容器跑一个gh-proxy容器专门针对github.com和raw.githubusercontent.com下载加速网页浏览体验弱跳转逻辑不完整只想要clone和下载提速我自己最终选了Nginx自建原因很实际Cloudflare免费版对单IP的限速非常严格测下来下载大文件时经常跑到一半被断而Caddy虽然配置简单但我想用sub_filter对HTML内容里的各种github.com链接做替换Nginx配合编译好的http_sub_module最顺手。另外Nginx的proxy_cache缓存大文件时表现也比Caddy更稳。如果你只是临时给朋友开几天那Worker方案确实快但想长期、安静、稳定地用还是得自己掌握Nginx那套。2. 动手前的基础准备与选型2.1 服务器怎么选带宽和区域是硬指标镜像站最耗资源的地方不在CPU而在出网带宽。买服务器前先想清楚你是自己一个人用还是给一个研发小组用一个人用1核1G内存、带宽5Mbps可能都够如果十几个人同时clone大仓库那带宽反而是第一瓶颈。区域的优先级高于一切。我这里不方便评价具体地区的网络环境但可以给你一个选型方法在目标服务器上执行三次curl -o /dev/null -s -w %{speed_download} https://codeload.github.com/测一下从这台服务器到GitHub官方下载端的实际速度。我实测过几个区域差异非常大有的能稳定跑到几十MB/s有的只有几百KB/s。建议你买服务器前先借用同区域的测试IP试一下或者买那种支持24小时无理由退款的产品开机后先测速速度不行马上退款换区域。存储推荐SSD且容量至少留50GB以上空间来做缓存。Nginx缓存release文件时一个大仓库的tag包可能有几百MB容量太小的机器缓存一会儿就满了命中率上不来。2.2 域名、证书与DNS三个环节缺一不可域名是必须的。用IP直接访问会带来几个麻烦HTTPS证书不好签、浏览器直接标“不安全”、后续子域名拆分比如raw.你的域名.com也做不了。域名不贵买个便宜后缀就够用。证书我用Let‘s Encrypt配合acme.sh自动续期三个月一续配置一次就不用管了。域名解析选哪家不重要阿里云、腾讯云、Cloudflare都行。但有两个操作细节要提一下如果你域名在国内备案的机器上使用A记录解析到国内IP可能会有备案核查问题具体按你的实际情况操作解析记录建议设置一个泛解析*这样后面想加raw、codeload、objects这些二级子域名时不用每次都去控制台新增记录。Nginx里我会按二级域名拆分不同location一个主域名github.example.com用来跑网页反代另外用raw.example.com和dl.example.com分别处理raw文件与release下载。这样职责清晰也方便针对不同流量配置不同的缓存策略。2.3 先列一份需求清单再决定要代理哪些域名这一步特别关键很多人搭完发现“网页能开了但clone还是慢”就是因为没搞清楚GitHub的下载流量不在网页域名上。我建议把自己的需求列成清单使用场景对应的GitHub域名你的镜像站怎么处理浏览仓库、Issue、PRgithub.com主域名反代并替换页面内链接git clone / pushgithub.com走主域名/git路径Nginx透传Smart HTTP协议下载release压缩包codeload.github.com单独子域名反代开缓存下载release内的assetsobjects.githubusercontent.com跟随跳转或单独反代下载raw文件raw.githubusercontent.com单独子域名反代开缓存请求REST APIapi.github.com如需使用单独子域名谨慎缓存用户头像资源avatars.githubusercontent.com建议回源不缓存或短缓存我见过有人只反代了github.com结果页面里所有clone链接都变成github.com/xxx/xxx.git点开还是要走原来的烂网络这就是典型的“拆东墙补西墙”。正确做法是页面里的所有链接都用sub_filter替换成你的镜像域名用户点到的所有资源都走你的服务器中转才叫真正的镜像。3. Nginx反向代理镜像核心配置3.1 安装Nginx时提前编译好两个关键模块如果你直接用系统自带的nginx比如apt install nginx大概率缺少http_sub_module和http_proxy_module的部分高级特性。尤其是sub_filterGitHub页面里的链接替换全靠它没这个模块你就没法做透明的“换链”操作。我在Ubuntu 20.04/22.04上推荐编译安装。先装依赖apt update apt install build-essential libpcre3-dev libssl-dev zlib1g-dev -y wget https://nginx.org/download/nginx-1.24.0.tar.gz tar zxvf nginx-1.24.0.tar.gz cd nginx-1.24.0编译参数里一定要带这几个模块./configure \ --prefix/etc/nginx \ --sbin-path/usr/sbin/nginx \ --modules-path/usr/lib/nginx/modules \ --conf-path/etc/nginx/nginx.conf \ --with-http_ssl_module \ --with-http_sub_module \ --with-http_gzip_static_module \ --with-http_v2_module \ --with-stream \ --with-stream_ssl_module make make install这里多说一句为什么我要--with-stream。后面如果要给git的SSH协议22端口也做镜像跳转stream模块可以做四层透明转发。虽然平时git用HTTPS就够但总有同事习惯用SSH协议拉代码有备无患。3.2 网页反代主配置换链是灵魂网页反代的难点不在“转发”而在“让用户看起来没离开GitHub”。GitHub页面会动态生成大量绝对链接图片、CSS、JS、仓库地址全指向github.com或avatars.githubusercontent.com等。你需要在返回给用户前把响应内容里的这些域名全部替换成你的镜像域名。关于换链核心配置如下server { listen 443 ssl http2; server_name github.example.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; # 关键替换HTML响应中的域名链接 sub_filter_once off; sub_filter https://github.com https://github.example.com; sub_filter https://codeload.github.com https://dl.example.com; sub_filter https://raw.githubusercontent.com https://raw.example.com; sub_filter https://objects.githubusercontent.com https://objects.example.com; sub_filter https://avatars.githubusercontent.com https://avatars.example.com; sub_filter_types text/html text/css application/javascript application/json; 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 https; # 防断连核心参数 proxy_connect_timeout 10s; proxy_send_timeout 60s; proxy_read_timeout 60s; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; # 关闭缓存保证页面实时性 proxy_no_cache 1; proxy_cache_bypass 1; } }proxy_pass https://github.com;这里有个细节不要在URI末尾加斜杠也不要带变量。否则Nginx可能把请求路径处理逻辑搞乱Git登录后的回调地址会错乱。保留默认的”把完整URI透传给上游“行为是最稳的。proxy_set_header Host github.com这行也容易被忽略。GitHub是根据Host头来识别你想访问哪个站点的如果你把Host留成你自己的域名GitHub会返回404或者跳转。那github.com的IP是怎么解析的Nginx默认用系统DNS解析但系统DNS有时候给出的不是最优IP。我建议在nginx.conf的http块里显式配置resolver 8.8.8.8 1.1.1.1 valid300s ipv6off; resolver_timeout 5s;再加一条proxy_ssl_server_name on; proxy_ssl_name github.com;。这是因为GitHub的SSL证书是针对github.com域名的Nginx和上游建立TLS连接时必须发送正确的SNI否则证书校验失败报SSL: certificate verify failed。3.3 release下载与raw文件子域名配置GitHub的release下载链路比较特殊浏览器请求codeload.github.com/owner/repo/tar.gz/refs/tags/v1.0.0会先返回302跳转到objects.githubusercontent.com/...。反代时如果你直接把proxy_pass指向https://codeload.github.comNginx会原样把302回给客户端客户端再去请求objects.githubusercontent.com但前面又说这个域名没被镜像等于白干。所以我的做法是在处理dl.example.com时把上游域名的跳转也一起“劫持”过来。两个方案方案一直接用Nginx跟随重定向。在location里加proxy_intercept_errors off;然后额外加一层location匹配objects.example.com把这一层也反代到objects.githubusercontent.com。这要求你在页面换链时已经把对象域名换成objects.example.com用户点击下载后实际请求落到你的服务器上。方案二顺手在nginx里直接改写Location头server { listen 443 ssl http2; server_name dl.example.com objects.example.com; location / { proxy_pass https://codeload.github.com; proxy_set_header Host codeload.github.com; proxy_ssl_server_name on; proxy_ssl_name codeload.github.com; proxy_redirect https://objects.githubusercontent.com/ https://objects.example.com/; proxy_redirect https://codeload.github.com/ https://dl.example.com/; proxy_intercept_errors on; error_page 301 302 307 handle_redirect; } location handle_redirect { proxy_pass https://objects.githubusercontent.com$request_uri; proxy_set_header Host objects.githubusercontent.com; proxy_ssl_server_name on; proxy_ssl_name objects.githubusercontent.com; proxy_redirect https://objects.githubusercontent.com/ https://objects.example.com/; } }proxy_redirect这条配置的作用是上游返回302时Nginx会把响应头里的Location也按规则改写。这样用户即使看到302浏览器地址栏也不会跳成GitHub官方域名而是一直停留在你的镜像域名上。raw文件子域名相对单纯一点server { listen 443 ssl http2; server_name raw.example.com; 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_redirect https://raw.githubusercontent.com/ https://raw.example.com/; proxy_cache github_raw_cache; proxy_cache_key $uri$is_args$args; proxy_cache_valid 200 6h; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; add_header X-Cache-Status $upstream_cache_status; } }raw文件绝大多数是源码文件不经常变化6小时缓存完全没问题。add_header X-Cache-Status是为了方便自己调试每次请求看响应头就能判断是HIT还是MISS排查问题时特别有用。3.4 git clone加速原理与配置优化镜像站的最终考验是git clone。Git的HTTP协议不是简单的GET它需要先请求一个info/refs的端点获取分支引用然后通过git-upload-pack和git-receive-pack两个端点传输对象数据。Nginx反代需要把这类POST请求原样透传。在刚才的主域名配置里location /就已经覆盖了这些路径。但有几个坑必须填第一个坑是URL转换。用户使用镜像域名clone时他把原始URL里的github.com/owner/repo.git换成github.example.com/owner/repo.git即可Nginx会把请求完整转发到https://github.com/owner/repo.git。这没问题。但很多用户会直接在页面里看到GitHub帮我们生成好的一行命令比如git clone https://github.com/owner/repo.git这个原始URL已经被sub_filter替换成了镜像域名所以页面里复制的命令直接可用。第二个坑是大仓库的POST body限制。git push时要上传大量数据Nginx默认的client_max_body_size是1m你push几百MB的提交时一定会报413 Request Entity Too Large。我在主站配置里统一加一行client_max_body_size 2048m; proxy_request_buffering off;这里proxy_request_buffering off是让Nginx把客户端数据边收边发给上游而不是攒满整个请求体再转发。不然既占内存对大文件push也不友好。第三个坑是超时时间不要太短。Git clone空仓库时服务器端可能长时间没有数据输出如果proxy_read_timeout只有60秒拉一个1GB大仓库时很容易在某个节点触发上游超时。我自己一般给到600sproxy_connect_timeout 15s; proxy_send_timeout 600s; proxy_read_timeout 600s;还有一个很大的提速点浅克隆。很多场景下我们根本不需要仓库的全部分支历史只要默认分支最新代码。可以跟团队明确一下用git clone --depth1替代完整克隆镜像站压力小一大截下载速度也快好几倍。我这边在内部文档里直接把浅克隆设为推荐操作。3.5 大文件缓存让重复下载走上快车道release下载场景里重复下载相同版本是非常普遍的。比如一个新版本发布团队10个人先后都要下载如果每次都回源你服务器和GitHub之间的带宽完全不够用。加一块Nginx缓存能有效解决。缓存配置可以放在http块proxy_cache_path /data/nginx_cache levels1:2 keys_zonegithub_dl_cache:10m max_size80g inactive14d use_temp_pathoff;重点是levels1:2的目录分级、max_size上限和inactive清理时间。我建议max_size设置成你磁盘容量的60%左右留出余量给系统日志和临时文件inactive选14天比较合适release包生命周期也就这一两周。然后在dl.example.com的server块里启用location ~* \.(tar\.gz|zip|tgz|bz2|exe|dmg|deb|rpm)$ { proxy_pass https://codeload.github.com; proxy_set_header Host codeload.github.com; proxy_cache github_dl_cache; proxy_cache_valid 200 14d; proxy_cache_lock on; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; add_header X-Cache-Status $upstream_cache_status; }proxy_cache_lock on这行太重要了。不加它当10个人同时请求同一个大文件时Nginx会同时回源10次把上游带宽打满不说你服务器的CPU也会被白白耗掉。加了这个参数同一时刻只有一个回源请求其他人排队等待第一个结果写进缓存后再直接命中。我实测过缓存命中之后大文件的下载速度基本取决于你服务器到用户之间的带宽和GitHub官方链路完全无关了。如果你用的是带BGP线路的机器体验会非常接近本地下载。4. 上线后的维护与提速技巧4.1 缓存命中率观测与预热搭好之后别急着甩给同事用先用你自己账号把常用的仓库、release包访问一遍让缓存预热。看缓存命中率最直接的方式是看响应头的X-Cache-StatusMISS这一次走了上游GitHub还没缓存HIT这次是你本地缓存直接返回速度快UPDATING缓存正在后台刷新当前请求用了旧缓存EXPIRED缓存过期需要回源。我这边的经验是发布新版本时自己先手动下载一次release包让缓存先热起来。不然同事同时抢着下载第一次全MISS体验还是卡。对于页面HTML我不建议开缓存。GitHub的页面包含大量动态内容README渲染、文件列表、star数缓存容易造成页面过时。但你可以在Nginx层面把静态资源.css、.js、.png单独设一条location给静态资源做缓存这个提升很明显。4.2 再提速调整TCP与HTTP参数Nginx默认的内核参数不是为镜像站这种“高并发长连接”场景设计的。我调过几个参数后页面加载速度和下载稳定性都有改善在nginx.conf的http块里加keepalive_timeout 20s; keepalive_requests 1000; tcp_nopush on; tcp_nodelay on; sendfile on;tcp_nopush与tcp_nodelay看起来矛盾但配合使用其实效果很好前者优化大文件发送后者优化小数据包低延迟。在高带宽机器上sendfile能直接把文件从磁盘读到网卡走内核零拷贝CPU占用明显下降。系统层面可以加大连接队列长度sysctl -w net.core.somaxconn65535 sysctl -w net.ipv4.tcp_max_syn_backlog65535有朋友问我需不需要上CDN我的看法是如果你的用户群体和你服务器所在区域比较集中CDN的意义不大反而多一层回源增加延迟但用户分布在全国各地的话靠一台服务器很难保证所有人快套一层CDN、把缓存命中率做上去确实能解决跨区域延迟问题。CDN配置时记得把缓存规则针对大文件做特殊调整否则CDN节点全回源到你服务器你还得再买带宽。4.3 防止镜像站被滥用限流与安全加固镜像站一搭好如果你把域名公开出去很快就会被全网扫描到然后被当成免费代理乱用。我最开始吃过这个亏一个晚上跑掉几十GB流量原因就是有人在用我这个镜像下大文件。几个实用手段第一请求限流。对每个IP限制请求速率limit_req_zone $binary_remote_addr zonegithub_limit:10m rate5r/s; location / { limit_req zonegithub_limit burst20 nodelay; }这个rate5r/s表示平均每秒最多5个请求burst20是允许瞬时突发20个对正常浏览完全够用但机器脚本会被拦下来。第二限制单IP的并发连接数limit_conn_zone $binary_remote_addr zoneperip:10m; limit_conn perip 10;防止有人开几十个线程同时从你这里拉文件。第三更保险的做法是启用Basic Auth只有团队内部分享用户名密码的人能用。这个看需求如果只是自己用我建议直接开location / { auth_basic GitHub Mirror; auth_basic_user_file /etc/nginx/.htpasswd; }用openssl passwd -apr1生成密码放到.htpasswd即可。公开镜像站的流量控制难度指数级上升不如一开始就限制使用范围。5. 常见问题排查实录与避坑清单5.1 现象一网页打开白屏或样式丢失这个八成是sub_filter没生效。很多人编译Nginx时没带http_sub_module或者用了系统默认的nginx包配置里写了sub_filter但Nginx启动时直接报错根本没加载。先确认模块nginx -V 21 | grep sub看到--with-http_sub_module才算OK。还有一个坑是sub_filter_types没加application/javascript现在GitHub的JS都是text/javascript、application/javascript混合类型漏掉就只替换HTML不替换JS页面里很多功能按钮点起来会404。5.2 现象二能打开网页但git clone还是直连github.com排查思路很简单——打开页面右键查看源码搜索一下github.com。如果还能搜到原始域名说明sub_filter没生效或没匹配到。常见原因有二一是页面某些响应是gzip压缩的Nginx的sub_filter默认只对未经压缩的响应做替换需要在http块里加proxy_set_header Accept-Encoding identity;禁用上游压缩二是你设置的sub_filter_types不够全漏了JSON类型。GitHub的部分接口返回是JSON格式原始内容里也有仓库地址这种不替换的话依赖接口路径的前端交互组件会继续指回官方域名。加上后基本能根治。5.3 现象三release下载到一半断了这种问题首先看是不是缓存目录满了。Nginx写缓存失败时会回源但本身传输也会受影响。我遇到过/data/nginx_cache这个目录所在的磁盘满了Nginx报cache lock错误下载直接404。另外注意proxy_cache_lock和proxy_cache_use_stale的配合。如果上游网络抖动导致回源失败默认配置会把错误直接抛给用户我加了proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504后Nginx会在回源失败时尝试用旧缓存兜底至少用户还能拿到文件只是可能不是最新版本。对release包来说旧版本其实也能用。5.4 快速排查速查表异常现象优先排查项避坑操作HTTPS证书报错SSL证书文件路径、有效期加定时任务自动续期或用acme.sh hook重载nginx页面能开但图片裂sub_filter未替换avatars域名确认配置了avatars.example.com反代clone提示401/403Host头没有透传proxy_set_header Host github.com;不可省push超过1MB报413client_max_body_size太小设为2048m并关掉request_buffering间歇性502上游超时参数太短proxy_read_timeout调大到600s502频繁出现在缓存场景proxy_cache_lock并发确认use_temp_pathoff避免缓存写临时目录sub_filter部分生效上游gzip未禁用加proxy_set_header Accept-Encoding identity;下载速度无法跑满本地vCPU/磁盘瓶颈大文件走sendfile on;确保磁盘IO够5.5 一个容易被忽略的坑API与登录场景镜像站做反代时GitHub的登录功能是没法直接用的。GitHub登录涉及cookie、CSRF token、OAuth回调全部绑定官方域名单纯用Nginx反代和换链没法把整套登录逻辑搬到你的域名下面。所以镜像站通常只能服务公开仓库的浏览、clone、下载这些场景fork、star、issue评论、登录后操作都会有各种异常。我建议你在使用文档里写清楚“本镜像站仅用于公开仓库的浏览与下载登录与写操作请使用官方地址。”这样能避免团队里有同事踩到“发现自己登不上镜像站”的坑。如果你确实想给团队提供稳定的代码拉取渠道比反代更稳的思路是我上面提过的方案组合网页浏览走镜像站代码下载优先用release缓存clone时推荐git clone --depth1遇到私有仓库就仍然走官方客户端配合认证。把这个组合写进团队开发规范里避免大家遇到问题再来问你。5.6 我的几点实操心得最后分享几个我自己摸出来的小技巧。第一个Nginx配置改完先做语法检查和reload这已经成了肌肉记忆nginx -t nginx -s reload但reload只对新连接生效旧的长连接还会保留一会儿如果改的是缓存或限流参数建议直接systemctl restart nginx别省这个事。第二个日志一定不要省。我在nginx.conf里单独给镜像站配了一份访问日志字段带上$upstream_cache_status、$upstream_response_time和$request_time。排障时一眼能看出是上游慢还是本地慢。log_format mirror $remote_addr [$time_local] $request $status $body_bytes_sent $request_time $upstream_response_time $upstream_cache_status; access_log /var/log/nginx/mirror_access.log mirror;第三个别忘了监控磁盘和流量。我写过一个简单的cron脚本每天检查缓存目录占用率超过阈值自动清掉inactive时间最长的文件find /data/nginx_cache -type f -atime 14 -delete比自己盯着磁盘容量踏实多了。镜像站这个东西说到底是给“链路质量不理想环境下的开发工作”提供一个工程化兜底。你把这套流程跑通后再遇到GitHub访问问题心里就有底了不用到处找别人搭的公共镜像自己手里的这套随时能用、能调、能修。后续如果你想加raw文件加速、release大文件缓存甚至团队内部分发都是一样的思路往下扩展就行。