上周开发同事又在群里喊公共基础库的 clone 又超时了快看看 GitHub 镜像站。这台镜像站是运维部自己搭的8 核 16G 内存跑着一台 Gitea同步了三百多个常用开源仓库。半年多折腾下来坑踩了不少也沉淀出一套可以直接复用的方法。这篇文章把完整的搭建思路、关键配置、操作代码和踩坑记录整理出来给三类人看内网开发环境出口带宽有限、又想快速拉取开源代码的团队需要做关键仓库离线备份的运维以及纯粹对 GitHub 镜像站原理感兴趣的开发者。先说一个容易被误解的点很多人以为镜像站等于“反代一个 github.com 页面”实际上真正稳定、可控、能长期维护的镜像站是“仓库同步型镜像”。下面我会把整个思考过程、选型逻辑和落地步骤讲清楚。1. 自建 GitHub 镜像站到底是在解决什么问题1.1 先说清楚“镜像站”三个字的三种含义“GitHub 镜像站”这个词在不同人嘴里代表完全不同的东西动手之前一定要先对齐。第一种是仓库同步型镜像。把 GitHub 上的开源仓库定时搬到自己服务器上提供git clone、Web 浏览、压缩包下载。这种方案最常用也是本文重点讲的。第二种是文档型镜像。比如某个项目的官网、API 文档、教程站用静态站点爬虫搬回来再挂到内网或公网。这种一般针对固定站点不用天天同步适合文档类资产比较多、版本变化又不快的团队。第三种是反向代理型。把所有访问 GitHub 的请求转发到自己的服务器再由服务器去GitHub 拉取页面、文件、release 包。乍一看最省事实际上性能、登录态、证书、合规风险都很麻烦。我先给出结论团队自建镜像站不建议选这条路下文第 2 章会展开说明原因。1.2 两种典型场景内网拉代码与构建依赖我们搭镜像站的直接原因是开发环境的网络出口不稳定。同一个仓库有人 clone 要等十分钟有人中途断线反复重试。后来发现问题的根源不是带宽不够而是很多公共依赖仓库分布在不同的 CDN 链路每次拉取都要重新建立连接网络抖动一大就失败。镜像站解决的是“重复拉取”的问题。第一次从上游全量同步到内网这部分的网络开销不可省但之后所有开发机和 CI 都从内网镜像拉速度就非常理想了。举个例子一个 1GB 左右的中型仓库直接上游拉可能断断续续要 20 分钟内网镜像差不多 1 分钟以内。第二种场景是 CI 构建。我们内部流水线里有很多依赖是源代码形式比如编译 OpenCV、PaddleOCR、一些 CUDA 工具链的源码包。每个 MR 触发构建时都要去拉同一批仓库。如果你不搞镜像同一套代码一天要在公网上传播几十次时间和流量都浪费。有了镜像构建节点统一走内网整个流水线的稳定性提升一个量级。第三类是离线备份需求。GitHub 是第三方平台任何公开仓库理论上都有可能被删除、被存档、被移交。对有持续依赖的关键项目定期镜像到自己的服务器其实是给自己买保险。这个场景经常被忽略但很值得做。1.3 开工前想清楚边界避免镜像站失控镜像站不是把 GitHub 整个搬回家它是有边界的只镜像开源许可协议允许再分发的仓库。私有仓库不要同步到任何公网可见的镜像站。镜像站要在页面上明确标注“本仓库镜像自 GitHub版权归原作者”。内网镜像站要关闭公开注册默认只允许公司内部账号访问。这些边界不是理论问题。我见过有团队把镜像站做成公网开放服务结果被爬虫抓、被恶意刷流量、被上游仓库作者发邮件要求撤下。到那个时候再补救就晚了所以一开始就要把访问控制做对。2. 方案选型为什么我坚持“同步型镜像”而不是反代一层2.1 同步型镜像把上游仓库搬回家同步型镜像的架构其实很朴素上游 GitHub 仓库通过定时同步脚本或者 Gitea 自带镜像功能把 git 仓库对象、分支、标签搬到本地 Gitea 上内网开发人员直接 clone 本地地址。这样做的好处非常明显上游网络抖动不影响内网 clone。全量历史保留在本地可以做审计和离线备份。Gitea 自带 Web 界面可以浏览代码、查看 Release、搜索仓库体验和 GitHub 接近。只读镜像仓库可以严格控制写入权限避免误操作。而且 Gitea 本身就是开源软件部署成本低对一个几百仓库的镜像站来说8 核 16G 内存完全够用。2.2 反向代理为什么看起来简单却容易踩进深坑“我是不是用 Nginx 反代一下 github.com 就行”这是每次讨论镜像站都会出现的问题。我确实试过。表面上看一个 server 块就能搞定实际跑起来会发现一连串问题GitHub 大量跳转会跨多个域名。比如你访问https://github.com/owner/repo/raw/main/file.txt实际文件下载会 302 跳到raw.githubusercontent.com你的反代必须同时接管一串域名一环没配好就白屏。登录态和 Cookie 会被搞乱。GitHub 的登录认证依赖多个 Cookie 和跨域请求反代之后经常出现“明明登录了刷新一下又让我重新登录”的诡异现象。证书处理很麻烦。你没法直接用 GitHub 的证书只能自己签证书替客户端“解密再加密”这意味着所有客户端都得信任你的 CA。在浏览器里还能接受在 git 命令行、CI 节点、容器镜像里信任自签证书是一个巨大的运维负担。大文件下载会打满单机带宽。镜像服务器成了所有大文件的必经之路几十个人同时下载 Release 包时网络直接卡死。管理边界不可控。反代本质上是在为所有人的所有请求做转发这种能力很容易失控出了问题也很难说清楚。所以我的结论很明确反向代理适合临时应急不适合长期自建服务。一旦要长期、稳定地服务整个团队的代码拉取需求仓库同步型镜像才是正路。2.3 软件栈选型Gitea、Gogs 还是 GitLab同步型镜像站需要一个代码托管平台来承载仓库。我对比过三个方案逐个说下感受Gitea轻量、部署简单、镜像迁移功能内置支持从 GitHub 一键导入仓库并保持同步。社区非常活跃适合大多数团队。Gogs比 Gitea 更轻界面更朴素但部分镜像、迁移和插件能力不如 Gitea 完整团队二次开发少的话不太推荐。GitLab功能最全自带 CI/CD、容器仓库、审计日志但资源占用高。跑一台 2C4G 的机器装 GitLab启动后内存消耗接近 2GB纯做镜像太浪费。最终选 Gitea。部署方便仓库迁移顺手权限模型和内网域名配置也简单能让我们把精力花在同步策略和运维上而不是天天伺候服务本身。3. 从零搭建Gitea 安装、仓库导入与 HTTPS 接入3.1 Docker Compose 拉起 Gitea我用 Docker Compose 部署管理方便升级也快。目录结构很简单一个docker-compose.yml一个挂载数据目录一个备份目录。下面是实际使用的 Compose 文件做了一些精简services: gitea: image: gitea/gitea:latest container_name: gitea ports: - 22:22 - 3000:3000 environment: - USER_UID1000 - USER_GID1000 - GITEA__server__DOMAINgit.example.com - GITEA__server__ROOT_URLhttps://git.example.com - GITEA__server__SSH_DOMAINgit.example.com - GITEA__service__DISABLE_REGISTRATIONtrue volumes: - ./gitea:/data - ./backup:/backup restart: unless-stopped几点说明22是 SSH clone 用的端口3000是 Web 页面端口。GITEA__server__ROOT_URL要设置成最终对外访问的域名Gitea 生成的 clone 地址全靠它。环境变量里直接关闭公开注册避免陌生人注册进来。内部员工的账号由管理员手工创建或者对接公司 SSO。部署命令就一条docker compose up -d然后访问http://服务器IP:3000会进入首次安装页面。数据库我直接选 SQLite几百个仓库的规模足够了不需要额外跑一个 MySQL。设好管理员账号完成安装。3.2 从 GitHub 迁移仓库为镜像仓库Gitea 的镜像同步功能是现成的入口位置在不同版本叫法略有差异有的写“迁移仓库”有的写“导入仓库”。在右上角“”菜单里选择“新建仓库 - 迁移仓库”或者直接在仓库列表页找“导入仓库”。关键配置有这么几项迁移源选择 GitHub。Clone Address 填 GitHub 仓库地址。管理员账号里填入 GitHub Personal Access Token。这个 Token 不需要仓库权限给public_repo权限即可。勾选“此仓库为镜像”这样 Gitea 会按设定的时间间隔自动拉取上游更新。设定镜像同步间隔我给核心仓库设的是 6 小时普通仓库 24 小时。有人会问Token 到底有什么用。一个直接原因是 GitHub API 有速率限制。匿名请求一把 IP 一小时内只能打 60 次而带 Token 之后是 5000 次。如果你要同步几十上百个仓库没有 Token 很快就触发 403任务会大面积失败。Gitea 迁移仓库时可以勾选一些附加数据比如 Issues、PR、Release、Wiki 等。注意一个事实Gitea 的镜像同步不是把 GitHub 整个网站搬过来它同步的是代码仓库本体外加你勾选的可见数据。如果只是为了拉代码只勾 Release 就够了。如果还想在内部搜 Issues、看历史讨论才需要把 Issues 和 PR 也勾上。3.3 给镜像站配内网域名与 HTTPS镜像站跑起来之后不能让同事记一串 IP 加端口去访问。内网 DNS 加一条git.example.com解析记录然后用 Caddy 做反代和证书管理。我选 Caddy 而不是 Nginx因为 Caddy 最常用的场景就是“自动申请证书 反代”配置只有三行git.example.com { reverse_proxy 127.0.0.1:3000 }如果是内网域名Caddy 没法自动申请公网证书需要两种情况处理公司有内部 CA把内部 CA 证书装到所有开发机上然后让 Caddy 使用内部 CA。没有内部 CA就用自签证书把自签证书分发给所有客户端或者干脆先走http://等内部证书体系建好再切 HTTPS。我的建议是不要长期用 HTTP。git clone 时会用 HTTP 明文传输凭据虽然 Gitea 默认有防护但内网里也不应该裸奔。自签证书虽然麻烦但在客户端信任一次之后体验就很顺了。3.4 验证 clone 链路配置完的验证命令很简单git clone http://git.example.com/owner/repo.git cd repo git remote -v如果 URL 输出的是你自己的域名说明ROOT_URL生效了。再试一次 SSH clonegit clone gitgit.example.com:owner/repo.git如果 SSH clone 失败先检查服务器的22端口是否被占用再检查客户端公钥是否已经加到 Gitea 账号里。SSH clone 首次配置稍微麻烦但后面用起来比 HTTP 顺手。到这里一个能正常 clone 的镜像站就算上线了。4. 同步策略进阶轻量探针、并发限流与 LFS 处理4.1 别再写“每 10 分钟全量 clone”的脚本了镜像站搭好之后最大的问题不是“怎么同步”而是“怎么同步得聪明”。最容易踩的坑是写一个定时任务对每个仓库执行一次git clone --mirror每 10 分钟跑一遍。这种方案在仓库少的时候没问题仓库多了之后会非常浪费带宽和磁盘 IO。全量 clone 会把仓库所有对象重新拉一遍即使上游只增加了一个 commit。正确做法是分两步用git ls-remote做轻量探针只查询远程仓库的分支和 HEAD 指针流量很小。发现上游有变化后再用git remote update --prune做增量拉取。下面是我常用的同步脚本模板化之后可以套到任意仓库上#!/usr/bin/env bash set -euo pipefail UPSTREAMhttps://github.com/owner/repo.git LOCAL/data/gitea-repositories/owner/repo.git # 首次同步直接全量拉取 if [ ! -d $LOCAL/objects ]; then git clone --mirror $UPSTREAM $LOCAL exit 0 fi # 已有本地仓库先比较远端 HEAD 与本地 HEAD REMOTE_HEAD$(git ls-remote $UPSTREAM HEAD | awk {print $1}) LOCAL_HEAD$(git -C $LOCAL rev-parse HEAD) if [ $REMOTE_HEAD ! $LOCAL_HEAD ]; then git -C $LOCAL remote update --prune git -C $LOCAL update-server-info fi为什么用ls-remote而不直接rc因为ls-remote只发一个很轻的查询请求返回值就一两行几十字节的数据量。十个仓库探测一次都不到一秒钟对上游和本地都没有压力。要注意rev-parse HEAD只比较了默认分支的 HEAD 指针。如果仓库多个活跃分支频繁更新你可以把HEAD换成refs/heads/main refs/heads/master refs/heads/dev等关键分支多点比较及时发现变化。4.2 多仓库并发与 GitHub API 限流仓库一多串行同步会慢到你怀疑人生。三百个仓库平均每个同步一分钟一轮下来五个小时太不现实。并发是必要的。我用xargs做简单的并发控制cat repo-list.txt | xargs -P 8 -I {} ./mirror-update.sh {}-P 8表示同时跑 8 个同步任务。为什么要限制在 8而不是满量跑因为同一时间打太多请求很容易触发 GitHub API 的限流现象是同步脚本突然全部返回 403错误信息里写rate limit exceeded。GitHub API 的限制是这样的匿名请求每个 IP 每小时 60 次。带 Token每个 Token 每小时 5000 次。所以同步脚本里一定要带上 GitHub Token否则仓库数量超过 60 个就一定出问题。我之前踩过这个坑后面第 6 章会详细讲教训。还有一个经验脚本里要有失败重试和退避逻辑。网络抖动、上游仓库暂时不可用、GitHub 限流都会导致单次同步失败。不要失败一次就放弃重试三次、间隔递增 30 秒能救回大部分偶发故障。另外我维护了一个“最近同步时间记录表”记录每个仓库上次同步的时间戳。如果某个仓库 10 分钟内已经同步过就跳过避免重复同步高频仓库。这个表是一个简单的文本文件或 SQLite 表都行看你们习惯。4.3 LFS 对象与大仓库的特殊处理Git LFS 是最容易忽略的坑。很多开源仓库用 LFS 存大文件但 LFS 对象和普通 git 对象在存储上完全分离。git clone --mirror只能拿到 LFS 的指针文件真正的二进制大对象不会跟着过来。如果你镜像之后团队 clone 下来发现大文件全都打不开大概率就是只做了普通镜像没有同步 LFS 对象。处理 LFS 的思路分两种第一种仓库比较小、LFS 对象不多直接在 Gitea 迁移时勾选“迁移 LFS 数据”让 Gitea 帮你拉取 LFS 对象。这个操作在迁移向导里能看到。第二种仓库量级已经很大需要在脚本里手动处理。可以在镜像目录里执行cd /data/gitea-repositories/owner/repo.git git lfs fetch --all git lfs push --all origin把 LFS 对象先拉全再推到镜像仓库的 LFS 存储里。这样 clone 镜像地址时就能正常恢复大文件。大仓库的磁盘增长非常快。以我们镜像里的几个模型仓库为例代码部分只有 200MBLFS 对象加起来超过 8GB。同步之前一定要评估磁盘空间别等第一轮全量同步时才发现把数据盘塞满了。5. 实测数据项目背景与盲区验证5.1 克隆耗时前后对比下面这组数据来自我们内网环境不同网络环境下差异会很大但能说明趋势性结论。仓库规模直接上游 clone内网镜像 clone50MB 以下2~5 分钟不稳定5~15 秒500MB 左右10~20 分钟经常断线30~60 秒1GB 以上很难一次性拉完1~2 分钟特别明显的是 1GB 以上的大仓库。直接上游 clone 经常中途因为网络波动断开git报错后重新开始体验非常痛苦。镜像站只受内网带宽和磁盘 IO 限制拉取速度稳定且可预期。5.2 磁盘占用与 Git GC 策略镜像站的磁盘消耗主要来自两块git 对象和 LFS 对象。我们同步了三百多个仓库之后.git对象目录接近 180GBLFS 对象接近 60GB整体 240GB 左右。对于当前数据盘 2TB 来说足够用但迭代一段时间会发现仓库版本越多对象库增速越快。这里有一个不太直观的优化点Git 仓库长期同步后会产生大量松散的 object 文件。磁盘占用量其实不是最大的问题最直接的影响是git clone和git fetch时Git 需要扫描大量对象文件IO 占用明显偏高。Gitea 本身会在后台跑仓库维护任务但如果我们用外部脚本同步裸仓库就需要自己注意 GC。我建议在同步脚本里加上定期 GC 的逻辑比如每个月对仓库跑一次git -C $LOCAL gc --auto不要去手动跑git gc --aggressive这个命令为了让对象库压缩到极致会重新计算所有 delta 链非常耗时。正常使用--auto就够了。5.3 多人同时拉代码的服务器压力观察镜像站上线后第二个容易被忽略的问题是并发拉取。开发高峰期几十个人同时 clone、pull、fetch服务端的压力会快速上升。我在压测时发现50MB 以下的小仓库并发 30 个都没问题Gitea 进程 CPU 占用不到 40%。但 1GB 的大仓库同时被 5 个人 clone网络层会被打满磁盘 IO 也会飙高其他仓库的请求响应时间明显变长。解决思路限制 HTTP 层并发连接数。用 Caddy 或 Nginx 做一层limit_conn比如同一个 IP 最多 4 个并发连接。对大仓库建议同事优先用git clone --depth1做浅克隆除非明确需要完整历史。减少不必要的全量git fetch。CI 里拿代码尽量用浅克隆而不是每次都git fetch --prune拉全部分支。6. 我从踩坑中总结的五个运维教训6.1 手动 clone --mirror 的仓库差点被 Gitea Doctor 清掉第一次批量接入仓库时我图省事在一台机器上用脚本git clone --mirror拉了一大批仓库然后直接放到 Gitea 的数据目录里。结果 Gitea 后台启动一致性检查Doctor时对不少仓库报了文件缺失和格式异常个别仓库还被标记为损坏。排查之后才明白Gitea 的仓库目录结构不只是“把裸仓库放进去”这么简单它还有自己的元数据文件、权限配置、钩子脚本。手动塞进去的裸仓库缺少这些内容Gitea 会误判成异常仓库。教训不要手动往 Gitea 目录塞仓库。要用 Gitea 自带的“迁移仓库”功能让它自己创建仓库目录、自己管理元数据。脚本同步只适合在 Gitea 环境下做增量更新不适合做首次数导入。6.2 同步脚本没带 Token第 54 个仓库开始全失败这是我最早踩的一次坑。当时同步一个仓库列表前面 53 个都很顺利到第 54 个的时候脚本开始报错返回信息里有rate limit exceeded。我一开始以为是网络问题反复重试也没用后来查了 GitHub API 文档才明白是匿名请求限流。GitHub 对同一 IP 的匿名 API 请求限制是每小时 60 次。我同步每个仓库前都会调一次接口查仓库元数据很快就打到了限额。解决方式很直接在同步脚本里带上 GitHub Token并在环境变量里设置GH_TOKEN让所有 API 请求都带上身份。带 Token 之后限额变成每小时 5000 次三百多个仓库同步下来非常宽裕。这件事给我的经验是任何批量任务第一版就要把 API 限额问题考虑进去。不要等到生产环境跑了大半才停下来补 Token。6.3 自签证书过期后镜像站进入“假死”状态内网域名一直用自签证书证书有效期我设了一年。到期那天正好是周末没人注意到结果周一的时候所有同事的 clone 命令都开始报TLS certificate verify failed。更麻烦的是有的同事改用了GIT_SSL_NO_VERIFYtrue临时绕过验证虽然能拉代码但把问题掩盖了。后来排查的时候发现有些安全软件检测到客户端跳过了 HTTPS 校验直接拦截了 git 进程。教训是两件事自签证书要设一个较长的有效期比如五年同时在自己的日历里标记到期时间。不要把GIT_SSL_NO_VERIFYtrue当成常规操作这个变量只是临时工长期开着的系统等于在裸奔。最好的做法还是搭一套内部 CA把根证书下发到所有开发机。虽然初期配置麻烦一点但后续证书签发和轮换都是自动化流程不会出现“全体断联一整天”的事故。6.4 子模块地址全部指向上游内网 clone 依然要外网有一次同事反馈镜像站 clone 主项目没问题但执行git submodule update --init --recursive之后就卡住了一直没动静。一看才发现项目里的.gitmodules文件写的子模块地址全部是https://github.com/xxx/repo.git子模块根本没有走镜像站还是直接从 GitHub 拉。这个问题的本质是git 只会按照.gitmodules里的 URL 去拉取不会自动知道你已经有一个本地镜像。解决方式是在客户端侧配置 URL 改写让开发者本地的 git 把github.com自动替换成镜像站地址git config --global url.http://git.example.com/.insteadOf https://github.com/这条配置的意思是当 git 遇到https://github.com/开头的地址时自动替换成http://git.example.com/。这个方案有副作用它会改写这台机器上所有 git 命令的 GitHub 地址包括访问 GitHub 上其他仓库的 URL 也会被替换。如果你希望只在特定项目里生效可以去掉--global改写成局部的.git/config。不过我的经验是如果团队内部对 GitHub 访问普遍不理想全局改写反而是最简单粗暴且有效的解决方案。6.5 团队误把镜像仓库当私人仓库提交代码最后一个坑非常典型也是权限设计的问题。有个新来的同事直接访问 Gitea 页面在一个镜像仓库里点了“Fork”创建了自己的私有副本然后在副本上开发最后又想合并回镜像仓库。因为 Gitea 的权限模型在某些配置下允许写操作结果他的提交直接推进了镜像仓库的默认分支。问题在于镜像仓库的下一次同步会把本地分支强制覆盖成上游状态这位同事的提交会在同步时被抹掉。更尴尬的是他提交的内容包含一些公司内部路径信息而那台 Gitea 配置的时候开了公网可访问只是没人知道而已。解决思路镜像仓库只读是底线。在 Gitea 里给普通用户组设置仓库只读权限管理员才允许写。关闭 Gitea 的公开可见范围。如果镜像站仅供公司内部使用把仓库可见性设置成“仅组织成员可见”。给新同事做一次 Keys 101 培训讲清楚镜像仓库和普通开发仓库的区别。7. 关于合规镜像站有哪些绝对不能碰的底线7.1 许可协议是镜像站的底线镜像不是“借用”本质上是再分发。GitHub 上的公开仓库不代表你可以无条件搬走再发布。每个仓库的 LICENSE 文件决定了你能不能再分发。常见的几类我实际梳理了一下MIT、BSD、Apache 2.0允许再分发但必须保留版权声明和许可协议文本。GPL、LGPL允许再分发但要保证接收者同样能拿到源代码并且衍生作品也保持相同的授权。带“禁止商用”条款的协议镜像站如果对外开放甚至只是内网长期存储都需要格外谨慎最好先咨询内部法务。实操上我建议在同步脚本里加一步检查如果仓库根目录没有 LICENSE 文件就把这个仓库标记为“仅内部缓存”默认不对外公开。这不是技术上的难事只是很多人没意识到。7.2 公开服务的“公开”二字不是随便写的镜像站如果对公网开放任何人都可以通过你的站下载代码。这个时候你就不再只是“团队内部工具”而是某种意义上的公共资源。随之而来的问题是所有仓库内容都要过一遍版权和合规审查。所有下载请求都要有访问日志不然出了问题根本没法追踪。上游仓库作者如果发来投诉要求撤下某个仓库你需要及时响应。我个人的选择是内网使用优先除非有明确的产品需求否则不把镜像站暴露到公网。7.3 关于边界的个人建议如果让我重新搭一次第一周就会把两件事做了一是把许可证信息做成仓库的 metadata在 Web 页面上一眼能看到二是把访问日志完整留下。不是为了应付检查而是为了避免几个月后仓库涨到上千个再回去整理许可证就会非常痛苦。镜像站本质上是一个“搬运工”的角色做好它很简单守住边界很难。只要你能确保每个仓库的来源、许可、访问范围都清清楚楚这个站就能长期稳定地服务团队但凡有一条边界被忽略后续的麻烦都是指数级增长的。我现在的习惯是每季度抽查一批仓库核对上游是否有许可证变更、是否出现异常访问顺手清理掉不再需要的同步任务。这个动作花不了多少时间但能让镜像站一直保持在一个干净、可控、可信的状态。