Git仓库本地化：从镜像克隆到自建服务的完整迁移指南

在公共代码托管平台嫖了这么多年仓库，很多开发团队都会遇到这样一个不能再熟悉的场景：项目越来越重要，团队规模变大，合规要求收紧，或者你所在的内网环境根本连不到外网，这时候“git仓库本地化”就成了绕不开的话题。我理解的本地化，不是简单地把代码clone到笔记本上，而是把整个项目的历史、分支、标签、协作流程，完完整整地搬到你能控制、能访问、能备份的本地环境，用自建的Git服务或者离线仓库继续高效运转。这篇文章就围绕“git仓库本地化”这件事，从需求判断到方案选型，从迁移实操到日常维护，把每个环节的细节和踩过的坑都摊开讲讲，适合正在考虑离开公共托管平台、想落地内部Git服务、或者在离线环境中搭建版本管理的团队和个人开发者参考。

1. 本地化的核心场景与方案选型

1.1 你真的需要本地化吗：典型需求拆解

绝大多数团队最初选择公共托管平台，图的就是省事：注册账号、创建仓库、push代码，一切都有现成的UI和权限管理。但一旦项目走向深度开发或者进入交付阶段，几个实际问题会逼着你认真考虑本地化。

第一种场景是内网隔离。很多涉密、金融、军工或者大型国企的项目开发环境本身就不允许访问外网，开发服务器在隔离网段，代码只能通过摆渡方式进入，这时候如果你还在公共平台上托管代码，连基础push都做不到。第二种场景是数据主权和合规要求。部分行业明确要求源代码、文档等资产必须存放在境内自有服务器或指定物理范围内的存储设备，不允许第三方SaaS平台保存核心代码。第三种场景是成本与控制力。小团队初期用免费额度没问题，但仓库越来越大、成员越来越多，私有仓库、超大存储、CI/CD集成都开始收费，而且你无法控制平台方的服务稳定性，一旦对方调整策略或服务中断，整个研发流程都要停摆。

还有一种容易被忽略的场景：单个开发者长期依赖某个公共仓库管理个人笔记、配置文件，但担心平台账号被封或者仓库被误删，想把所有历史完整搬回本地。这种轻量需求其实也很适合“git仓库本地化”。

判断是否需要本地化，我通常问三个问题。第一个，多长时间之内必须用外网？如果需求里写着“永久离线”，本地化是唯一选择。第二个，团队协作是否依赖Web端的MR/PR、Issue、Wiki这些功能？如果是，那本地化就不只是搭一个裸仓库，而是要选带Web界面的自建Git服务。第三个，历史资产是否宝贵？如果仓库里有大量分支、标签和多年提交记录，迁移时必须要做完整克隆，而不是copy工作目录。

1.2 四种主流落地形态对比

把git仓库本地化，听起来是同一个需求，实际落地形态差别很大。

第一种形态是“纯裸仓库+SSH”。这种方式最轻量，只需要一台Linux服务器，安装好Git，然后创建一个裸仓库目录，开发者的remote地址改成ssh://user@server/git/repo.git即可。好处是几乎没有额外依赖，内网穿透或局域网直接访问都很顺畅。坏处是没有Web界面，没有issue跟踪，代码浏览只能靠命令行或者本地IDE，跨团队协作的门槛高。

第二种形态是“自建轻量Git服务”。借助开源Git服务软件，在本地服务器上部署一套带Web界面的仓库管理平台，支持用户管理、权限分组、在线代码查看、合并请求等功能。相比裸仓库，这种方式更接近公共平台的体验，同时数据完全在自己手里。部署成本适中，对运维的要求也不高，单机部署就能支撑几十人的团队使用。

第三种形态是“物理服务器上的集中式裸仓库集”。可以理解为多个裸仓库通过一个父目录统一管理，配合系统用户的SSH权限来做访问控制。这种方式适合非常传统的内部团队，所有仓库都放在一台内网文件服务器上，通过SSH协议访问。它的特点是“所见即所得”，任何一台内网机器都能通过git clone git@server:repo.git拉取。

第四种形态是“本地镜像同步”。适合那些仍然暂时离不开公共平台，但希望每次提交都能自动同步到本地服务器作为备份和合规归档的场景。用定时任务拉取远端更新到本地裸仓库，保证本地仓库副本随时可用。这不是彻底的本地化，但很多过渡方案都会从这个模式开始。

四种形态不是互斥的，最常见的是先做镜像同步，再把团队迁移到自建服务上，最后彻底切断外网依赖。方案选型的关键在于：是想要“能push代码”，还是想要“完整替代平台”。

1.3 方案选型的三个关键决策点

第一个决策点：团队规模与分工复杂度。5人以下的小组，裸仓库完全够用；20人以上、并行分支多、需要代码评审协作，没有Web界面会很痛苦。第二个决策点：网络边界。如果本地化后所有客户端都在同一网段内，SSH直连效率最高；如果客户端要跨网段访问，那就要考虑在自建Git服务上开启HTTP/HTTPS协议。第三个决策点：备份与容灾要求。裸仓库虽然简单，但如果服务器只有一块盘，坏掉就是全毁；自建服务通常能配合存储快照、定期归档等机制，数据可靠性更高。

选型时还有一个容易忽略的点：迁移后的管理成本。本地化之后，所有用户账号、SSH key、仓库权限都要自行维护。如果你本来就没有专职运维，那就要优先选带简单Web管理界面的开源服务，而不是指令行+系统账号那套，否则日常维护会变成灾难。

2. 迁移前的仓库体检与准备

2.1 盘点仓库体量与历史包袱

直接在公共平台点“Download ZIP”再塞到本地仓库的人，十有八九会在两周后后悔。因为ZIP包没有完整Git历史，所有分支、标签、提交图全部丢失。真正做git仓库本地化，第一步是体检。

先看仓库大小。在项目目录里执行du -sh .git能看出对象库的体积，但对象库里包含各种历史版本对象，真正传输的体积可能比工作目录大很多。我建议先通过git count-objects -vH查看当前松散对象和包文件的大小，确认是否触发传输瓶颈。再看分支数量，git branch -a能列出所有本地和远端分支；还要看标签，git tag列出所有标签；最后看remote配置，git remote -v确认当前所有远端信息。

很多人在迁移后才想起某个重要分支没带过来，就是因为体检环节偷懒。我整理过一个完整的体检命令组合，通常在迁移前一晚执行：

# 查看仓库整体大小（含历史） git count-objects -vH # 查看所有分支（本地+远端） git branch -a # 查看所有标签 git tag # 查看远端仓库地址 git remote -v # 查看提交历史里最大的几个文件 git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $3, $4}' | sort -rn | head -10

最大的几个文件往往是迁移失败的根源，必须提前知道它们在哪里。

2.2 分支、标签、远端配置全梳理

仓库体检不能只停留在数字层面，还要看引用结构。远端的origin/develop、origin/release/1.0这些分支，在你clone下来之后会变成远程跟踪引用，如果不做映射，团队成员在本地看到的只有origin/*，而本地分支数量可能只有master一条。

我建议迁移前先导出一份分支清单，明确哪些分支是活跃分支，哪些是已经合并过的死分支。死分支没必要全部迁到新仓库，保留主干和活跃功能分支即可。标签也容易遗漏，尤其是那些带注释的annotated tag，普通git clone都能正常拉取，但如果是手工复制.git目录，标签就会丢失。

远端配置的迁移也常被忽略。如果原仓库有多个remote，例如公共平台是origin，内部还有upstream，那就要在本地化新仓库里重建这些remote。我习惯先把旧仓库的remote配置记录下来：

git remote -v

然后在新环境里统一添加。少一个remote，可能就断了一条上游拉取通道。

2.3 提前处理大文件和敏感信息

这是git仓库本地化里最容易被忽视但最致命的环节。大文件进入Git历史后会永远躺在对象库里，即使后来删除了文件，历史记录仍然占用大量存储。迁移过程中如果带上一堆几百MB的二进制文件，整个克隆传输会慢到让人怀疑人生，服务器目录也会迅速膨胀。

解决办法是：如果项目还没使用LFS，先检查历史中是否有大文件，如果有，考虑用git lfs迁移或者用历史重写工具清理。但历史重写会改变commit哈希，所有开发者的本地分支都会受影响，所以必须在迁移前跟团队确认是否可以接受。

敏感信息同理。如果有人把密码、密钥、Token直接提交进了历史，那么本地化之前必须先通过git filter-repo或者git filter-branch清理历史，否则仓库落到本地服务器后，泄密风险并没有消失，反而因为本地防护可能更薄弱。

我踩过一次很深的坑：迁移一个旧项目时没有做历史清理，结果本地仓库里藏着三年前的数据库口令，导致后续安全审计整改时费了很大劲。所以我的建议是：任何仓库从公共平台搬到本地，都要把“历史文件扫描”当成强制步骤。可以用git log --all --oneline -- source或者专门的密钥扫描工具扫一遍提交历史，确认没有敏感字符串再动手。

3. 核心实操：从远程仓库完整克隆到本地

3.1 裸克隆与镜像克隆的区别

很多开发者熟悉git clone，但迁移场景真正该熟悉的是git clone --bare和git clone --mirror。

普通clone会把远程仓库复制到本地工作区，生成.git目录和一份当前分支对应的文件快照，适合日常开发。但迁移仓库到本地服务器，我们需要的是“仓库本身”，也就是只有.git内容、没有工作目录的裸仓库。

git clone --bare会把远端仓库的Git对象和引用完整复制到本地，但裸仓库不包含工作目录，不能在上面直接修改文件，它只作为push/pull的服务端仓库。git clone --mirror则更进一步，它会复制远端的所有引用，包括所有分支、标签、远程跟踪分支，并且保证后续git remote update时能精确同步远端的状态。

这里有一个容易混淆的点：裸克隆只复制了远端分支对应的对象和HEAD的当前状态，标签通常是同步的，但“远端仓库里的remote跟踪引用”可能不会完全一致。如果需要做严格的一比一镜像，优先用--mirror。

在迁移场景里，如果只是把公共平台的仓库搬回内网裸仓库，我会这样操作：

git clone --mirror https://某平台地址/org/project.git cd project.git git remote -v

执行完以后，project.git目录就是一个包含完整历史的独立Git仓库。注意这里的地址要替换成实际项目的URL。在本地化落地前，这个裸仓库还不能直接给别人push，需要先放到正确的路径下，或者导入自建Git服务。

3.2 把本地裸仓库变成可写可协作的托管服务

如果你选择的是“裸仓库+SSH”方案，下一步就是把刚才镜像出来的裸仓库放置到服务器统一管理目录，比如/srv/git或者/home/git/repositories下。

以一台Linux服务器为例，给git用户创建专门的仓库目录：

sudo mkdir -p /srv/git sudo chown -R git:git /srv/git

然后把镜像裸仓库移动进去：

mv project.git /srv/git/project.git

裸仓库默认是不接受push的，因为Git找不到工作目录，但作为服务端仓库它只需要接收push。你需要显式开启这个能力：

cd /srv/git/project.git git config receive.denyCurrentBranch ignore git config core.bare true

这里core.bare true保证它保持在裸状态，receive.denyCurrentBranch ignore允许其他工作仓库推送代码到这个裸仓库。如果只是做备份用途，不需要允许push，那可以保持默认拒绝。

接下来要处理权限。最简单的做法是设置git用户作为仓库所有者，把仓库目录的权限控制好。每个开发者的SSH公钥加到git用户的authorized_keys里，同时限制每个key只能执行git-shell命令，避免通过SSH登录进服务器。创建用户时可以用git-shell做登录shell：

sudo useradd -m -s /usr/bin/git-shell git

然后在/home/git/.ssh/authorized_keys里逐行添加开发者的公钥。这样每个开发者连接服务器的时候只会看到Git命令环境，无法获取系统shell，安全等级高很多。

如果是选择自建Git服务，通常服务软件自带导入仓库的功能，我只需要把裸仓库目录配置到服务的仓库根目录下，或者通过Web界面新建空仓库后再把裸仓库内容推过去。

3.3 保存全部引用与替换远程地址的命令详解

从公共平台迁移到本地仓库，还有一个必要动作：把本地开发环境的remote地址切换到新地址。

假设你原来的项目在本地的工作区还保留着，但服务器上已经建好了/srv/git/project.git，你只需要在本地项目里修改remote地址：

git remote set-url origin git@your-server:/srv/git/project.git

如果你的本地代码不是从旧仓库clone的，而是直接用git clone --mirror生成裸仓库后想要导出工作区，可以用git clone从裸仓库再克隆出一个工作副本：

git clone /srv/git/project.git my-project

注意这里用的是本地路径，Git会自动识别，等效于走SSH协议。

还有一个技巧是保留旧remote作为备份。比如公共平台地址设为old-origin，本地服务设为origin：

git remote rename origin old-origin git remote add origin git@your-server:/srv/git/project.git

分布式灵活性在这里体现得很充分，迁移后依然可以定期从旧地址拉取更新，也可以把新提交同时推送到两个远端，形成双写。

但如果要彻底本地化，我通常会额外执行一次引用清理，把旧remote的远程跟踪分支从本地仓库中移除，避免干扰：

git remote prune old-origin

这些操作看似简单，但命令顺序错了会导致包引用混乱。我建议按照先镜像、再放置、再配置权限、最后改remote的顺序推进，每一步都能通过git remote -v或者git ls-remote验证。

4. 本地化后的同步策略与日常维护

4.1 单向备份：离线锁库场景

有些团队做本地化是为了彻底告别公共平台，本地仓库成为唯一数据源。这种情况下同步策略就是“没有任何外来的同步”，一切本地push/pull都发生在内网。此时维护重点变成备份。

我强烈建议对裸仓库做定时快照，而不仅仅是依赖文件复制。因为Git仓库在高并发push时，如果直接用cp -r拷贝，可能会复制到中间状态导致备份损坏。最简单的可靠方式是先用git clone --mirror克隆一份备份，或者用git bundle把整个仓库打包成一个文件。

一条git bundle命令就能生成完整的仓库快照：

git bundle create project-backup.bundle --all

这个bundle文件包含了所有分支和标签，可以放到另一台机器上随时恢复：

git clone project-backup.bundle project-restored

等价于把整个仓库装进一个文件。做定时任务时，每条仓库跑一次bundle，再配合异地存储，离线场景下的数据安全就有保障了。

4.2 双向同步：本地与远程并行的双轨制

如果你的团队还没有完全切干净，公共平台和本地服务器都要保留一段时间，那就需要一套清晰的双向同步策略。

我的建议是：确定一个权威仓库，其他仓库都作为它的镜像或下游。最简单也最不容易出错的方式是把本地服务器当成中心，公共平台上的仓库作为上游来源，定时从上游拉取：

cd /srv/git/project.git git remote add public https://某公共平台地址/org/project.git git fetch public

但裸仓库默认没有工作区，不能直接merge。如果要让本地裸仓库保持与上游公共仓库的绝对一致，我们可以在定时任务里执行git fetch public +refs/heads/*:refs/heads/*，强制让本地分支指针与上游对齐。这会覆盖本地直接push的提交，所以双轨制要求团队所有人员在本地服务器上协作，公共平台的提交只是单向流入，不在公共平台上直接修改。

想实现双向的话，就必须保证有一个人或一台机器负责在两边之间搬运提交。最朴素的搬运方式是，在本地服务器之外的某台工作机上，同时挂着两个remote，执行git pull old-origin && git push new-origin。如果频率不高、变更不冲突，这条链路完全够用。

考虑到两个平台可能对分支权限、文件大小有不同的限制，我会额外写一个同步日志脚本，记录每次同步的分支和提交数，防止静默失败。

4.3 定时同步与Hook自动化

手动执行同步不是长久之计，尤其是本地化之后，日常维护如果还靠人工记着“每周五同步一次”，大概率会在第三周忘掉。

Linux环境下用cron做定时任务最直接。假设我们每天早上8点同步一次公共平台到本地仓库，在crontab里写：

0 8 * * * /usr/local/bin/sync-git-repos.sh

同步脚本的核心逻辑是把本地裸仓库的引用同步到上游：

#!/bin/bash REPO_DIR="/srv/git/project.git" cd "$REPO_DIR" git remote update --prune 2>>/var/log/git-sync.log git for-each-ref --format='%(refname)' refs/remotes/public/ | while read ref; do local_ref=${ref#refs/remotes/public/} git update-ref "refs/heads/$local_ref" "$ref" 2>>/var/log/git-sync.log done

这个脚本做的事情是先从公共平台拉取所有新引用，然后把远程跟踪分支的引用强制更新为本地分支。虽然粗暴，但对一个只读镜像仓库而言是可行的。

如果担心定时任务执行时机与团队push时间撞车，现代Git同步可以在push时触发服务端Hook，比如在/srv/git/project.git/hooks/post-receive里写上触发内部CI构建或同步的命令，这样代码一推上来，备份或构建流程立即跟着跑。

#!/bin/bash # post-receive hook 示例：推送到本地仓库后自动备份到指定目录 git bundle create /backup/$(date +%Y%m%d%H%M)-project.bundle --all

这样就不再需要额外cron，维护动作全部都绑定在Git事件上，思路更干净。

5. 常见问题与排查技巧实录

5.1 克隆不完整、丢分支怎么破

我见过很多新人在本地化迁移后，发现团队成员clone下来的仓库里看不到某些分支。原因通常有三个。

第一个原因是原仓库有“隐藏”分支，不在常规的分支列表里，需要用git branch -a仔细检查。如果远端分支是受保护分支或通过PR创建但未合并的，普通用户可能看不到全部，迁移者要确保自己有足够的读取权限。

第二个原因是镜像方式不对。如果用了git clone --bare而不是git clone --mirror，某些引用可能没有被复制。验证方法是在新建的裸仓库里执行：

git branch -a && git tag

与原始环境的git ls-remote --heads对比，数量一致才算完整。

第三个原因是本地分支和远程跟踪分支没有建立映射关系。clone下来后，默认只有当前工作分支的本地分支，其他origin/*分支需要手动创建：

git checkout -b feature-test origin/feature-test

对于大量分支，可以写循环自动处理：

git for-each-ref --format='%(refname:short)' refs/remotes/origin/ | while read branch; do local_ref=${branch#origin/} if ! git show-ref --verify --quiet "refs/heads/$local_ref"; then git branch --track "$local_ref" "$branch" fi done

这个命令能快速把所有远程分支都生成对应的本地跟踪分支。

5.2 权限体系与SSH key冲突

本地化后最难管理的是权限，尤其是多人共享同一个git用户再用authorized_keys区分身份的模式。

我遇到过团队里两个人用了相同账号，结果一个老员工离职后，其他人没法判断仓库提交的真实归属。提交作者其实是由本地Git配置的user.name和user.email决定的，但如果强制推送到裸仓库，服务端只验证SSH key有没有权限，不验证提交者的邮箱是否匹配。这样内部审计时，一个account里所有提交都会被算到同一人名下。

要解决这个问题，最好让每个开发者拥有独立的系统用户，或者使用带Web管理的Git服务来管理用户。如果坚持共享git账号，那么至少要给每一对authorized_keys加上注释，并把开发者的SSH公钥文件命名清晰，比如：

# 用户：张三，邮箱：zhangsan@example.com ssh-rsa AAAA... zhangsan@company

另一个常见冲突是，开发者的本机可能有多个SSH key，而clone命令默认使用~/.ssh/id_rsa，连到本地Git服务器时认证失败。解决办法是在~/.ssh/config里为服务器指定对应的IdentityFile：

Host git.local HostName 192.168.1.100 User git IdentityFile ~/.ssh/id_rsa_local

这样默认使用哪个key就完全可控了。

5.3 大仓库克隆超时与内存报错

从公共平台迁移到本地服务器的过程中，克隆大仓库经常碰到两类问题。

第一类是HTTP协议的超时。如果自建服务走的是HTTP/HTTPS，仓库容量大时，首次clone可能超过网关超时时间，连接被中断。解决思路是开启HTTP的智能协议，并适当调大超时参数。不过最稳的方法还是引导开发人员直接走SSH协议传输，本地化环境下SSH是最可靠、最高效的。

第二类是内存不足。Git在压缩增量对象时需要内存，超大仓库在执行git gc或git repack时可能报错“无法分配内存”。解决方法是调整Git配置，限制打包线程和内存使用：

git config pack.threads 1 git config pack.windowMemory 256m git config pack.deltaCacheSize 128m

如果是服务器端做大规模重构，可以分批次git gc --aggressive，不要在业务高峰期操作。

还有一类容易忽视的问题是文件路径过长。Windows环境的开发者从本地服务器clone时，如果历史里有很深层的目录，会被系统路径长度限制挡住。解决方法是开启Windows的LongPathsEnabled选项，或者在迁移前将仓库目录结构扁平化。

5.4 误删本地分支后的恢复

本地化之后，分支管理完全靠自己，误删分支的恢复就更依赖Git的对象生命周期机制。Git的分支只是一个指向commit的引用，删掉分支只删了引用，commit对象依然在对象库里躺着，只要没触发git gc --prune=now彻底清理，就可以通过reflog找回。

一个常见的恢复场景：

git branch -D feature/demo

当天发现删错了，马上执行：

git reflog

找到删除前分支对应的commit号，然后重建分支：

git branch feature/demo 3e9c6a7

如果这个分支只在远端存在过，但本地没有fetch记录，那可以通过git reflog show --all查看包括远程跟踪分支在内的引用日志。如果连ref log都被清理掉了，那就只能寄希望于服务器端还有备份，这也是我前面为什么反复强调裸仓库备份的重要性。

从管理角度，我建议在本地化服务的服务端开启reflog的保留时间，很多人不知道裸仓库也可以设置：

git config gc.reflogExpire 90.days

这样即使误操作，也有90天的后悔期。

6. 进阶实践与经验沉淀

6.1 用“大仓库拆分”降低本地化难度

很多存量项目在公共平台托管多年后，仓库已经变成巨石仓库，所有组件都在一个仓库里。这种仓库本地化后，不仅clone慢，权限控制也难。如果你迁移的正是这种巨石仓库，我建议趁本地化动手的时候做一次拆分。

拆分没有统一标准，我的参考原则是：按领域边界拆。把独立部署的服务、独立版本号的库、独立团队维护的代码拆成多个仓库；公共的依赖包放到统一的内部模块仓库里。拆完之后，每个仓库的线性历史更清晰，后期备份和同步压力也更小。

拆分可以用git subtree split命令把子目录提取成独立仓库：

git subtree split --prefix=packages/core -b core-branch

再基于这个分支创建裸仓库：

git branch --set-upstream-to=core-branch origin/trunk

但subtree拆分后，原仓库的历史仍然保留了那些目录，体积不会明显下降。要彻底瘦身，需要用工具重写历史。重写历史的代价是全体成员都要重新clone，迁移阶段做一次这样的操作，性价比是最高的。

6.2 多仓库场景下的统一维护脚本

本地化的项目多了之后，手动去每个仓库执行git fetch、git bundle会非常痛苦，尤其是仓库数量超过二十个时。

我习惯维护一个简单的批量脚本，核心逻辑是遍历仓库根目录下的所有子目录，对每个包含HEAD的目录执行统一命令：

#!/bin/bash REPO_ROOT="/srv/git" for repo in "$REPO_ROOT"/*.git; do echo "=== Processing $repo ===" cd "$repo" git fsck --full --no-dangling git repack -a -d git gc --prune=now done

还可以加上每周一次的bundle快照，自动按日期存到备份磁盘。这种一键巡检脚本，是本地化Git仓库日常维护最实用的工具，没有之一。

6.3 团队协作规范要跟着迁移一起更新

技术层面落地了，团队协作习惯不改，本地化的价值会打折扣。公共平台上有丰富的Web交互，例如MR评审、CI状态展示、权限审批流，迁移到本地后很多功能可能不再具备。如果团队还是按旧习惯在Web界面上找功能，却发现界面简陋甚至没有，就会产生抵触心理。

我的建议是，在迁移前一至两周同步制定新的协作规范。明确代码从哪个仓库拉取、合并请求通过什么方式发起（如果自建Git服务支持MR就用它，否则就约定命令行或内部聊天工具沟通），分支命名保持统一，tag发布规范不变。特别重要的是要明确：本地Git服务是唯一数据源，任何本地修改都要第一时间push到本地中心仓库，否则一断电，代码还在个人电脑里，就谈不上集中管理了。

另外，迁移后的首批仓库成员需要做一次clone验证，确保权限、地址、分支映射都正确。我一般会让每个开发者执行一条黄金命令：

git clone git@server:team/project.git && cd project && git branch -a && git log --oneline -3

如果每个成员都能顺利跑通，说明仓库本地化已经成功了一大半。

7. 一些踩过的坑和具体建议

再补充几个实际操作中很容易踩中的细节，这些内容在官方文档里基本不会写。

第一，域名和IP问题。本地化服务器如果只配置了内网IP，那仓库地址里就要写死IP或者内部DNS。如果以后IP有变动，所有开发者的remote地址都要跟着改。我建议从一开始就在内网DNS上给Git服务器分配稳定主机名，不要在remote地址里直接写IP，否则后续每次网络调整都是一次全员修改。

第二，裸仓库所在磁盘的剩余空间检查。Git仓库在接收push时会临时产生写入数据，如果磁盘满了，导致的错误信息往往很难懂，比如报"cannot lock ref"或者"unable to create temporary file"。我吃过这个亏，当时仓库目录所在分区只剩几百MB，同事push一个几十MB的压缩包，服务端直接拒绝，排查了很久才发现是盘满了。所以日常巡检第一件事就是看磁盘水位。

第三，使用HTTP协议时不要忘了启用Git自带的智能HTTP支持。很多人直接用Nginx映射裸仓库目录，就会发现push总是断掉，其实是因为没有配置git-http-backendCGI。与其折腾Nginx，不如直接用SSH，或者直接用成熟的Git服务软件。

第四，对大型二进制文件要“零容忍”。本地化之后，内网传输虽然快，但二进制文件会让仓库体积无限膨胀，每次clone都变慢。一定要在团队规范里注明“禁止直接提交二进制产物”，有需求就上LFS。本地化环境同样可以使用Git LFS，只是LFS的存储指针和对象库都在本地服务器，完全可控。

第五，流程上要留一条“逃生通道”。本地化不是拍板那一刻就永久切换，先并行跑两周，确认日常开发没有断档，再逐步关停外网仓库的写入权限。我见过有的团队当天切断外网仓库，结果一个尚未合并的分支留在公共平台，导致整个分支工作白白丢失。切换前务必确认所有仓库已经完整镜像，且至少有一个成员在本地工作副本中验证过所有活跃分支可以正常检出。

自己在多次迁移项目后的真实体验是：git仓库本地化本质上不是技术难题，而是一次“资产转移”。技术命令翻来覆去就那么几条，真正花时间的是梳理引用、审查历史、沟通协作方式。只要前期把仓库体检做透，镜像命令执行准确，权限收口清楚，再配合一个简单的备份策略，本地化之后的维护负担会远小于继续依赖公共平台的隐形成本。如果你正在犹豫要不要做，先把本文第二节的体检命令跑一遍，再看结果决定，方向就不会错。