彭河森1. 项目背景与核心需求
最近在部署一个Python项目时，突然发现从公司内网拉取GitHub仓库代码时频繁出现超时。ping了一下github.com，延迟高达800ms+，还伴随30%的丢包率。这让我意识到：是时候给项目找个"备胎"了。
国内开发者对这种情况应该不陌生。当GitHub访问不稳定时，我们需要快速将代码库迁移到Gitee、GitCode等国内平台。但迁移不只是简单的git remote set-url，还要考虑：
- 历史提交记录的完整性保留
- CI/CD流程的无缝衔接
- 团队协作的平滑过渡
- 子模块/依赖项的同步处理
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 迁移方案设计与对比
2.1 主流国内代码托管平台选型
| 平台 | 免费私有库 | 单仓库大小限制 | CI/CD支持 | 特色功能 |
|---|---|---|---|---|
| Gitee | ✓ | 1GB | ✓ | 企业版SSO集成 |
| GitCode | ✓ | 500MB | ✓ | 原生支持Git LFS |
| Coding | × | 2GB | ✓ | 腾讯云生态集成 |
提示：选择平台时建议检查其开放API是否满足你的自动化需求。比如Gitee的API速率限制是每分钟100次。
2.2 迁移路径决策树
根据项目复杂度，我总结出三种迁移策略：
-
镜像同步方案（适合长期双活）
bash复制# 在Gitee创建仓库后自动生成的命令 git remote add gitee https://gitee.com/yourname/repo.git git push gitee --all git push gitee --tags -
完整迁移方案（适合彻底切换）
bash复制# 先克隆裸仓库 git clone --bare https://github.com/yourname/repo.git cd repo.git # 推送到新平台 git push --mirror https://gitee.com/yourname/repo.git -
子模块迁移方案（适合复杂项目）
bash复制# 递归克隆原项目 git clone --recursive https://github.com/yourname/repo.git # 修改.gitmodules文件中的URL sed -i 's/github.com/gitee.com/g' .gitmodules # 同步子模块 git submodule sync git submodule update --init --recursive
3. 完整迁移实操手册
3.1 前置检查清单
-
检查仓库体积：
bash复制
git count-objects -vH如果超过500MB，建议先使用
git gc清理 -
确认敏感信息：
bash复制
git secrets --scan-history -
备份现有远程配置：
bash复制
git remote -v > remote_backup.txt
3.2 分步迁移流程
步骤1：在Gitee创建空白仓库
- 不要初始化README/.gitignore
- 选择与GitHub相同的可见性设置
步骤2：本地仓库准备
bash复制# 添加新remote
git remote add gitee https://gitee.com/yourname/repo.git
# 测试连接
git ls-remote gitee
步骤3：完整推送
bash复制# 推送所有分支
git push gitee --all
# 推送所有标签
git push gitee --tags
# 如果有LFS文件
git lfs push gitee --all
步骤4：验证完整性
bash复制# 对比commit数
git rev-list --count HEAD
git rev-list --count gitee/main
# 对比文件哈希
git ls-tree -r HEAD | shasum
git ls-tree -r gitee/main | shasum
4. CI/CD适配改造
4.1 GitHub Actions迁移示例
原.github/workflows/build.yml：
yaml复制steps:
- uses: actions/checkout@v3
with:
repository: 'github.com/yourname/repo'
修改为：
yaml复制steps:
- uses: actions/checkout@v3
with:
repository: 'gitee.com/yourname/repo'
token: ${{ secrets.GITEE_TOKEN }} # 需要在Settings中配置
4.2 自建Runner网络配置
如果使用自托管Runner，需要确保：
bash复制# 测试网络连通性
telnet gitee.com 443
# 如果使用SSH协议
ssh -T git@gitee.com
5. 常见问题排雷指南
5.1 认证失败问题
现象：
code复制remote: [session-a1b2c3d4] Access denied
fatal: unable to access 'https://gitee.com/.../': The requested URL returned error: 403
解决方案：
- 检查账号是否完成实名认证
- 使用SSH替代HTTPS：
bash复制
git remote set-url gitee git@gitee.com:yourname/repo.git
5.2 LFS文件丢失
现象：
推送成功但拉取时提示LFS对象缺失
修复步骤：
bash复制# 重新上传LFS对象
git lfs push --all gitee
# 或者从原仓库迁移
git lfs fetch origin
git lfs push gitee
5.3 子模块路径错误
现象：
子模块更新失败，提示找不到仓库
解决方法：
- 手动修改
.gitmodules：ini复制[submodule "libs/foo"] path = libs/foo url = https://gitee.com/original_user/foo.git - 执行：
bash复制git submodule sync rm -rf libs/foo git submodule update --init
6. 迁移后优化建议
-
自动同步机制（适合过渡期）：
bash复制# 设置cron任务每周同步 0 3 * * 1 cd /path/to/repo && git fetch origin && git push gitee -
依赖项替换：
python复制# requirements.txt修改示例 - git+https://github.com/user/dep.git@v1.0 + git+https://gitee.com/mirror_user/dep.git@v1.0 -
文档更新提示：
markdown复制
迁移完成后，建议保持原GitHub仓库的README中放置跳转链接，至少保留6个月。对于团队项目，可以使用git config --global url."git@gitee.com:".insteadOf "https://github.com/"全局替换提高效率