一、背景与需求分析

在分布式开发场景中，企业常面临多代码托管平台共存的情况。例如，内部研发使用Gitea（轻量级、自托管），而部分项目需同步至GitLab（集成CI/CD、社区生态）。此时，镜像仓库功能可实现代码、Issue、PR的双向同步，避免手动维护多套仓库。典型需求包括：

1. 代码一致性：确保Gitea和GitLab仓库的分支、标签、提交历史完全一致。
2. 权限映射：将Gitea用户权限映射至GitLab，避免权限混乱。
3. 自动化同步：通过Webhook或定时任务触发同步，减少人工干预。
4. 冲突处理：解决因网络中断或并发修改导致的同步冲突。

二、Gitea添加GitLab镜像仓库的配置步骤

1. 准备工作

• Gitea版本要求：建议使用Gitea 1.16+（支持更完善的镜像仓库API）。
• GitLab访问权限：需在GitLab中生成Personal Access Token（权限需包含read_repository、write_repository）。
• 网络连通性：确保Gitea服务器可访问GitLab的API端点（如https://gitlab.example.com/api/v4）。

2. 在Gitea中配置镜像仓库

步骤1：创建镜像仓库

1. 登录Gitea管理后台，进入仓库设置 > 镜像仓库。
2. 填写GitLab仓库的URL（如https://gitlab.example.com/user/repo.git）。
3. 选择认证方式：
   • HTTP Basic Auth：输入GitLab用户名和Personal Access Token。
   • SSH Key：需提前将Gitea服务器的SSH公钥添加至GitLab的Deploy Keys。

步骤2：配置同步规则

• 同步方向：
  • 单向同步（Gitea → GitLab）：适用于仅需备份至GitLab的场景。
  • 双向同步：需启用Enable Mirror Sync并配置冲突解决策略（如“Gitea优先”或“GitLab优先”）。
• 同步触发方式：
  • 手动触发：通过Gitea的Web界面点击“同步”按钮。
  • 自动触发：配置GitLab的Webhook，在代码推送时调用Gitea的API（需Gitea开启ENABLE_PUSH_MIRROR）。

示例配置（YAML格式）

# Gitea配置文件（app.ini）中的镜像仓库相关设置
[mirror]
DEFAULT_INTERVAL = 3600  # 默认同步间隔（秒）
ENABLE_PUSH_MIRROR = true  # 允许通过Webhook触发同步

3. 权限管理与用户映射

用户映射策略

• 直接映射：Gitea和GitLab用户同名时自动关联。
• 自定义映射：在Gitea的custom/conf/app.ini中配置：

  [mirror.usermap]
  GITEA_USER1 = GITLAB_USER1
  GITEA_USER2 = GITLAB_USER2

• 匿名访问：若GitLab仓库公开，可配置MIRROR_ANONYMOUS_ACCESS = true。

权限同步

• 分支保护：Gitea中保护的分支会同步至GitLab的“Protected Branches”。
• PR/MR同步：需在Gitea中启用SYNC_PULL_REQUESTS，并确保GitLab的API支持MR创建。

三、GitLab镜像仓库同步至Gitea

1. 反向同步配置

若需将GitLab作为主仓库，同步至Gitea：

1. 在GitLab中配置Outbound Webhook，指向Gitea的API端点（如https://gitea.example.com/api/v1/repos/user/repo/mirrors）。
2. 在Gitea中启用PULL_MIRROR功能，并配置认证信息。

2. 同步冲突处理

常见冲突场景

• 同时修改：Gitea和GitLab对同一文件进行不同修改。
• 分支删除：Gitea中删除的分支在GitLab中仍存在。
• 权限变更：用户权限在两侧平台不一致。

解决方案

• 冲突检测：Gitea 1.18+支持同步前检测冲突，通过邮件通知管理员。
• 手动合并：冲突时暂停自动同步，由管理员手动解决后重启同步。
• 版本回滚：保留同步日志，支持回滚至指定提交。

四、性能优化与监控

1. 同步性能优化

• 增量同步：启用INCREMENTAL_SYNC，仅同步变更部分。
• 并行同步：对大型仓库，可拆分同步任务（如按分支并行）。
• 缓存机制：使用Redis缓存GitLab的元数据，减少API调用。

2. 监控与日志

• 同步日志：Gitea会记录每次同步的详细日志（路径：/data/gitea/log/mirror.log）。
• Prometheus监控：通过Gitea的Exporter暴露同步指标（如gitea_mirror_sync_duration_seconds）。
• 告警规则：配置同步失败时触发告警（如“连续3次同步失败”）。

五、常见问题与解决方案

1. 同步失败：认证错误

• 原因：Personal Access Token过期或权限不足。
• 解决：重新生成Token，确保包含api和repository权限。

2. 同步延迟：网络问题

• 原因：Gitea服务器与GitLab之间网络延迟高。
• 解决：
  • 使用CDN加速GitLab API访问。
  • 调整同步间隔（如从1小时改为30分钟）。

3. 权限不同步

• 原因：用户映射配置错误或GitLab API限制。
• 解决：
  • 检查mirror.usermap配置。
  • 确保GitLab用户未被禁用。

六、最佳实践建议

1. 分阶段同步：先同步测试仓库，验证无误后再同步生产仓库。
2. 备份策略：同步前备份Gitea和GitLab的仓库数据。
3. 文档化流程：编写《镜像仓库同步SOP》，明确责任人及操作步骤。
4. 定期审计：每月检查同步日志，清理无效的镜像配置。

通过以上配置与优化，Gitea与GitLab的镜像仓库同步可实现高效、稳定的跨平台协作，显著提升开发效率并降低维护成本。