从GitLab到Forgejo：企业级批量迁移仓库的完整指南与最佳实践

一、迁移背景与需求分析

随着开源生态的快速发展，GitLab的社区版（CE）因功能限制逐渐无法满足企业级需求，而基于Gitea衍生的Forgejo凭借其轻量化、高可定制性和更友好的开源协议，成为众多技术团队的替代选择。批量迁移GitLab仓库到Forgejo的核心需求包括：降低维护成本（Forgejo对资源需求更低）、提升数据主权（避免商业软件锁定）、支持自定义扩展（如集成企业LDAP/OAuth2）。

典型迁移场景包括：企业将内部代码库从GitLab CE迁移至自建Forgejo实例、开源项目维护者切换代码托管平台、教育机构优化教学环境。迁移前需明确关键指标：仓库数量、分支结构复杂度、历史提交量、是否包含大型二进制文件（如LFS对象）。

二、迁移前关键准备工作

1. 环境与权限配置

• Forgejo实例准备：建议使用Linux服务器（Ubuntu 22.04 LTS推荐），配置至少4核CPU、8GB内存和SSD存储。通过Docker部署可简化环境配置：

  docker run -d --name=forgejo \
    -p 3000:3000 -p 2222:22 \
    -v /path/to/data:/data \
    -e USER_UID=1000 -e USER_GID=1000 \
    forgejo/forgejo:latest

• GitLab API权限：生成具有read_repository和read_api权限的Personal Access Token，确保能访问所有待迁移仓库。

2. 数据完整性检查

• 使用git fsck验证目标仓库是否存在损坏：

  git fsck --full

• 对LFS对象较多的仓库，提前通过git lfs ls-files统计文件数量，评估网络传输压力。

3. 迁移策略设计

• 增量迁移：适用于大型仓库，分批次迁移历史提交（如每次1000条）。
• 全量迁移：小型仓库或对一致性要求高的场景，一次性同步所有数据。
• 混合迁移：先迁移主干分支，后续通过Webhook同步增量变更。

三、核心迁移步骤详解

1. 仓库元数据提取

通过GitLab API批量获取仓库列表及元信息：

curl --header "PRIVATE-TOKEN: <your_token>" "https://gitlab.example.com/api/v4/projects?per_page=100" | jq '.[].ssh_url_to_repo' > repos.txt

使用jq工具解析JSON响应，提取SSH地址并保存至文件。

2. 仓库内容迁移

方法一：Git原生克隆与推送

while read url; do
  repo_name=$(basename "$url" .git)
  git clone --mirror "$url" "/tmp/$repo_name"
  cd "/tmp/$repo_name"
  remote_url="ssh://git@forgejo.example.com:2222/user/$repo_name.git"
  git remote set-url origin "$remote_url"
  git push --mirror
  cd ..
done < repos.txt

优势：兼容所有Git版本，支持LFS对象传输。
局限：需手动处理权限映射。

方法二：使用迁移工具（推荐）

Forgejo官方提供的migrate工具支持自动化迁移：

forgejo-admin migrate \
  --from gitlab \
  --url https://gitlab.example.com \
  --token <your_token> \
  --target-url http://forgejo.example.com:3000 \
  --users-map "gitlab_user:forgejo_user"

关键参数：

• --users-map：定义GitLab用户到Forgejo用户的映射关系。
• --skip-wiki：排除Wiki数据（如不需要）。

3. 权限与钩子迁移

• 权限映射：通过Forgejo的组织-团队模型重构GitLab的组-权限关系。
• Webhook迁移：使用curl批量注册Webhook：

  curl -X POST -H "Content-Type: application/json" \
    -d '{"url": "https://ci.example.com/hook", "events": ["push"]}' \
    "http://forgejo.example.com:3000/api/v1/repos/user/repo/hooks"

四、迁移后验证与优化

1. 数据一致性校验

• 提交哈希比对：随机抽取10%的仓库，验证GitLab与Forgejo的最新提交哈希是否一致。
• LFS对象验证：对包含LFS的仓库，执行：

  git lfs fetch --all
  git lfs checkout .

2. 性能调优

• 数据库优化：对MySQL后端，执行ANALYZE TABLE更新统计信息。
• 缓存配置：在app.ini中调整[cache]部分，启用Redis缓存：

  [cache]
  ADAPTER = redis
  HOST = redis:6379

3. 用户培训与文档

• 编制《Forgejo使用手册》，重点说明与GitLab的差异点（如Merge Request流程）。
• 提供迁移常见问题解答（FAQ），例如：
  • Q：迁移后CI/CD如何配置？
    A：通过Forgejo的Actions功能或集成外部CI工具（如Drone）。

五、常见问题解决方案

1. 大仓库迁移超时

• 现象：迁移5GB以上仓库时，Git推送中断。
• 解决：
  • 调整Git配置：git config --global http.postBuffer 524288000（500MB）。
  • 分块推送：先推送历史，再推送master分支。

2. 权限丢失

• 原因：GitLab的Deploy Keys未正确映射到Forgejo的SSH Keys。
• 解决：
  • 导出GitLab的Deploy Keys公钥。
  • 在Forgejo中为对应仓库添加相同公钥。

3. LFS对象同步失败

• 诊断：检查git lfs env输出，确认Endpoint指向正确地址。
• 修复：

  git config --global lfs.url "http://forgejo.example.com:3000/user/repo.git/info/lfs"
  git lfs pull

六、总结与长期维护建议

批量迁移GitLab仓库到Forgejo需兼顾技术实现与业务连续性。建议采用“分阶段迁移”策略：先迁移非核心仓库验证流程，再逐步推广至核心项目。迁移后需建立持续监控机制，通过Prometheus+Grafana监控Forgejo实例的CPU、内存和磁盘I/O使用率。

Forgejo的模块化设计（如支持插件扩展）使其成为GitLab的理想替代方案。通过合理规划迁移路径，企业可在3-5天内完成百级别仓库的无损迁移，同时降低30%以上的运维成本。