183 lines
6.1 KiB
Markdown
183 lines
6.1 KiB
Markdown
# 多仓库同步系统
|
||
|
||
这是一个支持批量同步多个 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` 文件中定义需要同步的仓库：
|
||
|
||
```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 表达式：
|
||
|
||
```yaml
|
||
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 文档](https://docs.gitea.com/usage/actions/overview)
|
||
- [GitHub Actions 工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
|
||
- [Git 官方文档](https://git-scm.com/doc)
|