init pipeline

2025-11-20 21:35:08 +08:00
commit f74f068071
4 changed files with 499 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,180 @@
+# 多仓库同步系统
+
+这是一个支持批量同步多个 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://${GITEA_USERNAME}:${GITEA_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://${GITEA_USERNAME}:${GITEA_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` | 是 | 上游仓库访问令牌/密码 |
+| `GITEA_USERNAME` | 是 | 目标 Gitea 用户名 |
+| `GITEA_TOKEN` | 是 | 目标 Gitea 访问令牌 |
+
+**注意：** 建议使用 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)