企业官网建设流程全解析

最近团队在做一个不大不小的基建调整：把散落在外部托管平台上的代码仓库，全部收回到内网服务器，做一次彻底的仓库本地化。折腾了一周多，踩了不少坑，也沉淀出一套可以照抄的流程。这篇就围绕 git 仓库本地化，把方案选型、迁移细节、权限备份、问题排查串起来讲，适合正在考虑“要不要把仓库挪回内网”的团队参考，也适合自己维护多仓库的个人开发者。

先说结论：git 仓库本地化，不是简单执行一下 git clone 把文件拉到本地，而是把“代码托管 + 协作流程 + 权限体系 + 备份机制”完整搬到你能控制的基础设施上。你拥有的不是一份代码拷贝，而是一套不依赖任何外部条件的代码资产体系。想清楚这一点，后面所有步骤都有了判断标准。

1. 先把“git 仓库本地化”这件事说清楚

1.1 这个标题背后到底在解决什么问题

git 本身是分布式版本控制系统，每个开发者本地都有一份完整的历史记录，这是它设计上最巧妙的地方。但也正因为“分布式”，团队协作通常需要一个“中心仓库”作为权威事实源（source of truth），不然大家各推各的，很快就分叉得没法看。

大多数团队早期图方便，直接把中心仓库建在外部托管平台上，开个组织、拉几个成员、建几个仓库，协作就转起来了。这个模式本身没毛病，但运行一段时间后，以下几种情况会陆续出现：

• 网络层面：外部平台访问时快时慢，尤其在内网环境里，拉取一个大仓库或者频繁推送时，等待时间非常折磨人。
• 资产层面：代码仓库是核心资产，放在自己不可控的环境里，备份策略、容灾方案、数据导出权限都不由自己说了算。
• 安全层面：某些项目的代码不想经过第三方服务器，尤其是涉及内部算法、客户定制逻辑这部分，仓库的物理位置和访问链路是需要可控的。
• 流程层面：外部平台的权限模型、评审流程、CI/CD 集成方式，不一定能跟公司内部已有的账号体系、发布系统顺畅对接。

当这些点开始同时出现时，团队就会认真考虑：能不能在内部服务器上搭一套自己的 git 仓库服务，把中心仓库收到自己手里。这个过程就是 git 仓库本地化。

1.2 三种常见形态，看看你适合哪一种

很多朋友一听“仓库本地化”，第一反应是“在自己电脑上 git init”。这只是最轻量的形态，实际工程场景下，“本地化”通常有三层含义，需求强度从低到高：

上面表格里，第二种是当前最主流的选择：在内网部署一套 Git 服务，所有仓库的权威副本落在内网，团队通过内网进行日常 push、pull、merge、review。第三种通常是为了过渡——有些仓库还在跟外部协作者共享，没法一步切断，就先做同步镜像，等外部协作结束再彻底收编。

我这次做的，就是先从第二种形态切入，再对少量仍需跟外部联动的仓库叠加第三种方案。整体思路是：内网优先，外部按需同步。

2. 本地化方案怎么选：三条路线和各自的坑

2.1 先想清楚：你要的是“自建服务”还是“内网镜像”

自建服务和内网镜像这两个方向，经常被混在一起，但它们要解决的问题完全不同。

自建服务，是把团队日常开发的主战场搬到内网。仓库从创建、clone、push、pull、分支管理到权限控制、Webhook 触发构建，所有环节都由内网服务承担。这种方案对服务可用性要求高，因为团队所有人都依赖它。

内网镜像，则是在外部平台继续保留主仓库，内网定期拉一份完整拷贝。这种方案适合外部协作者还没有退出、或者内网环境暂时不允许直接托管的情况。镜像的诉求只有一个：数据一致，能读、能备份。

我强烈建议先定方向再选工具。如果你只是想要内网镜像，那部署一个轻量服务就够；如果你想彻底把日常开发搬进来，就要考虑高可用、权限细化、CI/CD 联动这些重活。

2.2 内网 Git 服务选型怎么看

市面上的内网 Git 托管方案不少，我整理了一个对比表，基本覆盖了主流选项：

注意上面我用方案 A/B/C 代替具体产品名，你选型的时候重点关注四个维度：

1. 资源占用能不能接受。小团队一台 4C8G 的旧服务器很常见，跑一个重量级全家桶会很吃力。
2. 权限模型够不够细。比如能不能做到“指定分支只有指定人能 push”。
3. 有没有现成的备份恢复工具。
4. 技术栈是不是团队熟悉的。选型时别只看功能列表，后续维护成本才是大头。

我这次选了方案 A。原因是团队规模不大、服务器配置有限，而且需要快速上手。方案 B 的功能确实强，但对于“先把仓库收回来”这个阶段目标来说，属于过度工程。如果团队以后要做完整的 DevOps 平台建设，再升级到方案 B 不迟。

2.3 服务器初始化的几个基本准备

选型定了之后，服务器准备是最容易翻车的一环。我用的是一台内网 Ubuntu 服务器，以下准备步骤都是实战验证过的：

# 更新系统 sudo apt update && sudo apt upgrade -y # 安装基础依赖 sudo apt install -y curl wget git vim # 创建专用系统用户 sudo adduser --system --group --home /var/lib/gitserver gituser # 创建数据目录 sudo mkdir -p /data/git-data sudo chown -R gituser:gituser /data/git-data

几个容易忽略的细节：

• 不要用 root 直接跑 Git 服务进程，单独建一个系统用户更安全，也方便后面做 SSH 权限隔离。
• 数据目录放到独立的磁盘或分区上。如果服务器只有一块系统盘，至少分一个单独目录出来，避免系统日志写满导致仓库数据异常。
• 提前规划好备份路径。我后面会把备份放在另一块内网磁盘上，目录结构上要跟数据目录分开。

提示：如果你打算用 SSH 协议访问内网仓库，需要在防火墙上放行对应端口，并确认服务器上的 SSH 服务没有端口冲突。如果系统 SSH 占用了 22 端口，Git 服务的 SSH 端口可以另设，比如 2222，但这会让 clone 地址变长，后面会专门讲这个问题。

3. 仓库迁移全流程实操：一个真实模拟项目为例

3.1 从公共平台完整备份：mirror clone

迁移仓库，第一个动作不是 git clone，而是 git clone --mirror。这个细节很关键。

普通的 git clone 只会把默认分支和远端跟踪分支拉下来，加上工作区文件。而 --mirror 模式会做一次裸仓库（bare repository）级别的完整镜像，所有分支、标签、远端引用、备注（notes）、替换对象（replacement）全部拉下来，一个都不少。

# 以模拟项目 x 为例 git clone --mirror https://external-platform.example.com/team/project-x.git # 执行后会生成 project-x.git 目录 cd project-x.git git branch -a git tag -l

执行完，检查一下分支和标签数量，确认跟源仓库一致，再往下走。如果发现分支对不上，优先排查源仓库有没有受保护分支没被镜像。镜像模式默认是包含所有 refs 的，但如果源平台设置了某些隐藏引用或受限分支，确实可能出现缺失。

3.2 在内网服务器上建立空仓库并导入

这一步先在内网 Git 服务里创建一个空仓库，名字保持跟源项目一致，然后在本机把镜像推过去。

# 在服务端手动创建仓库后，会得到一个内网地址 # 以方案 A 为例 git remote add internal http://git.internal.example.com/team/project-x.git # 或者直接用镜像推送到新仓库 git push --mirror http://git.internal.example.com/team/project-x.git

push --mirror 是“源仓库有什么，内网仓库就有什么”，包括所有分支和标签。这里有个必须要说的坑：

注意：push --mirror 是强制同步引用，内网仓库里如果已经有人建了独有分支，会被当作多余引用删掉。所以这个命令只适合在仓库刚建立、还没人开始使用的时候执行。如果内网仓库已经被团队用起来了，千万不能再用 --mirror，要改用 git push --all 和 git push --tags。

迁移完成后，在服务端看一眼分支、标签、提交记录是否完整。可以用一个小的校验脚本：

# 分别统计源镜像和内网仓库的 commit 数量 git rev-list --count --all

两边数字一致，说明数据完整搬过来了。这一步我做过很多次，是最有安全感的确认方式。

3.3 团队本地工作区如何无缝切换远程地址

仓库搬到内网之后，团队每个开发者的本地仓库 remote 都需要从外部地址切到内部地址。我在实际操作中发现，直接让所有人手动改 git remote 是不可靠的，很快会出现有人 push 到旧地址去的情况。

我采用的方式是：给团队发一个切换脚本，统一执行。

#!/bin/bash # 切换 remote 地址 for repo in $(ls -d */); do cd $repo # 备份旧的 remote 地址 OLD_URL=$(git remote get-url origin) echo "old: $OLD_URL" # 替换新地址 NEW_URL=$(echo $OLD_URL | sed 's|external-platform.example.com/team|git.internal.example.com/team|') git remote set-url origin "$NEW_URL" cd .. done

这里用 sed 做域名替换，前提是团队仓库的命名结构保持了一致性。如果旧地址和新地址路径结构差得比较大，建议写一个明文的 URL 映射表，批量映射，不要靠猜。

切换完之后，让团队成员执行下面两条命令验证：

git fetch --prune git remote show origin

第一条会从新仓库拉取所有更新并清理失效引用，第二条会显示新的 remote 地址，确认已经生效。

切换到内网后有一个体验提升非常明显：以前拉取大仓库要等半天，现在基本秒开。团队成员反馈最多的就是“终于不用挂着等 fetch 了”。

3.4 大文件和 submodule 的迁移细节

如果仓库里有大文件历史，或者用了 submodule，直接走上面流程会丢东西，需要单独处理。

大文件部分，我遇到的情况是项目里有一些编译产物和数据集体积不小。git 本身对大文件支持一般，一般会用 LFS（Large File Storage）扩展。迁移时要单独把 LFS 对象也搬走：

# 先 fetch 所有 LFS 对象 git lfs fetch --all # 在服务端仓库添加并推送所有 LFS 对象 git lfs push --all http://git.internal.example.com/team/project-x.git

千万注意，LFS 对象和 git 提交记录是两套数据。如果你只推了 git 历史，没有推 LFS 对象，团队成员克隆时会看到大量 LFS 指针文件，但实际文件拉不下来，会让人一头雾水。

submodule 的问题更隐蔽。submodule 本质上是一个指向另一个仓库提交记录的引用，每个子模块都有自己的 remote 地址。迁移主仓库只是完成了主仓库的搬迁，子模块的地址还指向旧环境，必须逐个处理。

# 更新 submodule 的远程地址 cd submodule-dir git remote set-url origin http://git.internal.example.com/team/submodule-x.git cd .. git add .gitmodules submodule-dir git commit -m "update submodule urls to internal"

如果你有很多子模块不想手动改，还有一个取巧的办法：利用 git 的 URL 重写规则，在 .gitconfig 里加一条替代规则，把旧域名整体映射到内部地址：

git config --global url."http://git.internal.example.com/team/".insteadOf "https://external-platform.example.com/team/"

这样团队开发机器上所有指向旧域名的 submodule 地址，都会自动映射到内网地址。这个技巧我强烈推荐，能省掉大量逐个修改的时间。

3.5 用自动化脚本保持与外部源同步

如果还有一部分仓库暂时需要跟外部协作者保持同步，就需要做内网镜像的自动刷新机制。

我写了一个简单的同步脚本，扔在 cron 里定时执行：

#!/bin/bash # 镜像同步脚本：从外部平台同步到内网 REPO_LIST="/data/git-data/mirror-list.txt" while read repo; do REPO_NAME=$(basename "$repo" .git) echo "=== syncing $REPO_NAME at $(date) ===" cd "/data/git-data/mirrors/$REPO_NAME.git" # 从外部源拉取 git fetch --prune origin # 推送到内网目标 git push --prune git@git.internal.example.com:team/$REPO_NAME.git "+refs/heads/*:refs/heads/*" "+refs/tags/*:refs/tags/*" done < "$REPO_LIST"

这个脚本有几个设计要点：

1. fetch 用 --prune，保证源仓库删除的分支在内网镜像也能被清除，否则垃圾分支越积越多。
2. push 时用显式的 refspec，避免 --mirror 带来的“删除内网新增分支”副作用。镜像仓库的定位是只读备份，内网这边不应该有人直接改它。
3. 同步频率根据业务需求调，一般 15 分钟到 1 小时一次足够了，不需要过分频繁。

这里要提醒一下：镜像同步只解决“数据可达”问题，不解决“协作切换”问题。如果外部平台和内网同时被开发使用，很可能出现两边并行提交、互相覆盖的情况。建议在镜像仓库上设置禁止直接 push 的权限，把它当成一个单向的只读数据源。

4. 权限、备份和日常运维：本地化之后才是开始

4.1 用户认证和权限控制怎么搭

仓库搬回内网，不等于本地化完成。日常运维里权限控制是第一个绕不过去的坎。

我按团队实际角色做了三类权限：

权限模型说起来简单，配置时有两个关键动作：

一是开启分支保护。主干分支默认不允许直接 push，所有变更必须通过合并请求（merge request / pull request）进入。这样即使用户误操作，也不会把半成品直接推到主干上。

二是明确 SSH key 的管理方式。团队成员每人生成独立的 SSH key，把公钥上传到自己的账号下，不要共用一个 key。共用 key 的问题在于出问题后无法定位是谁操作的，审计追溯非常麻烦。

# 生成专用 SSH key ssh-keygen -t ed25519 -C "name@example.com"

ed25519 比 rsa 更短更快，是当前推荐的选择。

4.2 一套够用的备份与恢复方案

备份是仓库本地化最核心的收益之一，本地化之后如果备份没跟上，反而比原来更危险——原来外部平台至少帮咱们扛着数据，现在全得自己来。

我的备份方案分三层：

第一层：git 裸仓库的定时打包。因为 git 仓库本身自带完整历史，只要把裸仓库目录完整复制走，就等于把整个版本历史备份了。

#!/bin/bash # 每天凌晨备份 BACKUP_DIR="/backup/git-repos" DATE=$(date +%Y%m%d) tar czf "$BACKUP_DIR/git-repos-$DATE.tar.gz" /data/git-data/repositories find "$BACKUP_DIR" -name "*.tar.gz" -mtime +14 -delete

第二层：服务配置和元数据备份。很多自建 Git 服务会把用户信息、仓库设置、Webhook 配置存在数据库里，这部分也要一起备份。我通常是连数据库一起导出，保证恢复出来不只是代码，连权限配置都在。

第三层：异地备份。内网服务器本地备份不算安全，如果硬盘物理损坏就全军覆没。我在另一台内网机器上挂了一个目录，每天同步备份 tar 包，相当于内网“异地”容灾。

恢复流程同样值得提前演练。我踩过一次坑：备份 tar 包打了，但从没验证过能不能解开、能不能用。真正需要恢复时才发现备份目录里有个软链接，解压出来全是空目录。

提示：备份做完一定要做恢复演练。我的做法是每两周挑一个仓库，在临时目录把 tar 解压出来，再 git clone 一次，确认能正常拉取所有分支和标签。演练过才叫备份，没演练过只能叫“心理安慰”。

4.3 Webhook、hooks 与 CI/CD 对接

仓库本地化后，原本依赖外部平台的 Webhook 触发机制要跟着一起搬。

我在实际对接中发现，Webhook 有几个非常容易踩坑的地方：

一是内网服务的地址问题。如果 CI 服务器和内网 Git 服务在同一个内网，直接填内部 IP 就可以；但如果 CI 是跑在开发机或者外部云上，就必须保证 Git 服务能被对方访问到。这里没有绝对安全的方案，我当前采用的是：让 Git 服务同时监听内网访问，CI 服务器通过内部网络调用，避免 Webhook 地址暴露到公网。

二是 Git 服务的 hooks 机制。自建服务一般都支持仓库级别的 webhook 设置，可以自定义推送、合并请求等事件的回调地址。如果你的 CI 系统不支持接收通用 Webhook，可以考虑用仓库 hooks 配合门禁脚本，限制不合规的推送。

三是分支保护策略与 CI 联动。我建议把“CI 通过才能合并”作为分支保护的强制设置，这样内网仓库的合并流程天然带质量门禁，不依赖外部平台的能力。

5. 遇到的问题和排查方法速查表

5.1 迁移阶段高频问题

5.2 内网服务运行阶段的典型故障

服务跑起来之后，阶段性的坑也不少。我挑几个最典型的：

SSH 端口冲突。内网服务器本身要开 SSH，Git 服务的 SSH 如果也绑 22 端口会直接冲突。我把 Git 服务的 SSH 端口改成了 2222，然后团队成员 clone 时要写成：

git clone ssh://git@git.internal.example.com:2222/team/project-x.git

端口写在 URI 里看着别扭，但用起来很稳定。如果想要更简洁的地址，可以通过 SSH config 配置 Host 别名，把端口、用户、key 都封装好。

# ~/.ssh/config Host git.internal HostName git.internal.example.com Port 2222 User git IdentityFile ~/.ssh/id_ed25519

这样团队可以直接git clone git.internal:team/project-x.git，看起来干净很多。

磁盘空间不足。内网仓库的运行成本和外部平台不一样，磁盘需要自己维护。我的服务器上/data分区一度被日志和大仓库写满，git push 开始报“无法写入对象”相关错误。解决方法是：把 Git 数据目录迁移到独立磁盘，加上磁盘空间监控告警，同时给常用大仓库开清理策略。

5.3 一个真实恢复案例复盘

有一次同事误操作，把一个仓库的 master 分支 force push 到了错误提交上，导致主干历史被整体改写。当时我第一反应是慌，毕竟整个团队的代码都在上面。

好在我的备份体系里有一份三小时前的裸仓库 tar 包。恢复过程如下：

1. 在临时目录解压备份：tar xzf git-repos-xxx.tar.gz
2. 进到备份仓库目录，确认目标的 ref 和提交哈希：

cd git-repos-xxx/repos/project-x.git git log --oneline -5 master

3. 直接把这个目录里的 master 分支推回线上修复版：

git push https://git.internal.example.com/team/project-x.git +BACKUP_HASH:refs/heads/master

force push 是不可逆的，但如果仓库备份是好的，它永远可逆。这次恢复全程不到十分钟，团队没有受到实质影响。事后我专门把恢复流程写成了操作手册，贴在了团队文档里。

最后再分享一个实测小技巧

仓库本地化过程中，我发现最容易被低估的事情是“仓库命名与路径规划”。刚开始我从外部平台把仓库迁回来时，直接沿用了旧的组织名和仓库名，结果过了两周就发现有些仓库归类混乱，有些同名仓库只能靠后缀区分。

建议在迁移前就规划好内网仓库的命名空间：

• 按业务线分组织，不按个人分
• 仓库名全局唯一，不要加奇怪的日期后缀
• 归档仓库和活跃仓库分开放

等仓库数量上了几十个，再想改命名，牵涉到所有开发者的 remote 地址，那成本就大了。这个教训我印象很深，希望头一次做本地化的团队能提前避开。

git 仓库本地化不是一锤子买卖，它是一次把代码资产、协作流程、权限边界、灾难恢复全部收编到自己手里的系统工程。跑通流程之后，团队对代码资产的掌控感会完全不同。如果你也在做或者准备做这件事，希望这篇里写的步骤和坑，能帮你少走一段弯路。