multi repo support

2025-11-22 17:31:53 +08:00
parent 79e949f4c3
commit b5552d7ffe
7 changed files with 673 additions and 77 deletions
--- a/README.md
+++ b/README.md
@@ -1,113 +1,151 @@
 # 多仓库同步系统

-这是一个支持批量同步多个 Git 仓库的自动化流水线系统，适用于从上游仓库同步代码到目标 Gitea 仓库。
+这是一个支持多方向、多仓库批量同步的自动化流水线系统，适用于在不同 Git 服务器之间同步代码的场景。

 ## 🚀 功能特性

- **批量同步**：通过配置文件一次性管理多个仓库同步
+- **多方向同步**：支持 A→B, B→C, A→C 等多种同步方向
+- **独立配置**：每个同步方向使用单独的配置文件和流水线
+- **环境隔离**：每个方向使用不同的环境变量前缀，安全性更高
+- **批量同步**：每个方向可以通过配置文件管理多个仓库
+- **灵活调度**：每个方向可以配置不同的定时任务
+- **手动触发**：支持手动触发单个方向的同步
+- **详细日志**：提供每个仓库同步过程的详细日志
 - **冲突自动处理**：使用 `reset --hard` 策略，确保目标仓库完全同步为上游状态
- **定时执行**：支持定时任务（每天凌晨1点自动执行）
- **手动触发**：支持手动触发和配置文件更新时自动触发
- **详细日志**：提供每个仓库同步过程的详细日志和总结报告
- **安全可靠**：内置超时机制和错误处理

 ## 📁 项目结构

 ```
-.
-├── repos.yaml                       # 仓库同步配置文件
+code-sync-project/
 ├── .gitea/
 │   └── workflows/
-│       └── multi-repo-sync.yml      # 同步流水线定义
-└── README.md                        # 本文档
+│       ├── sync_A_to_B.yml    # A→B 同步流水线
+│       └── sync_B_to_C.yml    # B→C 同步流水线
+├── configs/
+│   ├── A_to_B.yaml           # A→B 同步配置
+│   └── B_to_C.yaml           # B→C 同步配置
+├── scripts/
+│   └── sync_tool.py          # 核心同步工具（支持动态环境变量前缀）
+├── repos.yaml                # 旧版单配置文件（向后兼容）
+├── sync_repos.py             # 旧版同步脚本（向后兼容）
+└── README.md                 # 本文档
 ```

-**注意：** Gitea Actions 支持两种工作流路径：
- `.gitea/workflows/` （官方推荐）
- `.github/workflows/` （兼容性支持）
-
 ## 🔧 配置说明

-### 1. 配置文件 (repos.yaml)
+### 1. 配置 Secrets

-在项目根目录的 `repos.yaml` 文件中定义需要同步的仓库：
+在 Gitea 仓库的 **Settings > Secrets** 中配置以下变量：
+
+#### 对于 A→B 同步：
+```bash
+SYNC_A_B_USERNAME=your_username      # 源A的用户名
+SYNC_A_B_TOKEN=your_token            # 源A的访问令牌
+```
+
+#### 对于 B→C 同步：
+```bash
+SYNC_B_C_USERNAME=your_username      # 源B的用户名
+SYNC_B_C_TOKEN=your_token            # 源B的访问令牌
+```
+
+**注意**：每个同步方向使用不同的环境变量前缀，确保安全性。
+
+### 2. 配置同步任务
+
+编辑 `configs/A_to_B.yaml`：

 ```yaml
-# 多仓库同步配置文件
-# 定义需要同步的仓库对，源仓库 -> 目标仓库
+name: "A_to_B_Sync"  # 同步任务名称
+
 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: "bladex-tool"
+    source_url: "https://${USERNAME}:${TOKEN}@center.javablade.com/blade/BladeX-Tool.git"
+    target_url: "https://${USERNAME}:${TOKEN}@gitea.fjy8018.top/BladeX/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"
+  # 添加更多仓库...
+```

-  # 添加更多仓库同步配置...
+编辑 `configs/B_to_C.yaml`：
+
+```yaml
+name: "B_to_C_Sync"  # 同步任务名称
+
+repositories:
+  - name: "bladex-tool"
+    source_url: "https://${USERNAME}:${TOKEN}@gitea.fjy8018.top/BladeX/BladeX-Tool.git"
+    target_url: "https://${USERNAME}:${TOKEN}@backup.example.com/backup/BladeX-Tool.git"
+    branch: "master"
+
+  # 添加更多仓库...
 ```

 **配置字段说明：**

 | 字段 | 必填 | 说明 |
 |------|------|------|
-| `name` | 是 | 仓库标识名称，用于日志输出 |
-| `source_url` | 是 | 上游仓库地址，支持环境变量 |
-| `target_url` | 是 | 目标 Gitea 仓库地址，支持环境变量 |
-| `branch` | 否 | 要同步的分支，默认为 `master` |
+| `name` | 是 | 同步任务名称，用于日志输出 |
+| `repositories[].name` | 是 | 仓库标识名称 |
+| `repositories[].source_url` | 是 | 上游仓库地址，使用 `${USERNAME}:${TOKEN}` 格式 |
+| `repositories[].target_url` | 是 | 目标仓库地址，使用 `${USERNAME}:${TOKEN}` 格式 |
+| `repositories[].branch` | 否 | 要同步的分支，默认为 `master` |

-### 2. 环境变量
+### 3. 定时任务

-在 Gitea 仓库的 **Settings > Secrets** 中配置以下变量：
+A→B：每天凌晨 2 点执行（`.gitea/workflows/sync_A_to_B.yml`）
+```yaml
+schedule:
+  - cron: '0 2 * * *'
+```

-| 变量名 | 必填 | 说明 |
-|--------|------|------|
-| `UPSTREAM_USERNAME` | 是 | 上游仓库用户名 |
-| `UPSTREAM_TOKEN` | 是 | 上游仓库访问令牌/密码 |
-| `TARGET_USERNAME` | 是 | 目标 Gitea 用户名 |
-| `TARGET_TOKEN` | 是 | 目标 Gitea 访问令牌 |
+B→C：每天凌晨 3 点执行（`.gitea/workflows/sync_B_to_C.yml`）
+```yaml
+schedule:
+  - cron: '0 3 * * *'
+```

-**注意：** 变量名不能以 `GITEA_` 或 `GITHUB_` 开头（这些是系统保留前缀），建议使用 `TARGET_` 或 `UPSTREAM_` 等前缀区分不同仓库的凭证。
-
-**安全建议：** 使用 Personal Access Token (PAT) 而不是密码，以提高安全性。
+可以在对应的 workflow 文件中修改 cron 表达式。

 ## 🚀 使用方法

-### 方法 1：手动触发
+### 方法 1：自动触发

-进入 Gitea 仓库页面的 **Actions** 标签页，选择 "多仓库同步流水线"，点击 **Run workflow** 手动执行。
+当满足以下条件之一时自动触发：

-### 方法 2：定时任务
+- 定时任务到达设定时间
+- 修改了对应的配置文件
+- 修改了对应的流水线文件
+- 修改了核心脚本 `sync_tool.py`

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

-```yaml
-schedule:
-  - cron: '0 1 * * *'  # 每天凌晨1点执行
-```
+进入 Gitea 仓库页面的 **Actions** 标签页：

-### 方法 3：配置文件更新时自动触发
-
-当修改 `repos.yaml` 或工作流文件时，会自动触发同步。
+1. 选择 "同步 A → B" 或 "同步 B → C"
+2. 点击 **Run workflow**
+3. 查看执行日志

 ## 📊 执行结果

-执行成功后，可以在 Gitea Actions 页面查看：
+执行后，Actions 页面会显示：

- 每个仓库的同步状态（成功/失败）
- 详细的同步日志
- 同步完成总结报告
-
-示例输出：
 ```
+================================================================================
+多仓库同步工具
+================================================================================
+
+开始时间: 2025-11-22 10:00:00
+配置文件: configs/A_to_B.yaml
+环境前缀: SYNC_A_B
+✓ 配置任务: A_to_B_Sync
+✓ 找到 2 个仓库配置
+
+[1/2] 正在同步...
 ============================================================
 开始同步仓库: bladex-tool
-源地址: center.javablade.com/blade/BladeX-Tool.git
-目标地址: gitea.fjy8018.top/home/BladeX-Tool.git
+源地址: ***:***@center.javablade.com/blade/BladeX-Tool.git
+目标地址: ***:***@gitea.fjy8018.top/BladeX/BladeX-Tool.git
 分支: master
 ============================================================

@@ -115,16 +153,103 @@ schedule:
 [2/6] 添加上游远程...
 [3/6] 获取上游更改...
 [4/6] 检查分支...
-[5/6] 同步到上游分支...
+[5/6] 同步到上游分支 (使用 reset --hard)...
 [6/6] 推送到目标仓库...
 ✅ [bladex-tool] 同步成功!
+
+================================================================================
+同步完成报告
+================================================================================
+✅ 成功 bladex-tool
+✅ 成功 another-repo
+
+总计: 2 个仓库
+成功: 2 个
+失败: 0 个
+
+✅ 所有仓库同步成功!
+
+结束时间: 2025-11-22 10:05:00
+```
+
+## 🔧 添加新的同步方向
+
+要添加新的同步方向（例如 A→C）：
+
+### 步骤 1：创建配置文件
+
+```bash
+cp configs/A_to_B.yaml configs/A_to_C.yaml
+```
+
+编辑 `configs/A_to_C.yaml`：
+
+```yaml
+name: "A_to_C_Sync"
+
+repositories:
+  - name: "bladex-tool"
+    source_url: "https://${USERNAME}:${TOKEN}@center.javablade.com/blade/BladeX-Tool.git"
+    target_url: "https://${USERNAME}:${TOKEN}@backup.example.com/backup/BladeX-Tool.git"
+    branch: "master"
+```
+
+### 步骤 2：创建流水线
+
+```bash
+cp .gitea/workflows/sync_A_to_B.yml .gitea/workflows/sync_A_to_C.yml
+```
+
+编辑 `.gitea/workflows/sync_A_to_C.yml`：
+
+```yaml
+name: "同步 A → C"
+
+env:
+  CONFIG_FILE: 'configs/A_to_C.yaml'
+
+# ... 其他配置 ...
+
+    - name: 执行同步 A → C
+      env:
+        SYNC_A_C_USERNAME: ${{ secrets.SYNC_A_C_USERNAME }}
+        SYNC_A_C_TOKEN: ${{ secrets.SYNC_A_C_TOKEN }}
+      run: |
+        python3 scripts/sync_tool.py ${{ env.CONFIG_FILE }} --env-prefix SYNC_A_C
+```
+
+### 步骤 3：配置 Secrets
+
+在 Gitea 中配置：
+- `SYNC_A_C_USERNAME`
+- `SYNC_A_C_TOKEN`
+
+### 步骤 4：提交并推送
+
+```bash
+git add configs/A_to_C.yaml .gitea/workflows/sync_A_to_C.yml
+git commit -m "添加 A→C 同步方向"
+git push
+```
+
+## 🛠️ 本地测试
+
+在本地测试同步：
+
+```bash
+# 设置环境变量
+export SYNC_A_B_USERNAME="your_username"
+export SYNC_A_B_TOKEN="your_token"
+
+# 运行同步
+python3 scripts/sync_tool.py configs/A_to_B.yaml --env-prefix SYNC_A_B
 ```

 ## ⚠️ 重要说明

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

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

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

@@ -144,32 +269,50 @@ schedule:
 ### 问题：仓库不存在

 **解决方案**：
- 在目标 Gitea 上预先创建空仓库
+- 在目标服务器上预先创建空仓库
 - 检查配置文件中的仓库地址是否正确

 ### 问题：同步超时

 **解决方案**：
- 在 `.gitea/workflows/multi-repo-sync.yml` 中增加超时时间
- 对于大仓库，考虑使用浅克隆（已优化为 bare clone）
+- 在 workflow 文件中增加超时时间
+- 检查网络连接是否稳定

-### 问题：配置文件解析错误
+### 问题：环境变量未设置

 **解决方案**：
- 使用 YAML 格式验证工具检查 repos.yaml
- 确保所有必要字段都已填写
+- 检查是否在 Gitea Secrets 中配置了对应的变量
+- 检查环境变量前缀是否与配置文件中的一致
+- 查看日志中的环境变量检查输出

-## 📝 最佳实践
+## 📖 最佳实践

-1. **逐步添加仓库**：初次使用时，先配置 1-2 个仓库测试
-2. **使用变量**：将敏感信息和可变信息放在 Secrets 中
-3. **监控执行**：定期检查流水线执行日志
+1. **分环境配置**：不同环境（开发/测试/生产）使用不同的配置
+2. **逐步添加仓库**：初次使用时，先配置 1-2 个仓库测试
+3. **监控执行**：定期检查 Actions 执行日志
 4. **测试环境**：先在测试仓库验证同步逻辑
 5. **备份策略**：重要仓库确保有备份机制
+6. **安全隔离**：不同方向使用不同的 Token，降低风险
+
+## 🔄 向后兼容
+
+保留旧版文件以支持单配置文件场景：
+
+- `repos.yaml` - 单配置文件
+- `sync_repos.py` - 旧版同步脚本
+- `.gitea/workflows/multi-repo-sync.yml` - 旧版流水线
+
+如需使用旧版，请配置以下 Secrets：
+- `UPSTREAM_USERNAME`
+- `UPSTREAM_TOKEN`
+- `TARGET_USERNAME`
+- `TARGET_TOKEN`
+
+**建议**：新项目使用新版多配置文件架构。

 ## 🤝 贡献

-欢迎提交 Issue 和 Pull Request 来改进此项目。
+欢迎提交 Issue 和 Pull Request 来改进这个工具！

 ## 📄 许可证