GitHub 镜像站这个需求，很多团队迟早会遇到。可能是开发环境部署在隔离内网，代码没法直接往外拉；也可能是团队人多项目杂，每个人都从外网仓库逐个拉取，带宽和等待时间都受不了；还有一种是做代码归档，希望把关键的公开仓库都在内部留一份底稿。我第一次搭的时候，想法特别天真：不就是找台服务器 clone 一份吗？真正动手才发现，选哪种方案、同步频率怎么定、存储怎么规划、权限怎么控制，每一步都有讲究。
这篇文章把我从需求判断到落地运维的完整思路写下来，重点覆盖两种主流做法：用 Gitea 搭建带 Web 界面的镜像站，以及用纯 Git 命令加定时任务做轻量镜像。文章后面还附了踩坑记录和排查清单，想给团队内部做一个统一代码入口的朋友，不管有没有基础，都能照着动手。
1. 先想清楚：你要的是哪种镜像
镜像站听起来是一个词，实际落到需求上至少有四种完全不同的形态。不先把这个问题拆清楚，后面很容易做出一个“能用但没人用”的东西。
1.1 四种常见的镜像形态
第一种是代码浏览型。团队里有一部分人只是要看某个开源项目的源码结构、README、提交记录，并不想在自己机器上 clone。这类需求最轻，一个能列出目录和文件、能看 commit 的 Web 页面就够，GitWeb、cgit 之类的工具就能干。
第二种是 Git 拉取型。研发人员要把仓库拉进本地开发，CI 机器要拉代码构建，这时候镜像必须是一个完整的 Git 远程端，支持 clone、pull，甚至可能支持 push。这是最常见的形态，也是这篇文章主要讨论的场景。
第三种是制品型。很多项目在 GitHub Releases 里放二进制安装包，或者有编译好的工具，镜像这些文件需要考虑大文件存储和校验。它和代码仓库是两个体系，如果需求里有“下载 release 资产”，别天真地以为 clone 仓库就够了。
第四种是包依赖型。这是最容易混淆的，很多人说“代码拉不下来”，实际指的是依赖包拉不下来，比如 npm 安装包、Python 依赖。解决这类需求应该搭包管理器自己的镜像缓存，比如 npm 的 registry 镜像、pip 的 index 镜像，而不是 Git 仓库镜像。两套东西别混在一起规划。
1.2 实时性要求决定架构
第二个要问自己的问题是：镜像内容需要多新。如果只是归档备份，每天同步一次都嫌多；如果 CI 要用最新的代码，那延迟可能是致命的。
Git 层面的同步一般有两种机制。定时同步最简单，写个 cron 或者用平台自带的周期任务，每隔几小时把远端 refs 抓一遍，差分更新，增量很小。事件触发更实时，GitHub 上配置 Webhook，仓库有 push 事件时立刻通知你的镜像服务去同步，代价是要额外维护一个接收端服务。
大多数团队用定时同步就够了。GitHub 上的活跃仓库，半天内的延迟对代码浏览和构建来说完全无感；真正需要秒级同步的场景很少。
1.3 先盘一下手头的资源
动手之前，我还建议把三样东西理清楚。
存储是最容易低估的。一个仓库的 .git 目录往往比工作区大好几倍，历史越久越夸张。如果做 Git 拉取型镜像，一定要用裸仓库（bare repository），只存 Git 内部对象，不保留工作区，体积小很多。另外 LFS 大文件是独立的存储池，别忘了算进去。
带宽决定了首次全量同步要多长时间。第一次同步要把远端的完整历史都拉下来，几十 GB 的仓库能把出口带宽打满好几个小时。尽量选在夜间或者业务低峰期做第一次全量，后续增量同步就很轻了。
权限也要提前想。镜像公开仓库没有门槛，但一旦涉及私有仓库，就需要远端凭据，同时对内网访问者也要做访问控制，否则等于把公司私有代码暴露给整个内网。
2. 架构选型对比：三种方案怎么选
我见过不少人上来就问“用哪个软件搭”，其实方案选择完全取决于需求。这里直接给一张对比表，你可以对着自己的场景勾。
| 方案 | 适合场景 | 是否有 Web 界面 | 同步方式 | 维护成本 | 资源占用 |
|---|---|---|---|---|---|
| Gitea 镜像仓库 | 团队需要浏览、拉取、权限管理 | 有 | 内置周期同步和手动同步 | 低 | 很低 |
| 纯 Git 裸仓库 + cron | 只需要内网能 clone/pull，没人要看 Web | 可加 GitWeb | 自定义脚本定时 | 最低 | 极低 |
| GitLab 仓库镜像 | 内部本来就在用 GitLab 做代码托管 | 有 | 内置镜像功能 | 中高 | 高 |
| Nginx + cgit/GitWeb | 只要只读浏览源码 | 有 | 无写能力 | 低 | 低 |
2.1 各种方案的优缺点
Gitea 是我最常用推荐的首选。它是 Go 写的单二进制文件，内存占用比 GitLab 小一个数量级，2C4G 的小机器就能跑得动，自带的“迁移/镜像”功能正好覆盖 GitHub 仓库同步需求，同步进去的仓库还天然有 Web 浏览、内网权限控制，并且提供 API 方便批量操作。
纯 Git 命令方案适合极简场景。我的习惯是：如果只是 CI 服务器要一个可靠的代码源，或者带宽和机器都很紧张，就不上 Web 服务，直接在服务器上用git clone --mirror建立裸仓库，再用 cron 周期更新。缺点是没界面，想看代码还得另想办法。
GitLab 只有在团队已经重度使用 GitLab、不想再维护第二套系统时才值得考虑。它的仓库镜像功能也很成熟，但一套 GitLab 动辄要 8GB 内存，只为同步 GitHub 仓库而上它，性价比太低。
cgit 和 GitWeb 这类只读浏览方案，适合“只是想让同事方便看代码、完全不需要拉取”的纯浏览需求。它们的定位和 Git 远程端不同，别拿来当主力方案。
2.2 为什么我把 Gitea 放在默认位
我的理由很实际。第一，部署足够简单，下载一个二进制或者拉一个镜像就能跑，很多服务器环境都能轻松承载。第二，内置镜像功能是现成的，填一个远端仓库地址、填一个访问凭据、选好周期，剩下的事平台自己干，不用自己写同步逻辑。第三，Gitea 对 GitHub 的兼容性做得很好，仓库结构、分支、标签、发布页都能对应上。
尤其对中小团队，省事是第一位的。我自己给客户做方案，只要对方说“想要一个内网能看代码、能拉代码的统一入口”，我基本直接选 Gitea，后面剩下的基本都是细节调优。
2.3 什么时候不要用带界面的方案
带界面的方案也会带来不必要的负担。比如你只是希望 CI 机器能快速拉到某几个仓库的代码，不需要任何人浏览；或者你已经有内部的代码托管平台，只是需要把 GitHub 的仓库自动同步进现有平台；又或者服务器资源配置低到跑 Web 服务都有压力。这些情况下，用纯 Git 命令加一个几十行的同步脚本，反而是更优雅的解法。
所以我的建议是：需求不明确的时候先用 Gitea，因为它进可攻退可守；需求明确为“只要一个能拉取的 Git 地址”的时候，直接用裸仓库方案。
3. 实操：用 Gitea 搭建带界面的镜像站
这一节是完整可照抄的步骤。我用 Ubuntu 22.04 + Docker 的方式演示，实践中这是最省事的路径。如果你不喜欢容器，Gitea 官方也提供直接运行的二进制文件，原理一样。
3.1 环境准备与安装
先准备一台服务器，配置参考：2 核 CPU、4GB 内存、存储按仓库体积预留，起步建议 100GB。系统装好后，创建目录并写一个 docker-compose 配置：
services: gitea: image: gitea/gitea:1.22 restart: always volumes: - ./gitea-data:/data ports: - "3000:3000"启动完成后来到http://服务器IP:3000，第一次访问会进入初始化页面。数据库这一项直接用 SQLite 就够了，除非你预估仓库量非常大，否则没必要为了它单独装 MySQL。管理员账号在初始化页面创建，域名可以先随便填，后续在配置里改。
有一点值得注意：/data目录务必挂到独立的数据盘。我见过有人把 Gitea 数据放在系统盘，同步几个月后磁盘满了，整个系统卡死，恢复成本很高。
3.2 配置 GitHub 凭据和第一个镜像仓库
Gitea 同步 GitHub 仓库需要凭据。如果只同步公开仓库，可以不用凭据，但实践中我建议还是创建 token，一是避免刷新率受限，二是以后可能同步私有仓库。
在 GitHub 的 Settings -> Developer settings -> Personal access tokens 里生成一个 token，权限只需要repo（或更细的public_repo），不要给多余权限。最小权限原则在自动任务里特别重要，因为 token 一旦泄露，影响范围就是你给的范围。
然后在 Gitea 页面右上角点“+”号，选“迁移仓库”，再选“迁移/镜像”方式，填这些关键项：
- 源仓库地址：
https://github.com/owner/repo.git - 托管地址：GitHub 仓库的 Host/Owner，Gitea 会引导填写
- 镜像周期：界面里默认提供若干挡位，最小一般到半天或几小时级别，如果团队要求更短，需要改配置文件或用外部计划任务触发
- 用户名和密码：填 GitHub 用户名和刚才的 token
创建完成之后，Gitea 会立刻执行一次同步。你会在仓库列表里看到这个项目，代码、分支、标签全部从 GitHub 拉进来了。
这里有个 Gitea 的行为特性要提前说明：镜像仓库默认是只读的。任何人往内网镜像里 push，下次同步时会被远端内容直接覆盖。如果你希望团队在内网开发并反推回 GitHub，应该另外建普通仓库，而不是直接在镜像上乱搞。
3.3 批量把一批仓库登记成镜像
如果只有几个仓库，界面操作没问题。但常见场景是一个组织下有几十上百个仓库，一个个点会点到怀疑人生。这时候要走 Gitea API。
在 Gitea 后台生成一个 API token，然后在服务器上执行一个循环脚本，示例如下：
GITEA_URL="http://git.internal" GITEA_TOKEN="你的token" for repo in owner/repo1 owner/repo2 owner/repo3; do curl -X POST "$GITEA_URL/api/v1/repos/migrate" \ -H "Authorization: token $GITEA_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "clone_addr": "https://github.com/'"$repo"'.git", "repo_owner": "内网用户名", "repo_name": "'"$(basename "$repo")"'", "mirror": true, "private": false }' done这里的mirror: true是关键，等于告诉 Gitea 这个仓库是镜像，不是普通迁移。脚本跑完后，到 Gitea 页面检查仓库数量和同步状态。
批量操作时我建议控制并发。GitHub 的 API 有速率限制，瞬间发几十个请求很容易撞上 403，稳妥的做法是在循环里加sleep 1或者用串行方式跑，反正首次同步本身也耗时间，不差这几秒。
3.4 给镜像站加一个统一访问入口
Gitea 默认监听 3000 端口，给团队用还行，但不方便记。正规一点的做法是加一层 Nginx 域名接入。在 Nginx 里配置一个 server 块，把域名请求转发到本机 3000 端口即可，这是非常常规的转发配置：
server { listen 80; server_name git.internal; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }配好后，团队成员在内网直接把git.internal解析到你服务器，就能用统一的地址访问镜像站，git clone http://git.internal/owner/repo.git也直接可用。如果不方便配 DNS，临时用 hosts 文件也是一样的效果。
4. 轻量方案：纯 Git 命令加定时任务的裸仓库镜像
如果你的需求很纯粹，只要内网能 clone/pull，不想维护 Web 服务，这个方案最省心。核心就三个动作：建裸仓库、周期更新、开放访问。
4.1 建立镜像仓库
先在服务器上建一个目录，比如/srv/git，然后对每个目标仓库执行：
git clone --mirror https://github.com/owner/repo.git /srv/git/repo.git--mirror是这里的关键参数。它会把远端的所有引用完整镜像下来，包括分支、标签、远端头信息，相当于一个“全量快照”。普通git clone不会带远端分支引用，做镜像会吃亏。
首次全量可能需要很长时间。大仓库建议先用部分克隆方式拉框架，再补充对象：
git clone --mirror --filter=blob:none https://github.com/owner/repo.git /srv/git/repo.git--filter=blob:none表示只拉 commit 和 tree 对象，不拉文件内容（blob），这样仓库结构和历史能很快到位，文件内容在后续访问或同步时按需补充。对超大 monorepo，这个技巧能救命。
后续增量同步就很简单了：
git -C /srv/git/repo.git remote update --pruneremote update --prune会拉取远端新增内容，同时把远端已删除的引用清理掉，保持镜像和源仓库一致。
4.2 用定时任务自动化同步
把这些操作写成一个脚本，放到 cron 里执行。脚本大概长这样：
#!/bin/bash for repo_dir in /srv/git/*.git; do git -C "$repo_dir" remote update --prune donecrontab 里加一行：
0 */6 * * * /opt/mirror-sync.sh >> /var/log/mirror-sync.log 2>&1这样每 6 小时自动同步一次。实际周期怎么定，看你的仓库更新频率，活跃项目可以每小时，归档性质的一天一次都行。
4.3 对内网开放 Git 拉取
裸仓库本身只是一个目录，要让人能拉，得把它暴露成 Git 服务。最省事的方式是 Nginx + git-http-backend，这样走 HTTP 协议，防火墙和代理都友好。
先安装依赖：
apt install nginx fcgiwrap git然后配置 Nginx，核心片段如下：
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; fastcgi_param GIT_HTTP_EXPORT_ALL true; fastcgi_param PATH_INFO $1; }配置好后，团队成员执行git clone http://镜像服务器/git/repo.git就能拉代码。这个方案是只读服务，没有写入口，所以不存在内网误 push 覆盖镜像的隐患，安全性上反而更省心。
如果仓库里有 LFS 大文件，记得在服务器上装git-lfs，同步时补一步：
git -C /srv/git/repo.git lfs fetch --all普通git remote update不会拉 LFS 对象，漏掉这一步，你的镜像里文件会只是一堆占位指针，拉下来就废了。
5. 常见问题与排查实录
方案再好，落地总会遇到问题。我把这段时间在镜像站运维中最常遇到的问题整理成一张速查表，再加三个我印象深刻的具体故障。
5.1 问题速查表
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 镜像仓库一直是同步失败状态 | token 过期、GitHub API 限流、远端仓库地址变化 | 换新 token、检查权限范围、查看 Gitea 运行日志 |
| 同步跑到一半就断了 | 网络波动导致连接中断 | 手动触发重新同步，后续增量会接着完成 |
| LFS 文件拉下来是空指针 | 镜像端没有启用 LFS 同步 | Gitea 中开启 LFS 支持，纯 Git 方案执行git lfs fetch --all |
| 磁盘被对象文件塞满 | 仓库历史增长、没做定期维护 | 监控磁盘水位，规划仓库配额，必要时清理孤立对象 |
| 内网 push 的内容被远端覆盖 | 镜像仓库本身只读，这是预期行为 | 需要内网协作就另建普通仓库并手动同步过去 |
| 批量迁移时 API 频繁报 403 | GitHub 速率限制 | 降低调用频率，分批执行，或使用 GitHub App 代替个人 token |
| 远端改了默认分支，镜像没跟随 | 部分同步脚本没更新 refs/remotes 头 | 确保执行了完整的remote update --prune |
5.2 三个印象最深的故障
第一个是超大 monorepo 首次克隆超时。仓库历史有几十 GB，git clone --mirror跑了一夜都完成不了。后来改用--filter=blob:none做部分克隆，先让 commit 和目录结构到位，文件内容按需获取，几分钟就把框架拉完了。这让我理解到一个关键点：镜像同步不一定要一次全量到位，分阶段也是合理的。
第二个是私有仓库同步 403。Gitea 日志里看到权限拒绝，排查了一圈才发现是 token 只勾了public_repo，没有repo权限。这个教训是：GitHub 的 token 权限是严格按照接口区分的，创建 token 时就要想好哪些仓库需要镜像，否则后续排查很费劲。
第三个是磁盘写满导致所有同步集体卡死。镜像仓库数量多，对象文件快速增长，系统盘被塞满，Gitea 写不进去，所有同步任务全部挂起。最后靠清理一批不再需要的旧仓库才缓过来。后来我养成了两个习惯：数据目录放独立数据盘，或者给存储做水位监控告警。
5.3 例行检查清单
镜像站搭好后不是扔在那里就不管了，我建议定期做这几项检查：
- 翻一遍同步日志，看有没有异常报错
- 查看磁盘使用率，提前规划扩容量
- 确认 token 没过期，尤其是用个人 token 的场景
- 随机抽一个仓库执行
git fsck，验证仓库完整性
这些检查加起来十几分钟，能避免大部分“半夜接到告警”的尴尬。
6. 长期运维的个人体会
最后聊几点纯经验层面的东西。我在实际使用中发现，镜像同步周期真的不是越短越好。同步频率越高，意味着对远端的请求越频繁，API 限流风险越大，而没有实际收益。我的做法是区分仓库优先级：团队高频使用的那几个仓库，同步周期设短；历史归档类仓库，一天一次完全足够。
权限设计也值得多花心思。镜像仓库对内网通常保持只读，这是最省事的策略。如果团队需要基于镜像的代码再做开发，就另建普通仓库，通过手动导入或者额外同步来维护，千万不要让所有人都能在镜像上乱写。
还有一件事是我踩过几次坑之后才养成的习惯：所有同步相关的凭据都要单独管理，不要跟个人日常账号混在一起，token 权限尽量最小化。自动任务里的凭据一旦泄露，影响范围就是你给它的那点权限，权限小一点，风险就小一点。
这套东西整体的维护成本其实很低，真正花时间的永远是第一次全量同步和大仓库的处理。把存储规划好、同步策略定清楚、监控配到位之后，GitHub 镜像站基本就是一个“后台自动跑，偶尔看一眼”的基础设施了。我现在的习惯是每隔一段时间抽查一次仓库完整性和日志，顺手清理磁盘，剩下的时间，它都能安安静静地在后台把代码同步得好好的。
