企业官网建设流程全解析

前阵子帮团队搭了一套内部GitHub镜像站，起因特别朴素：CI每天要反复拉同一个上游仓库，每次构建都要在外面等数据流回来，等半小时、等一小时都是常事。后来我腾了一台服务器，把十几条高频仓库全部做成Git镜像，团队内部的拉取请求全部指向本地地址，构建的等待时间瞬间下降了一个量级。从那次之后，我再也没把一个公共仓库直接作为团队的依赖唯一来源。

这篇文章会把“GitHub镜像站搭建”这件事完整讲透：从最小可用的裸Git镜像，到带Web页面和权限管理的自托管平台镜像，再到自动化同步、体积控制、数据安全和排障记录。适合DevOps工程师、Git管理员、研发团队负责人，也适合所有喜欢自托管和折腾基础设施的人参考。

1. 先想清楚：是哪几种痛点让你想搭镜像

GitHub镜像这个话题看起来简单——“把上游仓库复制一份到自己服务器”——但真正做之前，我需要你先把目的理清楚。目的不同，镜像的形态和技术路线完全不同，后面做的事也会差很远。

1.1 场景一：CI/CD 反复拉取外部依赖，构建排队

这是最常见的情况。一个团队少则十几个、多则上百个仓库，只要一提交代码，流水线就去上游拉代码、拉依赖、拉构建产物。高峰时段，同一批仓库每分每秒都有人在拉，上游偶尔抖一下，构建就失败。

这时把仓库做成镜像的真正价值，不是“备份”，而是把高频读流量从上游转移到本地。

镜像站在内网启动之后，CI只需要访问服务器上的仓库副本，不需要关心上游的状态。因为数据已经在本地，这些操作的速度是由内网带宽决定的，构建流程自然稳定很多。我后来测算过，几十个仓库的拉取操作合并之后，每个月能省下大量等待时间。

1.2 场景二：需要让团队看到“仓库里到底有什么”

裸Git仓库只能被git clone，别人想浏览代码、看提交历史、发Issue，都没有入口。研发团队规模到了一定程度，就不能只靠命令行回答“某个功能在哪个分支改过”。

这时候，镜像要考虑的就不是简单的“复制”，而是“复制一份带浏览能力的Web仓库”。用自托管平台把上游仓库同步下来，团队打开网页就能看目录、看提交、看Tag，甚至发起合并请求。

这类需求并不是为了替代GitHub，而是给内部提供一个更可控的统一入口，尤其是当上游仓库数量很多的时候，内部平台会成为一个稳定的、所有人都知道去哪找代码的地方。

1.3 场景三：数据备份和灾难恢复

还有一种需求被很多人低估：镜像可以作为数据恢复手段。上游仓库可能遇到所有者调整、误删除、历史重建等状况，一旦原仓库路径变化或数据不可用，依赖它的构建、发布流程会立刻停摆。

如果事前有镜像，至少能保证“代码还有一份在自己的手里”。这类场景下，镜像的更新频率可以不高，但完整性要求很高，任何分支、Tag、历史都不能漏。备份需求驱动的镜像，通常还要定期做归档，而不只是实时同步。

1.4 基础概念：镜像和Fork的区别

刚接触的人很容易把镜像和Fork混在一起，但二者的定位完全不同。

Fork是从原仓库复制出一个属于你的新仓库，你有独立的开发线，可以提交、维护，后续还可以通过Pull Request把改动推回上游，讲究的是“参与开发”。

镜像则是一个只读或半只读的数据副本，目的是保证同一份Git数据在本地随时可用，通常情况下不直接承载开发。它可能不会产生任何新的提交，只是忠实同步上游的分支、Tag和历史。

还有一个区分点：Fork是平台级功能，GitHub、Gitea、GitLab都有；而镜像可以是纯Git层面的操作，不依赖任何平台。一个普通的目录，加上一条git clone --mirror命令，就已经是一个合格的Git镜像了。

2. 裸Git镜像和平台级镜像：两条路线怎么选

镜像的搭建路线，大体可以分成两层：一层是纯Git层面的镜像，另一层是带Web界面的平台级镜像。这两个不是互斥关系，但大部分团队的实际情况是“选一条先用起来”。

2.1 裸Git镜像：一条命令加一个定时任务

裸Git镜像的技术核心，是使用Git自带的裸仓库（bare repository）和镜像引用映射（mirror refspec）功能。命令长的样子是这样：

git clone --mirror https://github.com/example/project.git

这条命令会把上游仓库的所有引用（分支、Tag、远端引用等）复制到本地，并且建立一个裸仓库。所谓“裸”，就是仓库里不包含工作目录，只有.git内部的对象数据库、引用和配置。

它的特别之处在于，后续同步非常简单：在镜像目录里执行git remote update，Git会自动把所有引用更新到和上游一致，不需要人区分辨别“这个分支要不要同步、那个Tag要不要带”。因为镜像的配置本身就是把上游所有引用映射到本地所有引用。

裸Git镜像的典型形态是一个共享出来的目录，团队通过git clone git://server/project.git或者git clone ssh://git@server/srv/git-mirror/project.git访问。它没有网页，没有权限系统，没有Issue，只是解决了“一个稳定、可访问的Git数据副本”这件事。

2.2 平台级镜像：让副本变得可浏览、可管理

平台级镜像，是指我们在自托管的Gitea、GitLab等平台上，把上游仓库挂接过来做自动同步。它的实际效果是：

• 上游仓库变更后，平台按设定频率自动把分支、Tag拉到本地；
• 团队成员登录平台就能浏览代码，不需要提前克隆；
• 平台可以配置独立的访问权限，谁只读、谁能写、谁完全看不到；
• 可以在平台里挂二次操作，比如代码检查、构建状态展示。

平台级镜像的最大优势是“有人性化的界面”和“能独立配权限”。对于研发团队来说，这是最常用到的形态，因为不是每个人都愿意用命令行去git log找信息。

它的代价也很明显：需要维护一个Web平台，涉及服务部署、升级、备份、账号分配。如果团队本来就运行着Gitea或GitLab，那这个代价会小很多，只需把“镜像仓库”功能打开即可。

2.3 两条路线的对比和选型建议

我的建议很直接：如果当前的核心诉求是“CI构建稳定、拉取快”，先上裸Git镜像；如果团队里每天很多人要“看代码、找历史、提合并请求”，那就直接上平台级镜像。很多团队会在二者之间选择一个作为长期方案，并不需要同时维护两套。

3. 从零搭一个最小可用的裸Git镜像站

这一节我从零开始走一遍，给你一个能直接照抄的实操流程。技能前提不需要太高，只要会用Linux和Git基本命令就行。

3.1 前置条件：一台服务器、Git、磁盘规划

裸Git镜像对硬件要求不高，一台2核4G的虚拟机就能撑起几十个中型仓库的日常同步和拉取访问。最关键的是磁盘，因为Git仓库会保存所有历史对象，仓库数量多了之后，体积往往是预估值的好几倍。

我在服务器上规划目录时，喜欢用/srv/git-mirror作为统一根目录，每个仓库单独放一个子目录，形如：

/srv/git-mirror/ ├── project-a.git/ ├── project-b.git/ └── sync.log

确认服务器装了Git：

git --version

如果没有，用系统包管理器安装即可。接着我把磁盘容量做成独立挂载点，避免和系统分区混在一起。原因后面排障部分你会看到：Git对象占满磁盘的场面，我最怕在系统盘上遇到。

3.2 初始化第一个镜像仓库

假设我们要镜像的项目是模拟项目X，上游地址为https://github.com/example/project.git，执行：

git clone --mirror https://github.com/example/project.git /srv/git-mirror/project.git

执行完后进入目录，可以看到典型的裸仓库结构：

cd /srv/git-mirror/project.git git branch -a git tag

屏幕上应该会出现上游的全部分支和Tag。重点提醒一句：--mirror意味着这个仓库的配置里，已经写好了“把所有相关的远端引用同步到本地对应位置”的参数。你不需要再去手动添加分支映射，这大大降低了维护成本。

3.3 手动同步更新

镜像不会自己长出新数据，更新还需要执行同步操作。最简单的单仓库同步命令是：

cd /srv/git-mirror/project.git git remote update --prune

remote update会更新所有远端引用，--prune会删除本地已经不存在于上游的引用。这一步是为了防止以后上游删分支、删Tag之后，镜像里还留着一堆陈旧引用。

如果仓库非常多，我建议做成一个脚本，循环处理一批仓库，并顺手记录日志。比如在/usr/local/bin/mirror-update.sh里放：

#!/usr/bin/env bash set -euo pipefail base=/srv/git-mirror repos=(project-a project-b project-c) for repo in "${repos[@]}"; do if [ -d "$base/$repo.git" ]; then cd "$base/$repo.git" git remote update --prune echo "$(date -Is) $repo sync ok" >> "$base/sync.log" else echo "$(date -Is) $repo missing" >> "$base/sync.error.log" fi done

给脚本加执行权限，先手动跑一遍，确认每条仓库都输出sync ok，再进入自动化环节。

3.4 把镜像暴露给团队拉取

镜像服务器建好了，团队要能访问它才算完。

最简单的访问方式是使用Git自带守护进程，在工作目录下执行：

git daemon --base-path=/srv/git-mirror --export-all --enable=upload-pack --port=9418

团队就可以这样克隆：

git clone git://your-server/project.git

这种方式适合内网使用，配置简单，不需要账号密码。缺点是没有鉴权，任何能连到这台服务器的人都能克隆，所以只建议在可信网络里用。

更常见的做法是用SSH访问。假设系统账号叫git，把公钥放入git用户的authorized_keys，然后仓库地址写成：

git clone ssh://git@your-server/srv/git-mirror/project.git

这种方式有操作系统的权限保证，可控性高。如果团队已经有了统一的HTTP服务，也可以用git http-backend配合Web服务器提供HTTP克隆。三种方式没有绝对优劣，内网选最简单可靠的即可。

3.5 一条让镜像更稳的隐性工作：日志和对象完整性

裸Git镜像看似简单，但如果不做日志，出了问题很难定位。上面脚本已经在sync.log里记录了每次同步时间和结果，这只是第一步。

我建议每周或每月跑一次Git对象完整性检查：

cd /srv/git-mirror/project.git git fsck --full

git fsck会检查对象数据库是否完整、是否有悬空对象。如果输出大量错误，说明镜像数据可能已经损坏，需要重新从上游完整克隆。这类检查最好也放进定时任务，因为一旦镜像数据坏了，团队拉到的可能就是一个残缺不全的副本。

4. 想要Web界面和权限管理：自托管平台上的镜像仓库

裸Git镜像解决了拉取速度问题，但解决不了“人要看代码”的问题。当团队内部已经有了自托管代码平台时，把GitHub仓库同步进平台是水到渠成的操作。下面以最常见的自托管平台为例，讲清楚整个镜像仓库的配置思路。

4.1 为什么裸Git镜像在团队里很快会不够用

一个十人团队或许能接受“拉取全靠命令行”，但几十人的团队不行。总会有人需要快速查看某个文件、确认某个分支最后改过什么、对比两个代码片段。

裸Git镜像不具备任何展示能力。你当然可以把镜像克隆到本地再用IDE看，但这样每人都要做一次本地克隆，连接数一多，镜像服务器反而变成瓶颈。平台级镜像的好处，是把“浏览”和“拉取”分开：浏览走Web，拉取走Git，两者互不影响。

4.2 先建一个专用同步账号

在平台上配置镜像，不建议直接使用某个人的管理员账号去连接GitHub。原因是个人账号具有过高权限，并且在人员变动时，镜像同步可能会因为账号被禁用而中断。正确做法是为同步任务单独建一个“机器人账号”，比如叫mirror-robot，单独给它分配需要的权限。

准备好账号之后，还要在GitHub准备访问令牌。要注意的是，给镜像用的令牌，原则上只需要基础读仓库的权限，不需要仓库管理权限。最小化授权，是镜像配置里最值得守住的一条底线。

如果上游仓库是私有的，还需要在机器人账号上配置对应的访问权限。一个常见做法是在GitHub团队里创建一个只读成员角色，只把需要同步的仓库加入该团队，而不是把机器人拉进所有库。

4.3 在平台上添加Pull Mirror：让上游往本地同步

Pull Mirror的典型含义，是“由本地平台定期从上游拉取更新”。不同的平台按钮位置略有不同，但大体的配置项是一致的：

• 上游仓库地址：填写GitHub仓库的完整URL；
• 访问凭据：填写机器人Token；
• 同步方向：Pull；
• 同步分支、Tag：平台默认会全同步；
• 同步频率：一般支持每小时、每天、每周。

配置完成后，平台会立刻执行一次首次同步。同步完成之后，平台内会出现和上游仓库同名的仓库，团队可以正常浏览和克隆。之后只要同步任务不被关闭，上游的新分支、新Tag就会按计划更新到本地。

Pull Mirror适合的场景，是把GitHub作为“数据源”，由自托管平台形成一份面向团队的统一展示库。你在本地不创建独立开发线，所有代码变更仍然回推到GitHub，镜像只负责分销。

4.4 Push Mirror的使用场景

很多人不知道，自托管平台的镜像还支持另一个反方向：把本地仓库推送到上游。

Push Mirror的典型业务场景是发布管线。团队在内部平台维护的是一个“发布仓库”，所有版本提交先进入这里，经过检查和审批后，由平台统一推送到GitHub公开仓库。这样既能满足外部协作需要，又能保证内部管控流程不被绕过。

配置Push Mirror的时候，平台会要求填写上游地址和使用具备写权限的令牌。这里要特别小心：写权限令牌的安全级别要按照生产密钥对待，不要出现在日志、Web前端或任何人可见的文档里。

4.5 平台级镜像搭建完后要做的三件事

第一件事，立刻把镜像仓库的可见范围设置好。默认可能是公开的，对内对外都一样。除非你想作为开放镜像站，否则应该设置成内部可见。

第二件事，在平台的Webhook或系统通知里挂上镜像同步失败的告警。平台镜像同步偶尔会失败，比如令牌过期、上游仓库临时不可达、磁盘空间不足。静默失败比失败更可怕，因为所有人还在克隆旧数据，却没人知道数据已经停止更新。

第三件事，做一次验证性克隆。用普通账号从平台的仓库地址克隆一遍，确认访问路径、认证方式都正确。这一步虽然简单，但往往能发现域名解析、证书、SSH端口等一堆环境问题。

5. 同步自动化：从cron到并发锁和失败告警

手动同步只能撑过搭建初期。镜像真正的价值，是建立一套无人值守的同步机制。这一节把自动化的几个关键环节拆开讲清楚。

5.1 用cron定时同步

最简单的定时同步就是cron。把前面写的多仓库更新脚本放到/usr/local/bin/mirror-update.sh，然后配置系统crontab：

0 * * * * /usr/local/bin/mirror-update.sh

这个例子表示每小时整点跑一次。对于绝大多数仓库来说，这个频率已经完全够用。实际工程里我还会加一行随机延时的技巧，避免多个镜像站在同一秒同时去访问上游：

5 * * * * sleep $((RANDOM % 300)); /usr/local/bin/mirror-update.sh

cron虽然简单，但要注意它的运行环境是非交互Shell，很多靠用户环境变量才能用的命令可能找不到路径。脚本里强烈建议用绝对路径，或者至少把PATH显式设置好。

5.2 用flock防止脚本互相撞车

仓库多了之后，同步耗时可能超过一小时。如果上一轮还没跑完，下一轮又启动了，两个进程同时操作同一个Git仓库，轻则产生锁冲突，重则导致引用状态异常。

解决办法是加一个并发锁。Linux自带flock，用法很简单：

flock -n /var/run/mirror-update.lock /usr/local/bin/mirror-update.sh

-n参数的意思是拿不到锁就直接放弃，不等待。结合cron使用，就能保证任何时刻只有一个同步脚本在运行。如果上一次还没结束，新一次的进程会直接退出，并留下一个可追踪的状态。

Git本身也有仓库级锁（.git/index.lock等），但那是文件级别的并发保护，不等同于任务管理器。真正的任务级锁还要靠你自己的编排。

5.3 webhook不是必选项

平台支持webhook时，你可能想上游每次更新就触发同步。理想状态是“零延迟同步”，但现实是webhook依赖于平台接收通知的能力，如果发送方和接收方之间的网络不可达，事件就会悄然丢失。

所以我的做法是：即便配置了webhook，也仍然保留cron兜底。把cron当成一个稳定、可预期的同步心跳，把webhook当作锦上添花的加速器。

5.4 失败通知别省

脚本脚本，没有通知就等于白跑。我在上线镜像脚本之后，做的第一件事是给sync.error.log接入监控告警：一旦出现错误条目，触发通知到内部通信群。

有几种常见的失败方式要格外警惕：

• 上游仓库被移动或删除：Token还有效，但URL失效；
• Token过期：平台侧权限发生变更；
• 磁盘满：同步时对象写入失败；
• 非快进更新：上游Force Push覆盖了历史。

如果这些错误不能第一时间知道，镜像就会像一个“断更的订阅”，所有人用着旧数据而不自知。

5.5 给镜像加上定期自检

除了同步失败，还要关注“同步成功但其实坏了”的场景。Git仓库对象数据可能因为磁盘坏道、异常断电等因素损坏，git fsck是发现问题的第一道防线。

我习惯把完整性检查和同步脚本分开，做成每周一次的低频任务：

#!/usr/bin/env bash base=/srv/git-mirror for repo in "$base"/*.git; do cd "$repo" git fsck --full || echo "$(date -Is) $repo fsck failed" >> "$base/fsck.error.log" done

脚本跑完，只要fsck.error.log为空，就可以放心继续使用。

6. 仓库体积失控：大历史、LFS和对象清理

GitHub镜像最常踩的暗坑，不是同步失败，而是磁盘凭空少了几百GB。我见过不少次，原因几乎都是同一个：仓库历史里躺着几个被后来删除的超大文件。这一节讲清楚体积问题的定位和应对。

6.1 怎么找到哪条仓库在吃磁盘

不要靠直觉猜，直接看数据。进入裸仓库目录，执行：

git count-objects -vH

这个命令会输出对象总数、对象实际大小、浪费空间等信息。如果再配合du整体看目录大小，就能快速判断某个镜像仓库是不是异常。

想找出具体是哪个对象比较大，可以用：

git verify-pack -v .git/objects/pack/*.idx | sort -k 3 -n -r | head -20

这里输出的第三列是对象大小，你会很直观地看到哪些提交或Blob对象占用了绝大部分空间。很多人这时候才意识到，仓库真正吃掉的空间往往藏在历史深处，而不是当前工作区。

6.2 浅镜像：省空间但有代价

如果你只是为了让CI拉取最新的代码做构建，不关心太长历史，可以考虑浅镜像：

git clone --mirror --depth=100 https://github.com/example/project.git

--depth=100表示只保留最近100条提交历史，对象体积会大幅下降。这个优化的副作用是，团队会把镜像当成唯一数据源时，访问不到更早的历史。

我的建议是：先确认镜像的数据消费者到底需要什么。如果确定只需要“最近版本可用”，浅镜像值得用；如果存在“需要回溯几个月前某个提交”的需求，那就别省这块磁盘空间。

6.3 Git LFS对象不会自动跟着镜像走

Git LFS（大文件存储）解决的是“把大文件放进Git仓库”的问题，但它的机制和普通对象不同：普通Git对象直接被仓库记录，LFS对象则被一个引用指向外部存储。

默认的git clone --mirror只同步了LFS指针文件，并没有把实际的大文件内容下载到本地。这就意味着，即使镜像仓库同步成功，团队成员克隆后可能拉不到真正的LFS大文件。

解决办法是，在镜像服务器上额外执行LFS拉取：

git lfs fetch --all git lfs push --all origin

fetch --all会把上游的所有LFS对象拉到本地缓存，push --all再把这些对象推送到远端。做镜像前，一定要先确认上游仓库是否使用了LFS，否则你的“完整镜像”其实只是半个副本。

6.4 清理丢失对象和孤儿对象

Git仓库每天都在产生临时对象，比如rebase、force push留下的旧对象。这些对象在当前引用图里不可达，但不会自动消失。日积月累，镜像体积会慢慢膨胀。

可以手动执行垃圾回收：

git gc --auto

在非临时需要的时候，不建议直接上--aggressive。这个参数会重新压缩所有对象，极其消耗CPU和IO，对于只读镜像来说收益很小，反而可能触发服务中断。

更合理的做法是，定期执行git gc --auto，让Git自己判断有没有必要做，而不是逼迫它“大扫除”。如果上游Force Push非常频繁，清理频率要相应提高。

6.5 提前给磁盘留够空间

对镜像服务器最有效的保护，是预算时把仓库体积估计为“当前上游仓库体积的2~3倍”。Git临时对象、LFS缓存、同步日志、备份文件都会占用额外空间。

我通常的做法是：把镜像目录挂在一个独立分区上，留出至少一倍余量，再设置磁盘告警阈值。一旦使用率达到80%，系统就开始通知。等90%再处理，往往已经晚了。

7. 权限和敏感数据：镜像上线前先想清楚安全和边界

很多团队把镜像上线当作“技術任务”来完成，忽略了数据边界。镜像的本质是把一份数据复制到另一处，而任何复制都会放大数据的暴露面。

7.1 最容易踩的坑：敏感文件被当成代码历史带入镜像

有一部分数据，用“敏感度”来形容一点不为过：.env配置、证书私钥、数据库备份文件、内部运维脚本里的连接串。这些内容如果曾经出现在上游仓库的历史里，那么哪怕后来被删除了，镜像同步后依然会带走这颗“历史炸弹”。

更隐蔽的是，这类敏感信息往往不在最新分支，而藏在某个旧Tag、旧提交里。

解决思路有两个方向：

• 从源头过滤：只同步需要的分支和Tag，而不是全量。
• 在镜像侧清洗历史：用git filter-repo这类工具重写历史，删除敏感文件。这会对镜像造成不可逆影响，事后所有引用哈希都会变化，所以一定要在镜像初始化之前决定是否要做。

7.2 服务账号最小授权

前面提过的“机器人账号”原则，在GitHub和自托管平台两侧都要坚持。

在GitHub侧，给镜像同步用的Token只申请仓库读取权限，不要给写权限。只有Push Mirror场景需要写权限，能不用就不用。

在自托管平台侧，mirror-robot账号应该只是同步执行者，不是全站管理员。它不需要创建用户、不需要修改系统配置。最小授权的好处是，即使Token泄露，攻击者能做的破坏范围也有限。

7.3 分支保护和可恢复机制

镜像仓库虽然不承载开发，但你仍然会遇见有人误删镜像仓库、平台数据损坏这类意外。我的经验是，把镜像当成重要的生产数据来保护。

最基本的一步，是用Git自身的打包能力定期归档：

git bundle create project.bundle --all

执行后会生成一个单一的project.bundle文件，把它拷贝到另一台机器或对象存储里，就能在灾难场景下恢复整个镜像仓库。这个文件是所有Git对象和引用的快照，相当于仓库的“完整集装箱”。

7.4 访问边界要明确

镜像一旦对外开放，你会遇到一个尴尬问题：它到底是给谁用的？

如果只是内网使用，应当在防火墙层面只允许内部网段访问；如果是作为开放镜像站，访问则不受限制。不同的边界，决定了你在系统上要不要单独划分VLAN、要不要单独开防火墙规则、要不要配置负载均衡。

把边界想清楚再开服务，比事后打补丁容易得多。

8. 镜像站排障手记：我踩过的几个坑

最后这一节，分享几个我真实经历过的故障场景。每个问题我都绕了不少时间，希望你看完能少走弯路。

8.1 非快进更新导致同步中断

使用裸Git镜像时，如果上游有人做了Force Push，本地的引用会拒绝被快进。表现就是git remote update报出类似“refusing to update”的错误。

解决方式分两种。如果你是纯只读镜像，通常不需要太担心，因为上游Force Push后，本地只需要重新获取最新引用即可：

git fetch --prune --force

如果是平台级Pull Mirror，平台一般会自动处理这种非快进情况。但实际运维中，我发现它有时会停在“同步失败”状态，需要人去平台里点一次“重试同步”。遇到这个场景，不要慌，先确认上游确实有Force Push，再重新触发同步。

8.2 cron环境里找不到SSH Key

我自己踩过的第二个坑，是脚本在命令行手动执行正常，一放进cron就同步失败。查到最后发现，原因是cron环境不加载当前用户的.bashrc和.ssh/environment，SSH客户端找不到对应私钥。

后来我把所有仓库的拉取地址统一改成HTTPS，并在脚本里显式指定凭据文件，彻底绕开了SSH key的路径问题。具体做法是为服务账号写一个独立的Git凭据文件：

git config --global credential.helper 'store --file=/etc/git-mirror-credentials'

这个文件权限要设成600，只让镜像服务账号能读。问题是解决了，教训也记住了：任何自动化脚本都要假设自己运行在一个“干净”的环境里，不能指望用户级配置被自动加载。

8.3 LFS对象缺失，Clone成功但拉不到大文件

有一次某个仓库同步看起来完全正常，分支、Tag都在，但同事一克隆就反馈“某个LFS文件下载失败”。

排查后发现，这个仓库启用了Git LFS，而我的同步脚本只执行了普通的git remote update，没有执行git lfs fetch --all。LFS指针文件同步过来了，实际大文件却没有。

修复方式很简单，在镜像更新脚本里加上LFS拉取步骤，并让LFS缓存目录有足够磁盘空间。从此之后，凡是上游启用LFS的仓库，我都会在初始化时明确标注并单独处理。

8.4 同步日志把磁盘空间吃满

一个不起眼的问题，最终差点让整个镜像服务器停机：sync.log写得太多，日志文件膨胀到几十GB，直接占满了系统分区。

从那次以后，我给脚本加了两道保险。第一，日志输出限制条数，用系统日志管理工具做轮转；第二，日志目录不放在系统分区，而是放到专门的数据盘。这个改动很小，但避免了一次完全可预见的故障。

8.5 恢复误删镜像的两种路径

如果是平台级镜像被误删，通常不用太紧张，只要上游还在，重新配置一条镜像任务即可恢复，代价也就是重新同步一次。

如果是裸Git镜像被误删，恢复路径则取决于你前面是否做了归档。有project.bundle归档的话，执行：

git clone --mirror project.bundle project.git

就能恢复整个仓库。如果没有归档，只能回到上游重新拉取，丢失的只是本地未同步的时间窗口。这也是为什么我始终强调，镜像服务器要定期做bundle归档，备份文件一定要放在另一台机器上。

最后再分享一点我个人习惯：镜像站这个事，成败不在“第一次同步成功”，而在于自动化、告警、备份、清理这套兜底机制是否齐活。我会先在裸Git镜像上把整套脚本跑顺，再考虑平台级镜像；等平台级镜像上线，又回头把裸镜像停掉或降级为冷备。这样一步步来，踩到的坑最少，后续维护也最省心。