326 lines
9.0 KiB
Markdown
326 lines
9.0 KiB
Markdown
# 多仓库同步系统
|
||
|
||
这是一个支持多方向、多仓库批量同步的自动化流水线系统，适用于在不同 Git 服务器之间同步代码的场景。
|
||
|
||
## 🚀 功能特性
|
||
|
||
- **多方向同步**：支持 A→B, B→C, A→C 等多种同步方向
|
||
- **独立配置**：每个同步方向使用单独的配置文件和流水线
|
||
- **环境隔离**：每个方向使用不同的环境变量前缀，安全性更高
|
||
- **批量同步**：每个方向可以通过配置文件管理多个仓库
|
||
- **灵活调度**：每个方向可以配置不同的定时任务
|
||
- **手动触发**：支持手动触发单个方向的同步
|
||
- **详细日志**：提供每个仓库同步过程的详细日志
|
||
- **冲突自动处理**：使用 `reset --hard` 策略，确保目标仓库完全同步为上游状态
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
code-sync-project/
|
||
├── .gitea/
|
||
│ └── workflows/
|
||
│ ├── 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 # 本文档
|
||
```
|
||
|
||
## 🔧 配置说明
|
||
|
||
### 1. 配置 Secrets
|
||
|
||
在 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:
|
||
- 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"
|
||
|
||
# 添加更多仓库...
|
||
```
|
||
|
||
编辑 `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` | 是 | 同步任务名称，用于日志输出 |
|
||
| `repositories[].name` | 是 | 仓库标识名称 |
|
||
| `repositories[].source_url` | 是 | 上游仓库地址，使用 `${USERNAME}:${TOKEN}` 格式 |
|
||
| `repositories[].target_url` | 是 | 目标仓库地址，使用 `${USERNAME}:${TOKEN}` 格式 |
|
||
| `repositories[].branch` | 否 | 要同步的分支，默认为 `master` |
|
||
|
||
### 3. 定时任务
|
||
|
||
A→B：每天凌晨 2 点执行（`.gitea/workflows/sync_A_to_B.yml`）
|
||
```yaml
|
||
schedule:
|
||
- cron: '0 2 * * *'
|
||
```
|
||
|
||
B→C：每天凌晨 3 点执行（`.gitea/workflows/sync_B_to_C.yml`）
|
||
```yaml
|
||
schedule:
|
||
- cron: '0 3 * * *'
|
||
```
|
||
|
||
可以在对应的 workflow 文件中修改 cron 表达式。
|
||
|
||
## 🚀 使用方法
|
||
|
||
### 方法 1：自动触发
|
||
|
||
当满足以下条件之一时自动触发：
|
||
|
||
- 定时任务到达设定时间
|
||
- 修改了对应的配置文件
|
||
- 修改了对应的流水线文件
|
||
- 修改了核心脚本 `sync_tool.py`
|
||
|
||
### 方法 2：手动触发
|
||
|
||
进入 Gitea 仓库页面的 **Actions** 标签页：
|
||
|
||
1. 选择 "同步 A → B" 或 "同步 B → C"
|
||
2. 点击 **Run workflow**
|
||
3. 查看执行日志
|
||
|
||
## 📊 执行结果
|
||
|
||
执行后，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/BladeX/BladeX-Tool.git
|
||
分支: master
|
||
============================================================
|
||
|
||
[1/6] 克隆目标仓库...
|
||
[2/6] 添加上游远程...
|
||
[3/6] 获取上游更改...
|
||
[4/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` 策略，确保目标仓库**完全与上游一致**。任何在目标仓库上的修改都可能被覆盖。
|
||
|
||
2. **权限要求**：提供的 Token 必须有对目标仓库的写入权限。
|
||
|
||
3. **冲突处理**：由于采用强制重置策略，不会保留目标仓库与上游的冲突修改。
|
||
|
||
4. **大仓库同步**：对于大型仓库，可能需要调整流水线超时时间。
|
||
|
||
5. **私有仓库**：需要确保 Token 具有访问私有仓库的权限。
|
||
|
||
## 🔍 故障排除
|
||
|
||
### 问题：权限被拒绝（Permission denied）
|
||
|
||
**解决方案**：
|
||
- 检查 Secrets 中的用户名和 Token 是否正确
|
||
- 确认 Token 具有 repo 范围的权限
|
||
- 验证仓库 URL 是否正确
|
||
|
||
### 问题：仓库不存在
|
||
|
||
**解决方案**：
|
||
- 在目标服务器上预先创建空仓库
|
||
- 检查配置文件中的仓库地址是否正确
|
||
|
||
### 问题：同步超时
|
||
|
||
**解决方案**：
|
||
- 在 workflow 文件中增加超时时间
|
||
- 检查网络连接是否稳定
|
||
|
||
### 问题：环境变量未设置
|
||
|
||
**解决方案**：
|
||
- 检查是否在 Gitea Secrets 中配置了对应的变量
|
||
- 检查环境变量前缀是否与配置文件中的一致
|
||
- 查看日志中的环境变量检查输出
|
||
|
||
## 📖 最佳实践
|
||
|
||
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 来改进这个工具！
|
||
|
||
## 📄 许可证
|
||
|
||
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)
|