# 多仓库同步系统

这是一个支持批量同步多个 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)