6.1 KiB
6.1 KiB
多仓库同步系统
这是一个支持批量同步多个 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] 同步成功!
⚠️ 重要说明
-
强制同步策略：本流水线使用
git reset --hard策略，确保目标仓库完全与上游一致。任何在目标仓库上的修改都可能被覆盖。 -
权限要求：确保提供的 Token 具有对目标仓库的写入权限。
-
冲突处理：由于采用强制重置策略，不会保留目标仓库与上游的冲突修改。
-
大仓库同步：对于大型仓库，可能需要调整流水线超时时间。
-
私有仓库：需要确保 Token 具有访问私有仓库的权限。
🔍 故障排除
问题：权限被拒绝（Permission denied）
解决方案：
- 检查 Secrets 中的用户名和 Token 是否正确
- 确认 Token 具有 repo 范围的权限
- 验证仓库 URL 是否正确
问题：仓库不存在
解决方案：
- 在目标 Gitea 上预先创建空仓库
- 检查配置文件中的仓库地址是否正确
问题：同步超时
解决方案：
- 在
.gitea/workflows/multi-repo-sync.yml中增加超时时间 - 对于大仓库，考虑使用浅克隆（已优化为 bare clone）
问题：配置文件解析错误
解决方案：
- 使用 YAML 格式验证工具检查 repos.yaml
- 确保所有必要字段都已填写
📝 最佳实践
- 逐步添加仓库：初次使用时，先配置 1-2 个仓库测试
- 使用变量：将敏感信息和可变信息放在 Secrets 中
- 监控执行：定期检查流水线执行日志
- 测试环境：先在测试仓库验证同步逻辑
- 备份策略：重要仓库确保有备份机制
🤝 贡献
欢迎提交 Issue 和 Pull Request 来改进此项目。
📄 许可证
MIT License