一、迁移背景与核心挑战

随着开源技术生态的演进，Forgejo作为GitLab的轻量化替代方案，凭借其自托管、低资源消耗和高度可定制的特性，逐渐成为中小企业和开发者团队的首选。然而，从GitLab到Forgejo的迁移并非简单复制，尤其是涉及数十甚至上百个仓库时，需解决三大核心问题：

1. 数据完整性：确保代码、分支、标签、提交历史等元数据无损迁移；
2. 权限一致性：维持开发者、团队、项目的权限层级；
3. 自动化效率：避免逐个仓库手动操作，降低时间成本与人为错误。

二、迁移前准备：环境与工具配置

1. 环境要求

• Forgejo部署：需提前完成Forgejo实例的搭建（建议使用Docker或Kubernetes部署），并确保存储空间充足。
• GitLab访问权限：获取GitLab的API Token（需包含read_repository和read_api权限），用于批量拉取仓库信息。
• 网络连通性：GitLab与Forgejo服务器需处于同一网络或可通过公网访问。

2. 工具选择

• Git命令行：基础迁移工具，适用于简单场景；
• 自定义脚本：结合git clone --mirror、curl和Forgejo API，实现全自动化；
• 第三方工具：如gitea-migrator（需验证兼容性），但可能缺乏灵活性。

推荐方案：编写Python脚本，利用GitLab和Forgejo的REST API，结合Git命令实现批量操作。

三、批量迁移核心步骤

1. 提取GitLab仓库列表

通过GitLab API获取所有仓库的URL、名称和权限信息：

import requests
GITLAB_URL = "https://gitlab.example.com/api/v4/projects"
TOKEN = "your_gitlab_token"
headers = {"PRIVATE-TOKEN": TOKEN}
params = {"per_page": 100}  # 分页参数
response = requests.get(GITLAB_URL, headers=headers, params=params)
projects = response.json()
# 提取关键信息
repo_list = [{"name": p["name"], "ssh_url": p["ssh_url_to_repo"]} for p in projects]

2. 镜像化克隆仓库

使用git clone --mirror创建裸仓库，保留所有引用（分支、标签等）：

for repo in repo_list:
    git clone --mirror ${repo["ssh_url"]} /tmp/${repo["name"]}.git
done

优势：镜像克隆比普通克隆更快，且不包含工作目录，适合批量处理。

3. 创建Forgejo仓库并推送

通过Forgejo API批量创建仓库，并推送本地镜像：

FORGEJO_URL = "https://forgejo.example.com/api/v1/admin/users/your_user/repos"
FORGEJO_TOKEN = "your_forgejo_token"
for repo in repo_list:
    # 创建仓库（需Forgejo管理员权限）
    create_data = {"name": repo["name"], "private": True}
    create_resp = requests.post(
        FORGEJO_URL,
        headers={"Authorization": f"token {FORGEJO_TOKEN}"},
        json=create_data
    )
    # 推送镜像
    repo_path = f"/tmp/{repo['name']}.git"
    os.chdir(repo_path)
    os.system(f"git remote add forgejo https://forgejo.example.com/your_user/{repo['name']}.git")
    os.system("git push --mirror forgejo")

4. 权限映射与团队同步

Forgejo的权限模型与GitLab存在差异，需手动或通过脚本映射：

• 用户映射：创建Forgejo用户并匹配GitLab用户名；
• 团队同步：通过API将GitLab的群组和权限复制到Forgejo。

示例脚本片段：

# 假设已获取GitLab团队数据
for team in gitlab_teams:
    forgejo_team_data = {
        "name": team["name"],
        "permission": "write"  # 根据GitLab权限调整
    }
    requests.post(
        "https://forgejo.example.com/api/v1/teams",
        headers={"Authorization": f"token {FORGEJO_TOKEN}"},
        json=forgejo_team_data
    )

四、验证与回滚机制

1. 数据完整性验证

• 提交哈希比对：随机抽查仓库的最新提交哈希是否一致；
• 分支列表对比：使用git branch -a验证分支数量。

2. 回滚方案

• 备份原仓库：迁移前对GitLab仓库进行快照；
• 增量同步：若迁移失败，可通过git fetch和git merge同步差异。

五、优化与扩展建议

1. 并行处理：使用多线程或异步IO加速大规模迁移；
2. 日志记录：详细记录每个仓库的迁移状态和错误信息；
3. CI/CD集成：将迁移脚本纳入CI流水线，实现自动化触发。

六、常见问题与解决方案

• Q：迁移后Webhook失效
  A：需在Forgejo中重新配置Webhook，并更新触发URL。

• Q：大仓库迁移超时
  A：调整Git的http.postBuffer参数（git config --global http.postBuffer 524288000）。

• Q：权限未正确继承
  A：检查Forgejo的团队命名是否与GitLab完全一致，并验证API调用是否成功。

七、总结与展望

批量迁移GitLab仓库到Forgejo的核心在于自动化与验证。通过结合API调用和Git命令，可实现高效、可靠的数据迁移。未来，随着Forgejo生态的完善，可进一步探索与ArgoCD、Jenkins等工具的集成，构建更灵活的DevOps流程。

关键收获：

• 迁移前需充分测试，优先处理小规模仓库；
• 权限映射是易错点，需双人复核；
• 自动化脚本应具备容错机制，避免中断导致数据丢失。