GitHub 访问不稳定这事国内开发者基本都经历过。git clone一个热门项目进度条卡在 30% 死活不动点开 Realease 页面准备下载最新安装包下了 200MB 突然断线更别提有时候连 github.com 主页都要刷新个五六次才能打开。与其整天在别人的镜像站之间来回切换学别人如何“借道”不如自己动手搭一个专属的 GitHub 镜像站。这个镜像站不求替代 GitHub只求把网页浏览、代码拉取、Release 下载这几条关键链路打通让你在访问不稳的时候能顺畅拿到东西。我前后花了两个周末把整套方案跑通中间踩了不少坑。这篇攻略会按照“需求拆解 → 方案选型 → 域名证书准备 → 入口转发层配置 → Git 仓库镜像 → Release 缓存 → 问题排查 → 运维加固”的顺序来写每一步都给配置、给原理、给实操心得。不管你是想给团队搭一个内部中转还是自己折腾着玩照着这套思路基本都能落地。1. 先搞清楚到底要镜像什么很多人一上来就问“怎么搭建 GitHub 镜像站”但这个问题的答案完全取决于你平时用 GitHub 的哪些能力。GitHub 表面上看是一个网站实际上底层由多条完全不同的数据链路组成每条链路的访问瓶颈和缓存策略都不一样。把它们混在一起讨论是做不好镜像的。1.1 GitHub 的四种访问场景拆解我自己把日常对 GitHub 的访问场景分成了四类镜像站要分别应对这四类需求网页浏览包括 github.com 的主页、仓库页面、文件浏览、Issue、PR 讨论等。这类流量以 HTML、CSS、JavaScript 为主体积不大但请求次数多对响应速度敏感而且静态资源分散在 assets-cdn.github.com 等域名下。Git 数据交换也就是git clone、git fetch、git push。这类流量走的是 git 协议或 https 协议每次拉取会把整个仓库的 commit 历史、分支、标签全部传一遍。大仓库动辄几百 MB 甚至几个 GB对带宽和磁盘 IO 的要求最高。Release 与附件下载包括 releases 页面里的源码压缩包.zip、.tar.gz以及项目作者上传的二进制安装包。这类流量是“一次性大文件下载”文件体积大、耗时长断点续传能力差是镜像站最容易出问题的地方。raw 文件与 API 请求raw.githubusercontent.com 被无数脚本和 CI 流程直接引用API 则服务于各种自动化工具。这两类请求并发量高而且很容易触发 GitHub 的限流策略。把这四种场景拆开之后你会发现一个真正的“全栈”镜像站并不能只靠一层简单的反向代理搞定。网页浏览可以用缓存加速Git 数据交换得靠仓库镜像或 git 协议转发Release 下载得做文件级缓存raw 文件还需要单独的缓存策略。如果只做一层 Nginx 反代确实能解决一部分“打不开”的问题但 clone 大仓库和下载 Release 时照样可能失败。1.2 自建镜像和公共镜像站怎么选目前网上有很多公共的 GitHub 镜像站点使用门槛为零打开网页填上地址就能用。但公共镜像的问题也很明显速度不稳定、维护者可能跑路、某些镜像只支持 clone 不支持网页浏览、还可能存在隐私顾虑——你 push 的代码会经过别人的服务器。自建镜像站在可控性上完胜域名是你自己的缓存策略是你自己定的想加什么功能随时加。但代价是你必须有服务器和域名还得承担带宽成本、磁盘成本和日常维护精力。我的建议是个人开发者如果只是偶尔 clone 一个仓库直接临时用公共镜像或者改用ghproxy这类的下载加速服务就够了没必要自建。但如果你是团队协作、需要频繁拉取固定依赖库、或者公司内部安全要求高那才值得自己搭一套镜像站。我接下来讲的方案默认面向后面这类场景。1.3 明确镜像站的服务边界动手之前建议把这几个问题先想清楚因为它们直接决定了你的架构复杂度是只镜像网页还是也要支持 git clone如果只镜像网页一个 Nginx 反代就够了要支持 clone就得处理 git 协议的转发或者做仓库级镜像。是否要支持用户登录和 push 操作镜像站的缓存机制天然适合读多写少的场景。如果团队成员需要往 GitHub 上 push 代码我建议 push 操作仍然走原始 GitHub镜像站只做读取加速否则缓存一致性会让你头疼。是否要给 Release 大文件预留足够的磁盘空间缓存 100GB 的热门安装包和只缓存网页静态资源完全是两种服务器配置。把这些边界划清楚再往下走你会省掉很多返工。2. 镜像站方案选型与整体架构我在搭建之前先画了一张“数据流图”把所有请求从浏览器或 Git 客户端出发到最终拿到数据的路径捋了一遍。整个镜像站可以拆成三层接入与转发层、仓库镜像层、文件缓存层。下面详细讲讲每一层的作用和选型思路。2.1 接入与转发层用什么做入口这一层是所有请求进来的第一道门核心功能是接收用户的请求根据路径把流量分发到 GitHub 原始服务器或者分发给本地缓存、仓库镜像节点。我选择的是 Nginx原因很朴素稳定、性能好、配置灵活而且系统包管理器直接就能装。Caddy 的配置更简洁、自动签发证书很方便但它的灵活性和对缓存插件的支持不如 Nginx 丰富HAProxy 在网络层更强但做不了 URL 级别的路径改写和内容缓存。所以 Nginx 是在“够用”和“可控”之间最平衡的选择。这一层的配置要点有三个一是处理 SSL 证书和 HTTPS 连接二是把请求头里的 Host 和转发地址按规则改写让 GitHub 服务端认为是合法的请求三是对静态资源做内存或磁盘缓存。最后为了降低盘空间压力我还会限制缓存文件大小只缓存 100MB 以下的文件更大的文件走直传。2.2 仓库镜像层Git 数据怎么中转对 Git 数据的镜像我对比了两种主流方案临时转发Nginx 把/user/repo.git/info/refs和/user/repo.git/git-upload-pack等路径直接转发到 github.com。优点是不占本地磁盘实时性高缺点是每次 clone 都会请求 GitHub访问量大时照样慢而且 Nginx 对 git 智能 HTTP 协议的长连接处理需要仔细调参。仓库级镜像同步用 Gitea 或 GitLab 自带的“仓库镜像”功能或者直接写脚本git clone --mirror把远端仓库全量拉到本地服务器上。优点是本地 clone 速度极快相当于 GitLab 的“仓库镜像”功能已经帮你解决了增量同步问题缺点是需要磁盘空间而且同步有延迟。我最后采用的是“双轨策略”对热门大仓库和团队核心依赖用仓库镜像功能提前同步到本地用户 clone 直接命中本地对冷门小仓库走转发链路实时去 GitHub 拉取。这样既保证速度又不至于给磁盘和带宽带来过大压力。2.3 文件缓存层Release 下载怎么救Release 里的安装包是体积最大的流量也是最容易中途断流的部分。GitHub 官方实际上把 Release 文件存放在 S3 存储桶上下载请求会从objects.githubusercontent.com跳转。直接从国内访问这个域名经常很慢。我的方案是在 Nginx 层对/user/repo/releases/路径下的文件做缓存第一次请求时后台去 GitHub 拉取并写入本地之后的请求直接命中本地文件不再回源。为了不把磁盘打满我设置了缓存目录的容量上限并用一个定时任务扫描清理极少访问的文件。关于如何清理旧缓存后面的章节会给具体脚本。2.4 整体架构一目了然如果非要简化成一句人话这个镜像站就是“一台 Nginx 入口机器 一个 Git 仓库镜像目录 一个 Release 缓存目录”。Nginx 拿到请求先问本地缓存有没有有就直接给本地没有就去 GitHub 回源拉取一次同时把结果存下来。用户访问网站页面时实际上就是访问一台“套了 GitHub 皮”的本地缓存服务器用户 clone 代码时实际是从你服务器上的 Git 裸仓库拉取数据。这套架构下你的服务器是用户和 GitHub 之间的“数据摆渡车”首次请求慢一点之后快很多。3. 域名规划与证书前置准备镜像站的所有能力都建立在域名之上。域名规划不好后面所有配置都会乱成一团。我一开始图省事只准备了一个域名结果所有路径都堆在一个域下Nginx 配置里写满了复杂的 if 判断后来痛定思痛把域名结构整理清楚了。3.1 子域名规划建议我建议至少规划三个子域名或者三级域名来承担不同职能这样配置清晰、缓存策略互不干扰子域名用途缓存策略g.example.com网页浏览入口对应 github.com短缓存5 分钟动态页面不做长缓存raw.example.comraw 文件访问对应 raw.githubusercontent.com长缓存24 小时dl.example.comRelease 文件下载对应 objects.githubusercontent.com / release-assets长缓存持久保存git.example.comGit 仓库中转和本地 Git 镜像访问不缓存直接访问本地裸仓库如果只想用一个域名也可以通过路径前缀区分比如example.com/github/...、example.com/raw/...但这样配置起来很别扭。给每个职能分配一个子域名是后期最省心的方案。3.2 DNS 解析怎么配我在 DNS 服务商那里把上述子域名都加了 A 记录指向镜像站服务器的 IP。如果你有多台服务器或者使用了国内云厂商的负载均衡也可以使用 CNAME 解析到负载均衡域名。需要注意的一点是如果你用了国内服务器域名必须完成备案否则 80 和 443 端口会被拦截如果你的服务器在海外比如香港或新加坡域名不需要备案但访问延迟可能稍高一些。我自己的服务器在境外这样既绕开了备案流程又保证了国内直连的可用性。不过这个选择需要你自己权衡。3.3 HTTPS 证书准备镜像站承载的是 HTTPS 流量证书是必需品。我用 acme.sh 申请泛域名证书*.example.com一张证书可以覆盖所有子域名比每子域名单独申请方便得多。泛域名证书的申请流程如下安装 acme.sh并设置默认的 CA用 DNS API 模式申请acme.sh 会在你的 DNS 服务商处自动添加一条 TXT 记录完成域名验证证书签发后设置自动续期定时任务申请完成后证书文件会放在/etc/nginx/certs/目录下Nginx 配置里直接引用即可。此处要提醒一句证书自动续期之后务必 reload Nginx否则 Nginx 会一直使用内存里的旧证书直到过期才暴露问题。我在第一次自动续期时就吃了这个亏Cron 任务明明执行了但 Nginx 没 reload结果用户访问时提示证书已过期吓得以为域名被劫持了。4. 入口转发层Nginx 反向代理的完整配置这一节是整篇攻略的核心。我把自己实际在用的 Nginx 配置精简再精简去掉和业务相关的敏感信息后整理如下。每一段配置我都会解释“为什么这么写”方便你按自己的场景调整。4.1 基础配置框架我习惯把每段功能写成独立的配置文件放进/etc/nginx/conf.d/下然后用include组装。下面是一个典型的虚拟主机配置server { listen 80; server_name g.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name g.example.com; ssl_certificate /etc/nginx/certs/example.com/fullchain.cer; ssl_certificate_key /etc/nginx/certs/example.com/example.com.key; ssl_protocols TLSv1.2 TLSv1.3; gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml; gzip_min_length 1024; }这里有个容易被忽略的细节GitHub 官方支持 HTTP/2如果你的 Nginx 开启了http2用户在访问你镜像站时也能获得多路复用的好处尤其是在加载网页里的多个静态资源时速度提升明显。但需要注意http2必须和listen 443 ssl写在同一行新版 Nginx 允许用单独的http2 on;指令老版本不支持。4.2 网页浏览路径的转发规则网页浏览的核心是把g.example.com的请求转发到github.com同时把响应里的链接改写让用户后续点击仍然停留在你的域名上。直接转发很简单但“改写响应中的链接”是个大坑。GitHub 的 HTML 页面里会有大量绝对链接比如https://github.com/user/repo。如果不做改写用户点一个链接就会跳回原始 GitHub镜像站就形同虚设。我的处理方式是在 Nginx 里用proxy_set_header把Host头设为github.com让 GitHub 认为请求确实来自 github.com响应返回时再用sub_filter把 HTML 中的https://github.com/替换为https://g.example.com/。示例配置如下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; sub_filter_once off; sub_filter https://github.com/ https://g.example.com/; sub_filter http://github.com/ https://g.example.com/; }sub_filter_once off表示替换响应中所有出现的匹配字符串而不是只替换第一个。这里最容易踩的坑是GitHub 页面里的部分资源比如*.githubusercontent.com、*.githubassets.com也需要替换但替换规则写太多会消耗 CPU。我的做法是把最常用的几个域名替换掉其他的资源让浏览器自行跨域加载因为很多资源实际上有全球 CDN 节点速度不算太差。4.3 Git 数据转发规则Git 的 smart HTTP 协议有两类关键的 HTTP 请求一类是GET /user/repo.git/info/refs?servicegit-upload-pack用于获取引用列表另一类是POST /user/repo.git/git-upload-pack用于获取 commit 数据。要让 Git 客户端通过镜像站 clone就必须把这两个路径也转发到 GitHub。下面这段配置放在同一个 server 块里location ~ ^/([^/])/([^/])\.git/ { 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_pass https://github.com;后面不能带 URI否则会覆盖匹配到的路径第二Git 客户端发送的请求有较长的头部和 body需要适当调大client_max_body_size和client_body_buffer_size。大仓库 push 时 body 可能达到几百 MB默认的 1MB 限制会导致 push 直接失败。建议在 server 块里加client_max_body_size 1024m; proxy_read_timeout 300s; proxy_send_timeout 300s;proxy_read_timeout尤其重要。如果发往 GitHub 的回源请求长时间没有响应Nginx 默认 60 秒就会断开大仓库 clone 时经常卡在“收对象”阶段然后掉线。我调到 300 秒后大部分极端情况都扛过去了。4.4 静态资源与缓存策略GitHub 网页的静态资源并不在 github.com 域名下而是分布在github.githubassets.com、avatars.githubusercontent.com、camo.githubusercontent.com等域名下。直接转发这些域名也可以但更高效的做法是在 Nginx 本地做一层磁盘缓存减少跨网络回源次数。我用 Nginx 的proxy_cache模块实现proxy_cache_path /data/nginx_cache levels1:2 keys_zonegithub_cache:500m max_size20g inactive7d; location ~ ^/(assets|avatars|images)/ { proxy_pass https://github.githubassets.com; proxy_cache github_cache; proxy_cache_valid 200 24h; proxy_set_header Host github.githubassets.com; }max_size要按服务器磁盘容量调整我一开始设了 50g结果半个月就把一块数据盘写满了后来改成 20g 加定期清理脚本才压住。重要提醒proxy_cache_valid 200 24h只缓存 HTTP 200 响应不要对 301、302 做缓存否则会缓存错误的跳转另外 GitHub 的有些页面带登录态内容因人而异所以对 HTML 页面我只做了短时间缓存或者干脆只缓存静态资源。4.5 转发层错误处理镜像站回源时偶尔会遇到 GitHub 返回 502、503 或者连接超时这时候用户看到的是 Nginx 默认的错误页体验很差。我给location /加了一个错误页兜底error_page 502 503 504 /maintain.html; location /maintain.html { root /var/www/html; internal; }maintain.html是一段静态页面提示“镜像站正在同步数据请稍后再试”顺便放一个回源链接。这个页面要做得很简洁避免用户在打不开 GitHub 的时候看到一个更打不开的报错页面。5. Git 仓库镜像让 clone 和 push 都有去有回Nginx 转发方案能解决“能不能访问”的问题但对频繁 clone 的核心仓库来说速度依然不够。为此我引入了 Git 仓库镜像层把仓库直接同步到本地用户 clone 时命中本地数据几乎等于内网速度。5.1 方案对比Gitea 自动镜像 vs 脚本手动同步我用过两种方式实现仓库镜像先说结论有现成的 Git 管理需求就上 Gitea只想当“哑缓存代理”就写脚本。Gitea 自动镜像Gitea 自带“仓库镜像”功能只需要在仓库设置里填上源仓库地址、用户名和 Token它就会按你设定的间隔最小 10 分钟自动同步。同步完成后用户可以到你的 Gitea 页面浏览代码同时也能 clone。好处是自带 Web UI免费坏处是它本质是一个完整的 Git 服务会占资源如果你只是想要一个“数据缓存”用 Gitea 有点杀鸡用牛刀。脚本手动同步用git clone --mirror拉取裸仓库再设置定时任务执行git remote update实现增量同步。好处是极轻量只需要 git 和 crontab坏处是没有页面可浏览需要自己写个简单的仓库列表页面。我最终选择了 Gitea。不是因为它的镜像功能多么花哨是因为我在搭建镜像站时顺带发现团队里有几个仓库确实需要一个统一的 Git 入口而 Gitea 开箱即用的 Web 页面和用户管理帮我少写了不少代码。5.2 脚本手动同步方案轻量版如果你只需要同步一个仓库并把它作为 git 只读缓存可以这样操作git clone --mirror https://github.com/username/repo.git /data/git-mirror/username/repo.git # 更新脚本 update_mirror.sh for repo_dir in /data/git-mirror/*/*.git; do cd $repo_dir git remote update --prune done然后写人 crontab*/30 * * * * /usr/local/bin/update_mirror.sh /dev/null 21用--mirror克隆的仓库会把远程所有的 refs分支、标签、PR refs完整复制过来后续增量同步时git remote update --prune会把源端删除的分支也同步删掉。但要注意--mirror仓库默认使用file//协议裸存储默认情况下不能直接 push只适合做只读镜像。如果你需要承接团队的 push 操作请改用git clone --bare并额外配置receive.denyCurrentBranch ignore但这已是另一个复杂话题建议直接使用 Gitea。5.3 给 Git 客户端做“URL 改写”镜像站搭好之后如果每次 clone 都要手动把https://github.com/改成https://git.example.com/那使用成本太高了。更优雅的方案是在 Git 客户端配置url.base.insteadOf让 Git 自动重写 URLgit config --global url.https://git.example.com/.insteadOf https://github.com/ git config --global url.https://github.com/.insteadOf https://git.example.com/第一条是让所有指向github.com的请求都走你的镜像站第二条是防止某些仓库自带硬编码的本地地址导致循环。需要注意的是insteadOf配置必须在客户端发起请求前生效所以如果你们团队的成员较多可以把这段配置写进一份共享的.gitconfig文档或者做成一个安装脚本让新人一键配置。5.4 镜像同步的隐藏风险同步 Git 仓库时最常碰到的坑是“同步到一半GitHub 对匿名请求限流”。git clone --mirror使用的匿名 https 请求在特定 IP 上做高频操作时很容易触发 GitHub 的限流表现为remote: Repository not found.或者fatal: unable to access ... : The requested URL returned error: 429。解决办法有两个一是用带 Token 的地址克隆https://TOKENgithub.com/user/repo.gitToken 只需读权限二是降低同步频率从 10 分钟一次改成 1 小时一次。另外仓库体积比较大的项目比如包含大量历史版本的内核或工具链仓库做镜像时会拉下一大堆历史数据占用磁盘非常可观。我看到过一些仓库动辄十几 GB 的裸库在磁盘规划时一定要按仓库数量的 1.5 到 2 倍预留空间。6. Release 与 raw 文件访问的缓存优化Release 下载是镜像站流量的大头也是让服务器磁盘消耗最快的地方。我单独拿出一个章节讲它因为很多教程根本没意识到对 Release 做缓存不只是“存个文件”那么简单。6.1 Release 下载路径的转发与缓存GitHub Release 文件的真实下载地址并不在 github.com 域下而是隐藏在objects.githubusercontent.com等域名上。当你请求https://github.com/user/repo/releases/download/v1.0.0/app.zip时GitHub 会返回一个 302 跳转指向实际文件地址。镜像站在转发这个请求时如果直接透传 302用户最终还是会访问到 GitHub 的存储地址镜像站只起到了“带路”作用速度没有改善。要让下载请求真正命中镜像站需要在 Nginx 层把 Release 下载路径单独处理将请求转发到 GitHub 获取文件并缓存到本地磁盘。我用的配置如下location ~ ^/([^/])/([^/])/releases/download/ { proxy_pass https://github.com; proxy_set_header Host github.com; proxy_cache github_cache; proxy_cache_key $uri; proxy_cache_valid 200 7d; proxy_max_temp_file_size 0; # 临时文件常驻内存避免下载文件时反复写零散的临时块 }细节一proxy_cache_key $uri让相同路径的请求永远命中同一个缓存避免带查询参数污染缓存。细节二我没有对 302 跳转缓存。因为 GitHub 返回 302 指向的资源地址会定期换签缓存 302 可能导致后续用户访问时跳转失效。细节三大文件下载时Nginx 默认会把文件临时写到代理缓冲区proxy_max_temp_file_size 0可以避免临时文件频繁刷盘但也会增加内存开销要按 Nginx worker 进程数和总内存权衡。6.2 raw 文件访问的缓存raw.githubusercontent.com上的文件一般内容稳定、变更不频繁很适合长时间缓存。很多项目的安装脚本比如curl .../install.sh和 CI 流程都会访问 raw 文件如果每次访问都回源白白浪费带宽还可能被限流。我给 raw 文件单独配了一个 server 块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_cache raw_cache; proxy_cache_valid 200 24h; proxy_cache_key $uri; } }由于 raw 文件大多是文本或源代码体积小、数量多且被脚本大量引用所以这里缓存时长可以设长一点。要注意的是raw.githubusercontent.com 的目录结构是/user/repo/branch/path/file其中的branch通常是一个分支名但分支的内容会变如果你的镜像站长时间缓存分支上的旧文件可能给团队开发带来困惑。所以对master/main分支上的 raw 文件我建议缓存时间缩短到 30 分钟或 1 小时而带tag路径的 raw 文件可以放心缓存 24 小时以上。6.3 缓存清理与磁盘水位监控缓存目录无论设置多大总有满的时候。Nginx 的max_size参数只是一个“软上限”达到后会启动淘汰机制但它淘汰策略非常粗放不一定符合你的优先级。我写了一个脚本每小时执行一次把缓存目录下超过 7 天没有访问的大文件清理掉find /data/nginx_cache -type f -size 50M -atime 7 -delete find /data/nginx_cache -type d -empty -delete还要加一个磁盘水位监控当磁盘使用率超过 85% 时自动清理最大的一批缓存文件df -h /data | awk NR2{ if ($50 85) system(find /data/nginx_cache -type f -printf \%s %p\\n\ | sort -rn | head -100 | awk {print $2} | xargs rm -f) }这个脚本看起来简单但实际效果很稳。我刚开始搭镜像站时没做清理一周后 50G 缓存盘就爆了然后 Nginx 疯狂报no space left on device连网页都打不开惨痛教训。7. 常见问题与排查思路实录运行镜像站这几个月我遇到过不少奇怪问题。这一节把这些问题和排查过程整理成一份速查表再挑几个典型的详细讲解排查思路。7.1 速查表现象可能原因排查与解决访问镜像站提示“证书不安全”泛域名证书覆盖的子域名不全或证书未续期检查证书文件有效期确认server_name包含该子域名续期后执行nginx -s reload网页能开但图片、CSS 加载失败静态资源域名未做替换或未走镜像检查sub_filter规则确认资源域名的 Nginx 转发配置存在git clone卡在Receiving Objects回源连接超时、带宽拥塞调大proxy_read_timeout至 300s确认本地磁盘有余量考虑改用仓库镜像clone 时出现repository not foundGitHub 对匿名请求限流换用带 Token 的镜像同步地址降低同步频率Release 大文件下载中途断流Nginx 代理缓冲区配置不当、网络不稳定调大proxy_buffer_size设置proxy_max_temp_file_size 0客户端使用支持断点续传的下载工具镜像站磁盘被缓存文件写满缓存清理未执行或 max_size 过大添加定时清理脚本调小max_size监控磁盘水位部分仓库页面显示“登录后才能访问”仓库是私有仓库匿名访问被限制私有仓库无法镜像换用带 Token 的正向访问方式或者只镜像公开仓库7.2 典型问题证书更新后 Nginx 没加载新证书这个问题我前面提过再展开讲讲。acme.sh 的定时任务默认会把证书续期后的文件放到原路径然后执行一个 deploy hook我在 hook 里写的是nginx -s reload。但有一次我发现系统里同时存在两个证书目录acme.sh 写入的新目录和 Nginx 引用的旧目录不是同一个路径。排查了半小时才发现acme.sh 默认使用--install-cert时会把文件复制到指定目录而我没有指定--reloadcmd参数导致 deploy hook 根本没执行。正确姿势是在安装证书时指定acme.sh --install-cert -d example.com --key-file /etc/nginx/certs/example.com.key --fullchain-file /etc/nginx/certs/fullchain.cer --reloadcmd nginx -s reload7.3 典型问题Nginx 缓存了“错误的页面”有段时间镜像站首页偶尔会显示 GitHub 的 404 页面用户访问某些仓库时也经常看到“项目不存在”。问题出在proxy_cache_valid 200 24h配置GitHub 对不存在的仓库返回的其实是 200 自定义 404 页面然后 Nginx 把这个页面当正常 200 响应缓存了 24 小时导致后续所有访问都命中这个假页面。解决方法是在缓存之间先对响应码做精细判定proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m;把 404 的缓存时间缩短到 1 分钟同时配合proxy_cache_key $uri让带不同路径的请求不互相污染缓存。页面类内容不要贪心缓存太久缓存的不仅仅是内容还有“错误”。7.4 典型问题大仓库 clone 时断流有一个仓库包体积不小clone 时经常到 80% 就报RPC failed; curl 18 transfer closed with outstanding read data remaining。刚开始以为是带宽问题后来盯了 Nginx 日志才发现是回源请求被自己设置的proxy_read_timeout 60s给杀了。Git 拉取大量对象时连接长而静默Nginx 的读超时策略很难区分“网络假死”和“正在传输”只好粗暴地调大超时时间。我把相关配置都调成 300s并加了proxy_buffering on配合本地磁盘缓冲之后就没再出现过类似断流。8. 性能、安全与日常运维心得镜像站跑起来只是一个开始想让它长期稳定地服务还需要在性能、安全和日常运维上下功夫。这节分享一些我在实际维护中总结的心得。8.1 性能调优缓存策略与带宽控制优先缓存“兵家必争之地”网页静态资源、Release 文件、raw 文件。GitHub API 和动态页面不要做长缓存否则你会得到一堆过期数据还不如不去缓存。开启 HTTP/2 和 KEEPALIVENginx 到客户端的连接启用 keepalive能明显减少 TCP 握手产生的延迟。特别是在网页浏览这种“大量短请求”的场景下这个优化收益很高。带宽限速如果服务器带宽有限给大文件下载加一个限速避免一个用户占满全部带宽location ~ ^/([^/])/([^/])/releases/download/ { limit_rate 10m; }limit_rate 10m表示单个连接限速 10MB/s。10MB 对个人下载已经够用如果团队带宽更低可以调到 5m 或 2m。不要设太低否则下载一个 1GB 的包要等很久用户体验很差。8.2 安全加固防御滥用与畸形请求一个放在公网上的镜像站很容易被各种扫描器和爬虫白嫖带宽。我在 Nginx 里加了这几个“最低成本”的防线限制 User-Agent屏蔽常见的爬虫 UA空 UA、Python requests、curl 等对动态页面的访问但注意不要屏蔽掉正常 Git 客户端的 UA比如git/2.39.0。限制 GET 之外的方法镜像站绝大多数请求都是 GET其他方法POST、PUT、DELETE可以直接返回 403避免被人用你服务器做跳板。访问频率限制limit_req_zone $binary_remote_addr zoneimglimit:10m rate5r/s; location / { limit_req zoneimglimit burst20 nodelay; }对同一个 IP 做每秒 5 次请求的限制可以挡掉一部分明显的爬虫但在校园网或公司 NAT 环境下一个出口 IP 后面可能有很多人限得太狠会影响正常使用。我建议把限制设在 10r/s 左右观察日志再调整。不要缓存敏感页登录页面、设置页面、私人仓库页面不要做缓存。这些页面涉及用户隐私数据而且 GitHub 对会话有严格的安全策略缓存的页面会造成会话错乱。我的做法是直接用proxy_no_cache对 Cookie 请求设置不缓存proxy_no_cache $cookie_session; proxy_cache_bypass $cookie_session;8.3 日常运维与监控运维环节最怕的不是“出事”而是“出事之后不知道哪里出了问题”。我搭了一套简单的监控组合nginx 的 access log 按天切割配合 logrotate用logwatch或fail2ban扫描 Nginx 的错误日志对频繁触发 4xx、5xx 的 IP 做临时封禁配置一个简单的 webhook让定时任务在“磁盘使用率 85%”或“Nginx 进程挂了”时推送告警到飞书或钉钉群每周手动检查一次证书剩余有效期。另外我强烈建议把整个镜像站的配置文件和脚本用 Git 管起来。所有配置放在一个仓库里改动都有历史记录出问题可以直接git revert。这个方法朴素但异常好用我在调整子域名转发规则时改崩过一次花了半小时才定位到问题如果一开始就有版本管理十分钟就能恢复。8.4 最后一个小技巧给镜像站配一个“健康检查”Nginx 配置里有一个stub_status模块可以输出连接数和请求统计。我把它挂在一个内网路径上用curl做健康检查每五分钟打一次发现Active connections连续三次异常就自动拉起一个新的 Nginx 进程。这个监控不复杂但能让你尽早感知问题。实际上日常维护镜像站最大的敌人不是流量而是“它明明挂了你却两天后才发现”一套简单的监控告警机制比任何高性能调优都值钱。以上就是我搭建 GitHub 镜像站的全部心得。这套方案没有追求“一条命令跑起来”的简易因为镜像站本来就是一件需要长期维护的事每一个细节都用上了才能让你的团队下次 clone 代码时不再咒骂断流。如果你也搭了一个遇到问题欢迎在评论区交流我可以把更细的时区日志和网络排查脚本整理成番外篇。