GitHub镜像站这话题跟代码打了十年交道的人多少都动过心思。我自己也是从“clone一个仓库老半天还失败”这种抓狂状态开始的——明明仓库只有几十兆网络一波动就断断了还得重来。后来折腾了一圈发现与其到处找现成的镜像碰运气不如自己动手搭一套。这篇就把我从选型到落地的完整过程摊开讲包括踩过的坑给同样被仓库同步问题折磨的朋友一条能直接照抄的路。先说清楚你搭出来的东西能干什么、适合谁。自建GitHub镜像站本质是把你关心的代码仓库同步到自己的服务器、内网或本地形成一个独立于上游的副本。它解决三个很实际的问题一是代码备份上游仓库万一被删或暂时不可用你有完整副本兜底二是团队协作多台机器从内网镜像拉代码比每次都直连上游省心三是离线归档把仓库冻结成某个时间点的快照长期保存。适合的人包括个人开发者、小团队维护者、需要为CI/CD流程准备稳定代码源的运维同学以及那些对代码所有权比较敏感、想在本地留存一份完整历史的技术负责人。1. 为什么需要自建GitHub镜像站场景与定位1.1 镜像站在解决什么问题先帮容易混淆的朋友理清楚GitHub镜像站不是把GitHub首页抄一份而是把仓库数据包括所有分支、标签、提交历史完整同步到自己的环境里。这跟用浏览器保存网页是完全不同的事也比“只是下载某个releases压缩包”重得多——因为你要的是整个Git仓库的全部历史而不仅仅是某一个时间点的快照。在真实工作里我遇到过几种典型情况都指向同一个需求。比如团队在局域网内搞开发外网带宽有限每次新同事入职要拉一遍公司所有依赖仓库直连上游不仅慢还可能因为网络波动反复中断。再比如自己做开源项目维护上游某天把仓库设为只读甚至删掉本地若是没有完整镜像历史贡献记录就全没了。还有一个场景是做离线交付客户现场不允许连外网但又需要把整套源码包括历史记录都搬到对方服务器上这时候一个提前同步好的镜像目录就是最直接的交付物。1.2 三种镜像形态怎么选我把这半年见到的方案归成三类按“从轻到重”排开。第一种是单仓库镜像也是一切的基础形态。用Git自带的裸仓库机制把一个仓库完整clone到本地之后定期跑增量同步。做法简单、依赖少缺点是同步对象多了以后管理成本上升如果你想给团队提供一个统一入口光靠裸仓库目录还差了层应用外壳。第二种是多仓库镜像通常是基于一个服务端应用来做的。Gitea、GitLab都内置了仓库镜像功能你把上游仓库地址和凭证填进去服务端定期抓取再用自身的Web界面暴露出来。这条路的好处是天然带权限管理、支持HTTP(S)免密拉取、有UI能看到每个仓库的同步状态适合团队使用或小规模对内服务。第三种是平台级镜像说白了就是架一个缓存层来承接所有对上游的访问请求。这种方式更多偏反向代理加内容缓存跟Git仓库的数据一致性不太是一回事对代码场景来说意义不大而且实现复杂、合规风险也高我一般不建议在这个方向上花时间。自建GitHub镜像站最实用的是“第二种为主、第一种兜底”的组合。Gitea做UI和权限层底层每个仓库本质仍是裸仓库既保留了Git的高效同步机制又提供了友好的访问方式。1.3 自建前需要准备的东西一台服务器或长期开机的机器Linux优先推荐Ubuntu 20.04/22.04 LTS或Debian 11/12。配置不用太高2核2G起步就能跑动小规模镜像站真正的瓶颈通常在磁盘带宽和IOPS。足够的磁盘空间这一步我吃过亏。Git仓库的历史比你以为的大得多尤其那些带大量二进制资产比如游戏资源、模型文件的项目仓库体积能轻松上GB。建议先把你计划同步的仓库整理出来逐个查一下体积再加至少50%的余量。一个域名和一套HTTPS证书如果你只是自己本机用这一步可跳过但一旦面向团队提供服务建议用域名加Lets Encrypt证书省去一堆客户端信任问题。访问凭证同步公开仓库其实不需要账号但同步私有仓库或者为了避免触发上游限流需要准备一个GitHub Personal Access Token权限只需勾选repo相关的最小范围即可。2. 核心原理Git镜像同步是怎么工作的2.1 bare仓库与镜像克隆要理解镜像站先要把“日常使用的仓库”和“镜像用的裸仓库”分清楚。普通git clone出来的目录里包含两部分一是工作区就是你能看到、能编辑的实际文件二是.git目录里面存了全部分支、提交历史、对象数据库。而镜像站要做的不是让人类坐在那编辑代码而是完整保存历史供其他人clone因此只需要.git这一半就足够了。这就是裸仓库bare repository的由来。用git clone --mirror创建出来的仓库没有工作区只有完整的历史对象和引用refs。它跟你平时clone出来的目录里那个.git在结构上几乎一样区别就在于它作为镜像的唯一目的就是接收推送和给别人clone。从同步角度说用bare仓库当镜像底座不会出现“工作区文件跟上游不一致”的额外麻烦省掉了一整类冲突问题。选择使用--mirror而不是普通--bare关键差异在于mirror模式会把上游的所有引用原样映射过来包括分支、标签还有那些藏在refs/pull底下的pull request引用。普通bare模式只关心常规分支和标签遇到PR引用会比较尴尬。既然做镜像目标就得是“上游有什么我有什么”所以--mirror是唯一合理选择。2.2 增量同步与引用管理镜像同步的第二个核心概念是增量同步。Git仓库本身就是一套对象数据库每个提交、每个文件版本都对应一个对象对象之间用哈希互相引用。正因为有这个结构第二次同步完全不需要像第一次那样把整个仓库重新拖一遍只需要把上游新增的对象拉下来即可。实际操作中同步命令的核心是git fetch。对裸仓库执行git fetch --prune origin--prune修剪很关键它负责删除上游已经不存在的引用保证镜像里不会残留上游删掉的旧分支或旧标签。如果没有这一步镜像是会“长胖”的——上游删掉的东西你这里永远留着日积月累既是存储浪费也可能把一些敏感历史在镜像里保留得比上游还久。有一个细节值得单独提git clone --mirror初始化出来的仓库默认已经配置好了remote.origin.fetch规则为refs/*:refs/*也就是把所有引用都映射过来。但如果你自己手动创建裸仓库再手动添加remote这个特殊规则得手动补上否则fetch默认只同步特定分支达不到镜像效果。2.3 触发方式定时任务与Webhook知道了“怎么同步”接下来要考虑“什么时候同步”。两种主流的触发机制各有取舍。定时同步是最容易上手的。通过系统的cron服务按固定间隔比如每小时执行fetch脚本。优点是逻辑简单、可预期、不会因为上游某个接口抖动导致漏跑缺点是时效性差一点上游刚推送的提交可能要等到下一个周期才出现在镜像里。事件触发Webhook更聪明。GitHub支持在仓库上配置Webhook当有push、tag创建等事件时向上游发送一个HTTP POST请求。你在自己的镜像服务器上开一个小服务接收这个请求一旦收到就立即触发同步。这样能做到“上游一推送镜像秒同步”而且只在真正有变化时才消耗同步资源。实际生产环境里我推荐的做法是把两者结合日常以15分钟或1小时级别的定时任务兜底同时给重点仓库配置Webhook做即时同步。定时任务保证不会错过Webhook提升新鲜度互相补位。3. 实操从零搭建一个可用的镜像站3.1 准备服务器与基本环境这里用一个最小可用方案做示范一台Ubuntu 22.04服务器目标是把指定的公开仓库镜像到本地并通过Nginx提供HTTP(S)访问。以下是初始化时需要装的东西sudo apt update sudo apt upgrade -y sudo apt install -y git nginx cron curl装完之后我习惯建一个专门用户来运行同步脚本比如gitmirror用户。不要用root直接跑避免脚本出问题时权限边界过大。同时规划好目录结构sudo useradd -r -m -s /bin/bash gitmirror sudo mkdir -p /srv/git-mirror sudo chown gitmirror:gitmirror /srv/git-mirror sudo su - gitmirror目录规划这一步看起来只是创建文件夹其实是在为后续扩展打基础。将来你可能会同时维护几十个仓库如果目录结构从一开始就是“每仓一目录、仓库名带命名空间”后边写脚本和排查问题都会轻松很多。3.2 用bare仓库加定时脚本同步目标仓库第一个要镜像的仓库我建议挑一个小型但完整的目标——既有分支也有标签方便验证流程。比如一个Python命令行工具项目体积几十MB那种就合适不要上来就拿几十GB的大仓库练手。初始化镜像仓库的命令cd /srv/git-mirror git clone --mirror https://github.com/yourname/your-project.git第一次clone的时间取决于仓库大小和网络状况耐心等它跑完。完成后你会看到your-project.git这个目录进去执行git branch -a和git tag能对比确认上游的分支、标签都同步过来了。然后写同步脚本。我把它命名为sync-mirror.sh放在/srv/git-mirror/scripts/下#!/bin/bash GIT_DIR_BASE/srv/git-mirror for repo_dir in $GIT_DIR_BASE/*.git; do [ -d $repo_dir ] || continue repo_name$(basename $repo_dir) echo Syncing $repo_name git -C $repo_dir fetch --prune origin if [ $? -ne 0 ]; then echo ERROR: Failed to sync $repo_name at $(date) /srv/git-mirror/sync-errors.log fi done脚本逻辑非常简单遍历/srv/git-mirror下所有.git目录逐个fetch。把错误信息追加到日志文件里方便后续排查。然后给脚本加执行权限chmod x /srv/git-mirror/scripts/sync-mirror.sh sudo chown -R gitmirror:gitmirror /srv/git-mirror/scripts配置定时任务编辑gitmirror用户的crontabsudo crontab -u gitmirror -e写入*/15 * * * * /bin/bash /srv/git-mirror/scripts/sync-mirror.sh到这里第一套最朴素的镜像站已经跑起来了每15分钟自动同步一次所有历史完整保存在/srv/git-mirror下。团队里的成员可以直接从这个目录git clone或者把它添加为本地remotegit clone file:///srv/git-mirror/your-project.git3.3 用Gitea搭建带UI的镜像站裸仓库方案够用但对团队不友好没有界面、没有权限体系、别人想浏览代码得靠命令行操作。这时候Gitea就派上用场了。Gitea是一个轻量级的Git托管应用自带仓库镜像功能非常适合当镜像站的Web外壳。安装Gitea的过程用二进制方式不折腾Docker依赖更少# 下载Gitea二进制注意替换成最新版本号 wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.21.11/gitea-1.21.11-linux-amd64 chmod x /usr/local/bin/gitea # 创建运行用户和数据目录 sudo adduser --system --group --disabled-password --shell /bin/bash gitea sudo mkdir -p /var/lib/gitea/{custom,data,log} sudo chown -R gitea:gitea /var/lib/gitea sudo chmod -R 750 /var/lib/gitea然后编辑配置文件/etc/gitea/app.ini。核心几项[server] HTTP_PORT 3000 DOMAIN git.example.com ROOT_URL https://git.example.com/ [repository] MIRROR_QUEUE_LENGTH 1000启动Gitea后在管理后台创建管理员账号然后进入“站点管理 → 用户 → 编辑 → 仓库镜像”勾选允许用户创建镜像仓库。这一步不做用户那边看不到镜像功能入口。接下来用管理员或普通账号登录右上角“”号选择“新建镜像仓库”。填写上游仓库地址比如https://github.com/yourname/your-project.git。如果上游是私有仓库在“鉴权”部分填用户名和Personal Access Token。同步间隔给个建议值我个人习惯设成3小时或6小时太频繁意义不大还会占用上游API配额。Gitea的镜像功能本质上就是在底层帮你维护一个裸仓库并定时fetch只不过这一切都包在了友好的界面和权限体系里。底层目录通常在/var/lib/gitea/data/gitea-repositories/用户名/仓库名.git你也可以对它做额外的备份操作。3.4 对外访问Nginx配置与目录浏览镜像站最终要让人用得顺手HTTP访问这关得过。给Gitea配反代同时让/srv/git-mirror下的裸仓库也能通过HTTP直接clone我建议分两层处理。Nginx反代Gitea的配置片段server { listen 443 ssl; server_name git.example.com; ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }如果还想让裸仓库目录直接走HTTP clone可以在同一台Nginx上加一个server块指向/srv/git-mirror并开启目录浏览。但这么做有个前提Git智能HTTP需要依赖git-http-backend这个CGI程序纯静态文件服务是跑不了clone的。要支持HTTP clone正确的做法是再配一个location指向location ~ ^/git(/.*)?$ { fastcgi_pass unix:/var/run/fcgiwrap.socket; include fastcgi_params; fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend; fastcgi_param GIT_PROJECT_ROOT /srv/git-mirror; fastcgi_param GIT_HTTP_EXPORT_ALL ; }这一步稍微有门槛如果暂时用不上建议先专注把Gitea配好——团队通过Gitea拉代码已经完全够用了裸仓库的HTTP访问属于加分项。4. 常见问题与排查技巧4.1 同步失败与认证问题我踩得最多的一类坑就是token权限不够或token过期导致私有仓库同步静默失败。git fetch的错误有时候很模糊可能是Authentication failed也可能是could not read Username。排查时先手动执行一次fetch看真实报错再用GIT_TERMINAL_PROMPT0环境变量禁止交互式输入逼出明确的认证失败信息GIT_TERMINAL_PROMPT0 git -C /srv/git-mirror/your-project.git fetch --prune originGitHub的token需要勾选repo权限才能读私有仓库。另外注意GitHub对未认证请求有速率限制频繁同步大量仓库很容易撞限流。解决办法是在fetch命令里带上token让请求变成认证状态限额会宽裕不少。远端URL可以写成https://用户名:tokengithub.com/owner/repo.git但这样token会明文落在仓库配置里有泄露风险更稳妥的做法是用Git的credential helper来管理。4.2 磁盘与性能问题镜像站最大的隐患是磁盘被静默填满。Git仓库不会自动压缩同步一个大仓库几百次之后对象数据库里会有不少冗余对象体积膨胀明显。建议给每个仓库做定期维护git -C /srv/git-mirror/your-project.git gc --aggressive --prunenow不过注意gc --aggressive非常吃CPU和IO跑大仓库时可能持续几十分钟甚至几小时最好安排在低峰期执行。另外要监控df -h我给镜像站设置过磁盘告警阈值磁盘使用率超过80%就告警别等到满了才处理。还有一个容易被忽略的问题inode耗尽。小文件极多的仓库比如node_modules被误提交进去的会吃光inode磁盘看起来还有空间但任何创建文件的操作都失败。用df -i检查inode使用率别只盯着容量。4.3 访问层问题Nginx配好了客户端却clone不了优先检查几个方向一是证书链是否完整很多自签证书或Lets Encrypt配置不当会导致客户端直接拒绝连接二是Gitea的ROOT_URL是否跟实际访问域名一致这个不一致会导致Gitea页面里生成的clone地址是错的三是防火墙有没有放行对应端口这个最简单但最容易漏。如果用户反馈clone速度慢先看是不是镜像服务器本身带宽瓶颈再检查有没有在Nginx层开gzip压缩——文本类代码文件压缩率很高能显著节省带宽。另外注意不要让Nginx的access_log无限制增长日志塞满磁盘这种事每天都在发生。5. 进阶玩法与维护建议5.1 按需同步与批处理镜像站跑起来之后你会很快遇到“仓库到底同步哪些”的问题。一开始手工维护列表还行仓库多了就得考虑用一个源清单文件来驱动同步脚本。我现在的做法是维护一个repos.txt每行一个上游仓库地址脚本读取后逐个检查本地是否已有镜像没有就clone有就fetch。这样新增仓库只需要往文件里加一行不需要改脚本。还要学会“按需浅同步”作为补充。有些仓库历史特别长、体积巨大全量镜像成本太高但团队实际上只需要最近若干提交或某些已发布版本。Git本身支持--depth浅克隆和--shallow-since按时间深度克隆这类仓库可以单独走一个“浅镜像”策略不追求完整历史只保证常用分支和标签可用。注意不要把浅镜像和全量镜像混在一个目录里脚本要按类型分开管理。5.2 归档与灾备自己辛辛苦苦搭的镜像站如果本身丢了数据就非常讽刺。所以镜像站也要有备份策略这一点容易被人忽略。裸仓库目录本身完全可以用rsync或tar做离线备份rsync -av --delete /srv/git-mirror/ /backup/git-mirror/但是要记住不要在Git仓库正在fetch时做备份哪怕rsync能处理正在变化的文件备份出来的结果也可能是一致性存疑的状态。更稳妥的做法是先进行一次git fetch确认同步完成后短暂停止同步服务比如停掉定时任务再跑备份备份完恢复任务。备份频率可以比同步低不少每天或每周一次都行取决于你对数据丢失的容忍度。冷备之外的补充手段是把关键仓库的更新事件做成通知。我的做法是在同步脚本里加一个钩子每次fetch有新增提交时往企业微信群或邮件发一条摘要。这个小改动对团队感知镜像新鲜度很有帮助。5.3 合规与运维注意事项镜像站在技术上是中性的但使用边界要自己心里有数。首先是版权和许可证问题把别人的开源代码同步到自己的服务器并对外提供要确认仓库的许可证是否允许分发和再分发。很多开源协议允许分发但要求保留版权声明和许可证文本镜像时这些信息必须原样保留。如果只是内部使用风险会小很多但也要遵守上游的服务条款。其次是资源消耗问题。同步大量大仓库尤其是频繁触发Webhook同步会对上游服务和你的服务器带宽都造成压力。建议对请求频率做限制给每个仓库设置合理的同步间隔避免成为某个上游仓库的“高频访问者”。运维上还建议把同步脚本的输出集中收集起来。至少做到两点一是有日志轮转别让日志文件无限增长二是有失败告警同步失败不能靠肉眼发现。一个简单的告警实现就是在cron任务里把stderr发到邮箱或IM机器人成本低、见效快。## 最后聊几句经验 搭镜像站这事儿技术本身真不难难的是想清楚“要同步什么、给谁用、数据多重要”这三个问题。我最初就是图省事写了个脚本把整个GitHub账号下的仓库全同步了结果磁盘直接报警后来才老老实实改成清单制、按需同步。镜像站的正确用法应该是克制的同步你真正依赖的仓库维护你确定有维护精力的数量别贪多。 还有一个体会是镜像站的稳定运行比搭建更考验耐心。真正的麻烦事往往不是Git命令本身而是证书过期、磁盘告警、token失效这种“周边小问题”。建议把所有同步任务的操作和依赖项提前写成文档哪怕只是给自己看的省得三个月后回来补脑。最后再分享一个小技巧给每个镜像仓库添加一个描述文件比如MIRROR_INFO.md记录上游地址、同步开始日期、同步策略这个习惯能在你面对一堆同名仓库时救你一命。 
长河君 · 2026/10/1 23:02:01 · 阅读 1.2k 手把手教你自建GitHub镜像站：从裸仓库到Gitea完整落地
GitHub镜像站这话题跟代码打了十年交道的人多少都动过心思。我自己也是从“clone一个仓库老半天还失败”这种抓狂状态开始的——明明仓库只有几十兆网络一波动就断断了还得重来。后来折腾了一圈发现与其到处找现成的镜像碰运气不如自己动手搭一套。这篇就把我从选型到落地的完整过程摊开讲包括踩过的坑给同样被仓库同步问题折磨的朋友一条能直接照抄的路。先说清楚你搭出来的东西能干什么、适合谁。自建GitHub镜像站本质是把你关心的代码仓库同步到自己的服务器、内网或本地形成一个独立于上游的副本。它解决三个很实际的问题一是代码备份上游仓库万一被删或暂时不可用你有完整副本兜底二是团队协作多台机器从内网镜像拉代码比每次都直连上游省心三是离线归档把仓库冻结成某个时间点的快照长期保存。适合的人包括个人开发者、小团队维护者、需要为CI/CD流程准备稳定代码源的运维同学以及那些对代码所有权比较敏感、想在本地留存一份完整历史的技术负责人。1. 为什么需要自建GitHub镜像站场景与定位1.1 镜像站在解决什么问题先帮容易混淆的朋友理清楚GitHub镜像站不是把GitHub首页抄一份而是把仓库数据包括所有分支、标签、提交历史完整同步到自己的环境里。这跟用浏览器保存网页是完全不同的事也比“只是下载某个releases压缩包”重得多——因为你要的是整个Git仓库的全部历史而不仅仅是某一个时间点的快照。在真实工作里我遇到过几种典型情况都指向同一个需求。比如团队在局域网内搞开发外网带宽有限每次新同事入职要拉一遍公司所有依赖仓库直连上游不仅慢还可能因为网络波动反复中断。再比如自己做开源项目维护上游某天把仓库设为只读甚至删掉本地若是没有完整镜像历史贡献记录就全没了。还有一个场景是做离线交付客户现场不允许连外网但又需要把整套源码包括历史记录都搬到对方服务器上这时候一个提前同步好的镜像目录就是最直接的交付物。1.2 三种镜像形态怎么选我把这半年见到的方案归成三类按“从轻到重”排开。第一种是单仓库镜像也是一切的基础形态。用Git自带的裸仓库机制把一个仓库完整clone到本地之后定期跑增量同步。做法简单、依赖少缺点是同步对象多了以后管理成本上升如果你想给团队提供一个统一入口光靠裸仓库目录还差了层应用外壳。第二种是多仓库镜像通常是基于一个服务端应用来做的。Gitea、GitLab都内置了仓库镜像功能你把上游仓库地址和凭证填进去服务端定期抓取再用自身的Web界面暴露出来。这条路的好处是天然带权限管理、支持HTTP(S)免密拉取、有UI能看到每个仓库的同步状态适合团队使用或小规模对内服务。第三种是平台级镜像说白了就是架一个缓存层来承接所有对上游的访问请求。这种方式更多偏反向代理加内容缓存跟Git仓库的数据一致性不太是一回事对代码场景来说意义不大而且实现复杂、合规风险也高我一般不建议在这个方向上花时间。自建GitHub镜像站最实用的是“第二种为主、第一种兜底”的组合。Gitea做UI和权限层底层每个仓库本质仍是裸仓库既保留了Git的高效同步机制又提供了友好的访问方式。1.3 自建前需要准备的东西一台服务器或长期开机的机器Linux优先推荐Ubuntu 20.04/22.04 LTS或Debian 11/12。配置不用太高2核2G起步就能跑动小规模镜像站真正的瓶颈通常在磁盘带宽和IOPS。足够的磁盘空间这一步我吃过亏。Git仓库的历史比你以为的大得多尤其那些带大量二进制资产比如游戏资源、模型文件的项目仓库体积能轻松上GB。建议先把你计划同步的仓库整理出来逐个查一下体积再加至少50%的余量。一个域名和一套HTTPS证书如果你只是自己本机用这一步可跳过但一旦面向团队提供服务建议用域名加Lets Encrypt证书省去一堆客户端信任问题。访问凭证同步公开仓库其实不需要账号但同步私有仓库或者为了避免触发上游限流需要准备一个GitHub Personal Access Token权限只需勾选repo相关的最小范围即可。2. 核心原理Git镜像同步是怎么工作的2.1 bare仓库与镜像克隆要理解镜像站先要把“日常使用的仓库”和“镜像用的裸仓库”分清楚。普通git clone出来的目录里包含两部分一是工作区就是你能看到、能编辑的实际文件二是.git目录里面存了全部分支、提交历史、对象数据库。而镜像站要做的不是让人类坐在那编辑代码而是完整保存历史供其他人clone因此只需要.git这一半就足够了。这就是裸仓库bare repository的由来。用git clone --mirror创建出来的仓库没有工作区只有完整的历史对象和引用refs。它跟你平时clone出来的目录里那个.git在结构上几乎一样区别就在于它作为镜像的唯一目的就是接收推送和给别人clone。从同步角度说用bare仓库当镜像底座不会出现“工作区文件跟上游不一致”的额外麻烦省掉了一整类冲突问题。选择使用--mirror而不是普通--bare关键差异在于mirror模式会把上游的所有引用原样映射过来包括分支、标签还有那些藏在refs/pull底下的pull request引用。普通bare模式只关心常规分支和标签遇到PR引用会比较尴尬。既然做镜像目标就得是“上游有什么我有什么”所以--mirror是唯一合理选择。2.2 增量同步与引用管理镜像同步的第二个核心概念是增量同步。Git仓库本身就是一套对象数据库每个提交、每个文件版本都对应一个对象对象之间用哈希互相引用。正因为有这个结构第二次同步完全不需要像第一次那样把整个仓库重新拖一遍只需要把上游新增的对象拉下来即可。实际操作中同步命令的核心是git fetch。对裸仓库执行git fetch --prune origin--prune修剪很关键它负责删除上游已经不存在的引用保证镜像里不会残留上游删掉的旧分支或旧标签。如果没有这一步镜像是会“长胖”的——上游删掉的东西你这里永远留着日积月累既是存储浪费也可能把一些敏感历史在镜像里保留得比上游还久。有一个细节值得单独提git clone --mirror初始化出来的仓库默认已经配置好了remote.origin.fetch规则为refs/*:refs/*也就是把所有引用都映射过来。但如果你自己手动创建裸仓库再手动添加remote这个特殊规则得手动补上否则fetch默认只同步特定分支达不到镜像效果。2.3 触发方式定时任务与Webhook知道了“怎么同步”接下来要考虑“什么时候同步”。两种主流的触发机制各有取舍。定时同步是最容易上手的。通过系统的cron服务按固定间隔比如每小时执行fetch脚本。优点是逻辑简单、可预期、不会因为上游某个接口抖动导致漏跑缺点是时效性差一点上游刚推送的提交可能要等到下一个周期才出现在镜像里。事件触发Webhook更聪明。GitHub支持在仓库上配置Webhook当有push、tag创建等事件时向上游发送一个HTTP POST请求。你在自己的镜像服务器上开一个小服务接收这个请求一旦收到就立即触发同步。这样能做到“上游一推送镜像秒同步”而且只在真正有变化时才消耗同步资源。实际生产环境里我推荐的做法是把两者结合日常以15分钟或1小时级别的定时任务兜底同时给重点仓库配置Webhook做即时同步。定时任务保证不会错过Webhook提升新鲜度互相补位。3. 实操从零搭建一个可用的镜像站3.1 准备服务器与基本环境这里用一个最小可用方案做示范一台Ubuntu 22.04服务器目标是把指定的公开仓库镜像到本地并通过Nginx提供HTTP(S)访问。以下是初始化时需要装的东西sudo apt update sudo apt upgrade -y sudo apt install -y git nginx cron curl装完之后我习惯建一个专门用户来运行同步脚本比如gitmirror用户。不要用root直接跑避免脚本出问题时权限边界过大。同时规划好目录结构sudo useradd -r -m -s /bin/bash gitmirror sudo mkdir -p /srv/git-mirror sudo chown gitmirror:gitmirror /srv/git-mirror sudo su - gitmirror目录规划这一步看起来只是创建文件夹其实是在为后续扩展打基础。将来你可能会同时维护几十个仓库如果目录结构从一开始就是“每仓一目录、仓库名带命名空间”后边写脚本和排查问题都会轻松很多。3.2 用bare仓库加定时脚本同步目标仓库第一个要镜像的仓库我建议挑一个小型但完整的目标——既有分支也有标签方便验证流程。比如一个Python命令行工具项目体积几十MB那种就合适不要上来就拿几十GB的大仓库练手。初始化镜像仓库的命令cd /srv/git-mirror git clone --mirror https://github.com/yourname/your-project.git第一次clone的时间取决于仓库大小和网络状况耐心等它跑完。完成后你会看到your-project.git这个目录进去执行git branch -a和git tag能对比确认上游的分支、标签都同步过来了。然后写同步脚本。我把它命名为sync-mirror.sh放在/srv/git-mirror/scripts/下#!/bin/bash GIT_DIR_BASE/srv/git-mirror for repo_dir in $GIT_DIR_BASE/*.git; do [ -d $repo_dir ] || continue repo_name$(basename $repo_dir) echo Syncing $repo_name git -C $repo_dir fetch --prune origin if [ $? -ne 0 ]; then echo ERROR: Failed to sync $repo_name at $(date) /srv/git-mirror/sync-errors.log fi done脚本逻辑非常简单遍历/srv/git-mirror下所有.git目录逐个fetch。把错误信息追加到日志文件里方便后续排查。然后给脚本加执行权限chmod x /srv/git-mirror/scripts/sync-mirror.sh sudo chown -R gitmirror:gitmirror /srv/git-mirror/scripts配置定时任务编辑gitmirror用户的crontabsudo crontab -u gitmirror -e写入*/15 * * * * /bin/bash /srv/git-mirror/scripts/sync-mirror.sh到这里第一套最朴素的镜像站已经跑起来了每15分钟自动同步一次所有历史完整保存在/srv/git-mirror下。团队里的成员可以直接从这个目录git clone或者把它添加为本地remotegit clone file:///srv/git-mirror/your-project.git3.3 用Gitea搭建带UI的镜像站裸仓库方案够用但对团队不友好没有界面、没有权限体系、别人想浏览代码得靠命令行操作。这时候Gitea就派上用场了。Gitea是一个轻量级的Git托管应用自带仓库镜像功能非常适合当镜像站的Web外壳。安装Gitea的过程用二进制方式不折腾Docker依赖更少# 下载Gitea二进制注意替换成最新版本号 wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.21.11/gitea-1.21.11-linux-amd64 chmod x /usr/local/bin/gitea # 创建运行用户和数据目录 sudo adduser --system --group --disabled-password --shell /bin/bash gitea sudo mkdir -p /var/lib/gitea/{custom,data,log} sudo chown -R gitea:gitea /var/lib/gitea sudo chmod -R 750 /var/lib/gitea然后编辑配置文件/etc/gitea/app.ini。核心几项[server] HTTP_PORT 3000 DOMAIN git.example.com ROOT_URL https://git.example.com/ [repository] MIRROR_QUEUE_LENGTH 1000启动Gitea后在管理后台创建管理员账号然后进入“站点管理 → 用户 → 编辑 → 仓库镜像”勾选允许用户创建镜像仓库。这一步不做用户那边看不到镜像功能入口。接下来用管理员或普通账号登录右上角“”号选择“新建镜像仓库”。填写上游仓库地址比如https://github.com/yourname/your-project.git。如果上游是私有仓库在“鉴权”部分填用户名和Personal Access Token。同步间隔给个建议值我个人习惯设成3小时或6小时太频繁意义不大还会占用上游API配额。Gitea的镜像功能本质上就是在底层帮你维护一个裸仓库并定时fetch只不过这一切都包在了友好的界面和权限体系里。底层目录通常在/var/lib/gitea/data/gitea-repositories/用户名/仓库名.git你也可以对它做额外的备份操作。3.4 对外访问Nginx配置与目录浏览镜像站最终要让人用得顺手HTTP访问这关得过。给Gitea配反代同时让/srv/git-mirror下的裸仓库也能通过HTTP直接clone我建议分两层处理。Nginx反代Gitea的配置片段server { listen 443 ssl; server_name git.example.com; ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }如果还想让裸仓库目录直接走HTTP clone可以在同一台Nginx上加一个server块指向/srv/git-mirror并开启目录浏览。但这么做有个前提Git智能HTTP需要依赖git-http-backend这个CGI程序纯静态文件服务是跑不了clone的。要支持HTTP clone正确的做法是再配一个location指向location ~ ^/git(/.*)?$ { fastcgi_pass unix:/var/run/fcgiwrap.socket; include fastcgi_params; fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend; fastcgi_param GIT_PROJECT_ROOT /srv/git-mirror; fastcgi_param GIT_HTTP_EXPORT_ALL ; }这一步稍微有门槛如果暂时用不上建议先专注把Gitea配好——团队通过Gitea拉代码已经完全够用了裸仓库的HTTP访问属于加分项。4. 常见问题与排查技巧4.1 同步失败与认证问题我踩得最多的一类坑就是token权限不够或token过期导致私有仓库同步静默失败。git fetch的错误有时候很模糊可能是Authentication failed也可能是could not read Username。排查时先手动执行一次fetch看真实报错再用GIT_TERMINAL_PROMPT0环境变量禁止交互式输入逼出明确的认证失败信息GIT_TERMINAL_PROMPT0 git -C /srv/git-mirror/your-project.git fetch --prune originGitHub的token需要勾选repo权限才能读私有仓库。另外注意GitHub对未认证请求有速率限制频繁同步大量仓库很容易撞限流。解决办法是在fetch命令里带上token让请求变成认证状态限额会宽裕不少。远端URL可以写成https://用户名:tokengithub.com/owner/repo.git但这样token会明文落在仓库配置里有泄露风险更稳妥的做法是用Git的credential helper来管理。4.2 磁盘与性能问题镜像站最大的隐患是磁盘被静默填满。Git仓库不会自动压缩同步一个大仓库几百次之后对象数据库里会有不少冗余对象体积膨胀明显。建议给每个仓库做定期维护git -C /srv/git-mirror/your-project.git gc --aggressive --prunenow不过注意gc --aggressive非常吃CPU和IO跑大仓库时可能持续几十分钟甚至几小时最好安排在低峰期执行。另外要监控df -h我给镜像站设置过磁盘告警阈值磁盘使用率超过80%就告警别等到满了才处理。还有一个容易被忽略的问题inode耗尽。小文件极多的仓库比如node_modules被误提交进去的会吃光inode磁盘看起来还有空间但任何创建文件的操作都失败。用df -i检查inode使用率别只盯着容量。4.3 访问层问题Nginx配好了客户端却clone不了优先检查几个方向一是证书链是否完整很多自签证书或Lets Encrypt配置不当会导致客户端直接拒绝连接二是Gitea的ROOT_URL是否跟实际访问域名一致这个不一致会导致Gitea页面里生成的clone地址是错的三是防火墙有没有放行对应端口这个最简单但最容易漏。如果用户反馈clone速度慢先看是不是镜像服务器本身带宽瓶颈再检查有没有在Nginx层开gzip压缩——文本类代码文件压缩率很高能显著节省带宽。另外注意不要让Nginx的access_log无限制增长日志塞满磁盘这种事每天都在发生。5. 进阶玩法与维护建议5.1 按需同步与批处理镜像站跑起来之后你会很快遇到“仓库到底同步哪些”的问题。一开始手工维护列表还行仓库多了就得考虑用一个源清单文件来驱动同步脚本。我现在的做法是维护一个repos.txt每行一个上游仓库地址脚本读取后逐个检查本地是否已有镜像没有就clone有就fetch。这样新增仓库只需要往文件里加一行不需要改脚本。还要学会“按需浅同步”作为补充。有些仓库历史特别长、体积巨大全量镜像成本太高但团队实际上只需要最近若干提交或某些已发布版本。Git本身支持--depth浅克隆和--shallow-since按时间深度克隆这类仓库可以单独走一个“浅镜像”策略不追求完整历史只保证常用分支和标签可用。注意不要把浅镜像和全量镜像混在一个目录里脚本要按类型分开管理。5.2 归档与灾备自己辛辛苦苦搭的镜像站如果本身丢了数据就非常讽刺。所以镜像站也要有备份策略这一点容易被人忽略。裸仓库目录本身完全可以用rsync或tar做离线备份rsync -av --delete /srv/git-mirror/ /backup/git-mirror/但是要记住不要在Git仓库正在fetch时做备份哪怕rsync能处理正在变化的文件备份出来的结果也可能是一致性存疑的状态。更稳妥的做法是先进行一次git fetch确认同步完成后短暂停止同步服务比如停掉定时任务再跑备份备份完恢复任务。备份频率可以比同步低不少每天或每周一次都行取决于你对数据丢失的容忍度。冷备之外的补充手段是把关键仓库的更新事件做成通知。我的做法是在同步脚本里加一个钩子每次fetch有新增提交时往企业微信群或邮件发一条摘要。这个小改动对团队感知镜像新鲜度很有帮助。5.3 合规与运维注意事项镜像站在技术上是中性的但使用边界要自己心里有数。首先是版权和许可证问题把别人的开源代码同步到自己的服务器并对外提供要确认仓库的许可证是否允许分发和再分发。很多开源协议允许分发但要求保留版权声明和许可证文本镜像时这些信息必须原样保留。如果只是内部使用风险会小很多但也要遵守上游的服务条款。其次是资源消耗问题。同步大量大仓库尤其是频繁触发Webhook同步会对上游服务和你的服务器带宽都造成压力。建议对请求频率做限制给每个仓库设置合理的同步间隔避免成为某个上游仓库的“高频访问者”。运维上还建议把同步脚本的输出集中收集起来。至少做到两点一是有日志轮转别让日志文件无限增长二是有失败告警同步失败不能靠肉眼发现。一个简单的告警实现就是在cron任务里把stderr发到邮箱或IM机器人成本低、见效快。## 最后聊几句经验 搭镜像站这事儿技术本身真不难难的是想清楚“要同步什么、给谁用、数据多重要”这三个问题。我最初就是图省事写了个脚本把整个GitHub账号下的仓库全同步了结果磁盘直接报警后来才老老实实改成清单制、按需同步。镜像站的正确用法应该是克制的同步你真正依赖的仓库维护你确定有维护精力的数量别贪多。 还有一个体会是镜像站的稳定运行比搭建更考验耐心。真正的麻烦事往往不是Git命令本身而是证书过期、磁盘告警、token失效这种“周边小问题”。建议把所有同步任务的操作和依赖项提前写成文档哪怕只是给自己看的省得三个月后回来补脑。最后再分享一个小技巧给每个镜像仓库添加一个描述文件比如MIRROR_INFO.md记录上游地址、同步开始日期、同步策略这个习惯能在你面对一堆同名仓库时救你一命。