批量迁移 GitLab 仓库到 Forgejo：从规划到落地的完整指南

随着开源生态的多元化发展，企业或开发者团队可能因功能需求、成本控制或自托管需求，需要将代码仓库从 GitLab 迁移至 Forgejo（一款基于 Gitea 的轻量级 Git 托管平台）。对于拥有数十甚至上百个仓库的团队而言，批量迁移的效率和准确性至关重要。本文将结合技术实践与工具链，系统阐述如何高效、安全地完成 GitLab 到 Forgejo 的批量迁移。

一、迁移前的核心准备：需求分析与工具选型

1.1 明确迁移目标与约束条件

迁移前需回答三个关键问题：

• 迁移范围：是否包含所有仓库（公开/私有）？是否需要过滤特定分支或标签？
• 数据完整性：是否需要同步 Issues、Pull Requests、Wiki 等元数据？
• 停机时间：能否接受业务中断？或需实现零停机迁移？

例如，若团队依赖 GitLab 的 CI/CD 流水线，需提前规划 Forgejo 的集成方案；若需保留历史讨论记录，则需选择支持元数据迁移的工具。

1.2 工具链选型：开源工具 vs 自定义脚本

• 开源工具推荐：
  • gitlab-backup + gitea-converter：GitLab 官方备份工具结合 Gitea 社区提供的转换脚本，适合标准仓库迁移。
  • go-git-migrate：支持多仓库批量迁移的 Go 语言工具，可自定义过滤规则。
• 自定义脚本场景：当需处理复杂权限（如 LDAP 集成）、自定义钩子或非标准数据时，可通过 GitLab API 和 Forgejo REST API 编写 Python/Bash 脚本。

二、批量导出 GitLab 仓库：数据采集与清洗

2.1 使用 GitLab API 批量获取仓库列表

通过 curl 或 Python 的 requests 库调用 GitLab API（v4）：

import requests
GITLAB_URL = "https://gitlab.example.com/api/v4"
PRIVATE_TOKEN = "your_access_token"
def get_projects(page=1):
    url = f"{GITLAB_URL}/projects?per_page=100&page={page}"
    response = requests.get(url, headers={"PRIVATE-TOKEN": PRIVATE_TOKEN})
    return response.json()
projects = []
page = 1
while True:
    data = get_projects(page)
    if not data:
        break
    projects.extend(data)
    page += 1

此脚本可获取所有仓库的元数据（名称、路径、权限等），为后续筛选提供基础。

2.2 批量克隆仓库：裸仓库 vs 完整克隆

• 裸仓库克隆（仅代码）：

  mkdir gitlab-repos && cd gitlab-repos
  for repo in $(cat ../repo_list.txt); do
    git clone --bare https://gitlab.example.com/$repo.git
  done

• 完整克隆（含 Git LFS 文件）：
  需先配置 Git LFS，并在克隆时添加 --recurse-submodules 参数。

2.3 导出元数据（可选）

若需迁移 Issues、MR 等，可使用 gitlab-exporter 工具：

gitlab-exporter --url https://gitlab.example.com --token YOUR_TOKEN --projects all --output issues.json

三、Forgejo 环境准备：配置与权限映射

3.1 Forgejo 实例部署

• 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

• 关键配置：
  • 在 app.ini 中设置 [repository] 路径和 [server] 域名。
  • 配置 SMTP 以启用邮件通知。

3.2 权限模型映射

GitLab 的权限（Guest、Reporter、Developer 等）需映射到 Forgejo 的角色：
| GitLab 角色 | Forgejo 角色 | 对应权限 |
|——————-|——————-|————-|
| Guest | Guest | 只读访问 |
| Reporter | Reader | 可创建 Issue |
| Developer | Writer | 可推送代码 |
| Maintainer | Admin | 可管理仓库 |

通过 Forgejo 的 org 和 team 功能批量分配权限。

四、批量导入 Forgejo：自动化与验证

4.1 使用 gitea-admin 批量创建仓库

Forgejo（基于 Gitea）提供 gitea-admin 命令行工具：

# 从 CSV 文件批量创建仓库
cat repos.csv | while read name owner; do
  gitea-admin create-repo --name "$name" --owner "$owner"
done

4.2 推送裸仓库至 Forgejo

假设已克隆所有裸仓库至 /gitlab-repos：

FORGEJO_URL="ssh://git@forgejo.example.com:2222"
for repo in /gitlab-repos/*; do
  repo_name=$(basename $repo .git)
  cd $repo && git push --mirror $FORGEJO_URL/$(whoami)/$repo_name
done

4.3 验证迁移结果

• 代码完整性：

  git log --all --oneline  # 检查提交历史是否完整
  git lfs ls-files         # 验证 LFS 文件

• 元数据验证：对比 GitLab 和 Forgejo 的 Issue 数量、标签等。

五、迁移后优化：CI/CD 与钩子配置

5.1 迁移 GitLab CI 到 Forgejo

Forgejo 支持通过 Drone CI 或 Woodpecker CI（原 Gitea CI）实现自动化构建。示例 .drone.yml：

kind: pipeline
type: docker
name: default
steps:
- name: build
  image: alpine
  commands:
    - echo "Building..."

5.2 配置 Webhook 与通知

在 Forgejo 仓库的 Settings > Webhooks 中添加：

• Push 事件：触发 CI 构建。
• Issue 事件：集成 Slack/Discord 通知。

六、常见问题与解决方案

6.1 迁移大型仓库超时

• 分批迁移：按项目组或时间范围拆分。
• 增加 Git 缓冲区：

  git config --global http.postBuffer 524288000  # 500MB

6.2 权限不一致

• 脚本修正：通过 Forgejo API 批量调整权限：

  for user, role in permissions.items():
      requests.put(f"{FORGEJO_API}/repos/{repo}/members/{user}", json={"role": role})

七、总结与最佳实践

1. 先小规模测试：选择 1-2 个仓库验证流程。
2. 自动化优先：减少人工操作误差。
3. 备份数据：迁移前备份 GitLab 和 Forgejo 数据。
4. 文档化流程：记录每一步的命令和配置。

通过系统化的批量迁移策略，团队可在数小时内完成从 GitLab 到 Forgejo 的平滑过渡，同时确保代码、权限和协作流程的连续性。