多仓库同步系统

这是一个支持批量同步多个 Git 仓库的自动化流水线系统，适用于从上游仓库同步代码到目标 Gitea 仓库。

🚀 功能特性

• 批量同步：通过配置文件一次性管理多个仓库同步
• 冲突自动处理：使用 reset --hard 策略，确保目标仓库完全同步为上游状态
• 定时执行：支持定时任务（每天凌晨1点自动执行）
• 手动触发：支持手动触发和配置文件更新时自动触发
• 详细日志：提供每个仓库同步过程的详细日志和总结报告
• 安全可靠：内置超时机制和错误处理

📁 项目结构

.
├── repos.yaml                       # 仓库同步配置文件
├── .gitea/
│   └── workflows/
│       └── multi-repo-sync.yml      # 同步流水线定义
└── README.md                        # 本文档

注意： Gitea Actions 支持两种工作流路径：

• .gitea/workflows/ （官方推荐）
• .github/workflows/ （兼容性支持）

🔧 配置说明

1. 配置文件 (repos.yaml)

在项目根目录的 repos.yaml 文件中定义需要同步的仓库：

# 多仓库同步配置文件
# 定义需要同步的仓库对，源仓库 -> 目标仓库
repositories:
  # 示例：同步 BladeX-Tool 仓库
  - name: "bladex-tool"           # 仓库名称（用于日志输出）
    source_url: "https://${UPSTREAM_USERNAME}:${UPSTREAM_TOKEN}@center.javablade.com/blade/BladeX-Tool.git"
    target_url: "https://${TARGET_USERNAME}:${TARGET_TOKEN}@gitea.fjy8018.top/home/BladeX-Tool.git"
    branch: "master"               # 要同步的分支

  # 示例：同步另一个仓库（取消注释并修改以下配置）
  - name: "another-repo"
    source_url: "https://${UPSTREAM_USERNAME}:${UPSTREAM_TOKEN}@github.com/example/repo.git"
    target_url: "https://${TARGET_USERNAME}:${TARGET_TOKEN}@gitea.fjy8018.top/home/repo.git"
    branch: "main"

  # 添加更多仓库同步配置...

配置字段说明：

字段	必填	说明
name	是	仓库标识名称，用于日志输出
source_url	是	上游仓库地址，支持环境变量
target_url	是	目标 Gitea 仓库地址，支持环境变量
branch	否	要同步的分支，默认为 master

2. 环境变量

在 Gitea 仓库的 Settings > Secrets 中配置以下变量：

变量名	必填	说明
UPSTREAM_USERNAME	是	上游仓库用户名
UPSTREAM_TOKEN	是	上游仓库访问令牌/密码
TARGET_USERNAME	是	目标 Gitea 用户名
TARGET_TOKEN	是	目标 Gitea 访问令牌

注意： 变量名不能以 GITEA_ 或 GITHUB_ 开头（这些是系统保留前缀），建议使用 TARGET_ 或 UPSTREAM_ 等前缀区分不同仓库的凭证。

安全建议： 使用 Personal Access Token (PAT) 而不是密码，以提高安全性。

🚀 使用方法

方法 1：手动触发

进入 Gitea 仓库页面的 Actions 标签页，选择 "多仓库同步流水线"，点击 Run workflow 手动执行。

方法 2：定时任务

流水线默认配置为每天凌晨 1 点（UTC）自动执行。可在 .gitea/workflows/multi-repo-sync.yml 文件中修改 cron 表达式：

schedule:
  - cron: '0 1 * * *'  # 每天凌晨1点执行

方法 3：配置文件更新时自动触发

当修改 repos.yaml 或工作流文件时，会自动触发同步。

📊 执行结果

执行成功后，可以在 Gitea Actions 页面查看：

• 每个仓库的同步状态（成功/失败）
• 详细的同步日志
• 同步完成总结报告

示例输出：

============================================================
开始同步仓库: bladex-tool
源地址: center.javablade.com/blade/BladeX-Tool.git
目标地址: gitea.fjy8018.top/home/BladeX-Tool.git
分支: master
============================================================

[1/6] 克隆目标仓库...
[2/6] 添加上游远程...
[3/6] 获取上游更改...
[4/6] 检查分支...
[5/6] 同步到上游分支...
[6/6] 推送到目标仓库...
✅ [bladex-tool] 同步成功!

⚠️ 重要说明

1. 强制同步策略：本流水线使用 git reset --hard 策略，确保目标仓库完全与上游一致。任何在目标仓库上的修改都可能被覆盖。

2. 权限要求：确保提供的 Token 具有对目标仓库的写入权限。

3. 冲突处理：由于采用强制重置策略，不会保留目标仓库与上游的冲突修改。

4. 大仓库同步：对于大型仓库，可能需要调整流水线超时时间。

5. 私有仓库：需要确保 Token 具有访问私有仓库的权限。

🔍 故障排除

问题：权限被拒绝（Permission denied）

解决方案：

• 检查 Secrets 中的用户名和 Token 是否正确
• 确认 Token 具有 repo 范围的权限
• 验证仓库 URL 是否正确

问题：仓库不存在

解决方案：

• 在目标 Gitea 上预先创建空仓库
• 检查配置文件中的仓库地址是否正确

问题：同步超时

解决方案：

• 在 .gitea/workflows/multi-repo-sync.yml 中增加超时时间
• 对于大仓库，考虑使用浅克隆（已优化为 bare clone）

问题：配置文件解析错误

解决方案：

• 使用 YAML 格式验证工具检查 repos.yaml
• 确保所有必要字段都已填写

📝 最佳实践

1. 逐步添加仓库：初次使用时，先配置 1-2 个仓库测试
2. 使用变量：将敏感信息和可变信息放在 Secrets 中
3. 监控执行：定期检查流水线执行日志
4. 测试环境：先在测试仓库验证同步逻辑
5. 备份策略：重要仓库确保有备份机制

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进此项目。

📄 许可证

MIT License

🔗 相关链接

• Gitea Actions 文档
• GitHub Actions 工作流语法
• Git 官方文档