一、核心概念与需求背景

在分布式开发场景中，团队可能同时使用Gitea（轻量级自托管Git服务）与GitLab（企业级代码管理平台）进行项目托管。为避免重复维护、提升协作效率，建立镜像仓库实现代码同步成为关键需求。通过Gitea镜像GitLab仓库，开发者可在本地Gitea实例中实时获取GitLab仓库的更新，反之亦然，尤其适用于混合云架构或跨团队协作场景。

二、Gitea添加GitLab镜像仓库的完整流程

1. 基础环境准备

• 版本兼容性检查：确保Gitea版本≥1.15（支持外部仓库镜像），GitLab版本≥13.0（REST API兼容）。
• 网络连通性验证：通过curl -v https://gitlab.example.com/api/v4/projects测试Gitea服务器能否访问GitLab API。
• 权限配置：在GitLab中生成Personal Access Token（需勾选api、read_repository、write_repository权限）。

2. Gitea端镜像配置

方法一：Web界面操作

1. 登录Gitea管理后台，进入目标仓库的Settings → Mirror Settings。
2. 勾选Enable Mirroring，选择Pull或Push模式：
   • Pull模式：Gitea定期从GitLab拉取更新（适合只读镜像）。
   • Push模式：Gitea将本地变更推送到GitLab（需GitLab仓库可写）。
3. 填写GitLab仓库URL（如https://gitlab.example.com/group/project.git）及生成的Token。
4. 设置同步间隔（建议≥5分钟以避免API限流）。

方法二：命令行配置（适用于批量操作）

# 通过Gitea API创建镜像（需管理员权限）
curl -X POST -H "Authorization: token YOUR_GITEA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "interval": 300,
    "enable_pruner": false,
    "repo_id": 123,
    "mirror_repo_id": 0,
    "mirror_address": "https://gitlab.example.com/group/project.git",
    "mirror_kind": "gitlab",
    "mirror_token": "YOUR_GITLAB_TOKEN",
    "on_demand": false
  }' "http://gitea.example.com/api/v1/repos/123/mirror"

3. GitLab端配置（可选）

若需双向同步，需在GitLab中配置Gitea作为远程仓库：

cd /path/to/gitlab/repo
git remote add gitea http://gitea.example.com/user/repo.git
git config --add remote.gitea.pushurl http://gitea.example.com/user/repo.git

三、高级同步策略与优化

1. 增量同步与冲突处理

• Webhook触发：在GitLab中设置Push事件Webhook，指向Gitea的/api/v1/repos/{id}/mirror-sync接口，实现实时同步。
• 冲突解决机制：
  • 启用--force推送时，建议在Gitea中配置[mirror] DISABLE_FORCE_PUSH = false（默认禁用）。
  • 使用git merge --strategy-option theirs处理非快进合并冲突。

2. 性能优化

• 并行同步：通过Gitea的[mirror] MAX_MIRROR_WORKERS配置项（默认2）调整并发数。
• 缓存加速：在Nginx反向代理中配置GitLab API响应缓存（TTL建议10分钟）。

3. 安全加固

• IP白名单：在GitLab的Settings → Network → Outbound requests中限制仅允许Gitea服务器IP访问。
• Token轮换：每90天更新GitLab Token，并通过Gitea的/admin/mirrors接口批量更新。

四、常见问题解决方案

1. 同步失败排查

• 错误403：检查Token权限是否包含write_repository（Push模式必需）。
• 错误504：调整Gitea的[server] SSH_TIMEOUT（默认60秒）或优化网络延迟。
• 日志分析：查看Gitea的log/gitea.log中mirror标签的记录。

2. 数据一致性验证

执行以下命令检查两端仓库的HEAD提交是否一致：

# 在Gitea服务器执行
git --git-dir=/data/git/repositories/user/repo.git rev-parse HEAD
# 在GitLab服务器执行
git --git-dir=/var/opt/gitlab/git-data/repositories/user/repo.git rev-parse HEAD

五、企业级实践建议

1. 混合云架构：将Gitea部署在私有云，GitLab部署在公有云，通过镜像同步实现代码安全隔离与弹性扩展。
2. CI/CD集成：在GitLab CI中配置mirror-sync作业，确保构建产物同步至Gitea。
3. 审计追踪：通过Gitea的Audit Log与GitLab的System Hooks记录所有同步操作。

六、总结与展望

通过Gitea与GitLab的镜像仓库同步，企业可构建灵活的代码管理生态，兼顾轻量化运维与企业级功能需求。未来，随着Gitea 1.18+对GitLab EE版功能的深度支持，双向同步的稳定性与安全性将进一步提升。建议开发者定期关注Gitea官方文档的Mirror章节更新，以获取最新实践方案。