repo-sync（reposync-java）

跨平台仓库同步服务 —— 基于 Spring Boot 3 的 Java 重写版本，提供 GitLink 与外部平台（GitHub / Gitee / GitLab / Gitcode / osredm）之间的仓库自动同步能力。

原架构中同步职责拆分在 forgeplus（Ruby/Rails，Webhook 编排）与 reposync（Python，git 执行）两个项目中；本项目将两者合并为可独立部署的单一服务，部署依赖收敛为 JDK 17 + MySQL。

功能特性

手动同步：支持仓库粒度（整仓）与分支粒度的手动触发同步
Webhook 实时同步：接收平台 push 事件，延迟触发自动同步，替代原 Sidekiq 方案
- 事件延迟队列 + 原子抢占消费，支持多实例部署
- 同仓库同分支事件自动去重合并
- 失败自动重试（可配置次数与退避间隔）
一键创建双向同步：单次调用完成双向仓库配置、分支映射、Webhook 注册与双向首次同步
同步状态跟踪：仓库/分支级同步状态回写与查询
多平台适配：PlatformHookAdapter 接口预留 Hook 注册扩展点（GitLink 已实现）

技术栈

组件	说明
Java 17 + Spring Boot 3.2.5	Spring MVC（非 WebFlux）+ Spring Data JPA
MySQL	同步配置、日志、Webhook 事件队列存储
Knife4j 4.4.0	OpenAPI 文档与调试 UI
Git CLI	实际同步执行（`git fetch` + `git push --force`）
Docker	容器化部署（构建阶段含 Maven 编译）

快速开始

环境要求

JDK 17、Maven 3.9+
MySQL 5.7+ / 8.0
本机安装 git（同步核心依赖）

1. 初始化数据库

mysql -u root -p < sql/init.sql
# 已有旧版本部署时，执行增量脚本
mysql -u root -p < sql/20261110_add_webhook_and_sync_status.sql

2. 配置

核心配置位于 src/main/resources/application.yml，全部支持环境变量覆盖，默认激活 local profile：

环境变量	默认值	说明
`SERVER_PORT`	8000	服务端口
`SYS_ENV`	local	激活 profile（local / dev）
`CEROBOT_MYSQL_HOST/PORT/DB/USER/PWD`	localhost / 3306 / reposync / root	数据库连接
`SYNC_DIR`	/tmp/sync_dir/	git 同步工作目录
`LOG_PATH`	/tmp/reposync_logs/	同步日志目录
`GIT_BIN` / `GIT_TIMEOUT_MINUTES`	git / 30	git 二进制与超时
`GITHUB_TOKEN` / `GITEE_TOKEN` 等	空	各平台 API Token
`WEBHOOK_BASE_URL`	http://localhost:8000	Webhook 回调地址（部署时填公网域名）
`WEBHOOK_DELAY_SECONDS`	5	push 事件延迟触发秒数
`WEBHOOK_MAX_RETRY` / `WEBHOOK_RETRY_BACKOFF_SECONDS`	3 / 30	失败重试次数与退避
`WEBHOOK_TOKEN`	空	非空时校验回调鉴权头 `X-Reposync-Token`
`WEBHOOK_AUTO_REGISTER`	true	创建配置时自动注册 Webhook

3. 启动

mvn spring-boot:run

启动后访问：

API 文档（Knife4j）：http://localhost:8000/doc.html
健康检查：http://localhost:8000/actuator/health

本地测试

完整测试步骤见首次同步测试与增量同步，覆盖首次同步、增量同步、推送冲突与强制覆盖四条路径；Webhook 链路可按 POST /api/v1/webhook/{platform}?repo_name={repoName} 手动模拟触发。

Windows 环境说明

repo_name 可能包含冒号（如双向配置生成的 test-pair:1），该字符在 Windows 下不能用作文件名。因此本服务在磁盘路径层面做了转义：

用途	取值
数据库、API、Webhook 回调中的 `repo_name`	`test-pair:1`（原值，保持不变）
同步工作目录 / 任务日志文件名	`test-pair_1` / `sync_test-pair_1.log`

转义仅在 Windows 生效（GitExecutor.safeName）；Linux 保持原名，与升级前行为一致。

Docker 部署

docker build -t reposync-java .
docker run -d -p 8000:8000 \
  -e CEROBOT_MYSQL_HOST=<db-host> \
  -e CEROBOT_MYSQL_PWD=<db-password> \
  -e WEBHOOK_BASE_URL=https://your-public-domain \
  reposync-java

镜像内已预装 git 与 openssh-client，健康检查指向 /actuator/health。

API 概览

完整接口定义见 Knife4j 文档，主要接口：

Webhook 接收

POST /api/v1/webhook/{platform}?repo_name={repoName}
Header: X-Reposync-Token: <配置了 webhook.token 时必传>

端点仅解析 payload 并入队，毫秒级返回；git 操作延迟 5 秒执行。

双向同步配置

POST /cerobot/sync/pair                                    # 一键创建双向配置（含首次同步）
GET  /cerobot/sync/{repoName}/branch/status                # 分支同步状态
GET  /cerobot/sync/repo/{repoName}/overview                # 仓库同步概览
GET  /cerobot/sync/repo/{repoName}/webhook/url             # 获取回调地址（手动配置 Hook 用）
POST /cerobot/sync/repo/{repoName}/webhook/register        # 手动注册 Webhook

手动同步

POST /cerobot/sync/repo/{repoName}/sync                    # 整仓同步
POST /cerobot/sync/{repoName}/branch/{branchName}/sync     # 分支同步

核心流程

平台 push
   → POST /api/v1/webhook/{platform}（校验 token，解析分支）
   → WebhookDispatcher（配置匹配、事件去重）
   → webhook_event 入队（status=0，延迟 5s）
   → DelayTriggerScheduler（1s 扫描，原子抢占防多实例重复消费）
   → SyncEngine.syncBranchNow / syncRepoNow
   → GitExecutor（git fetch + push --force）
   → SyncStatusService 回写同步状态

事件状态机：0 待处理 → 1 处理中 → 2 成功 / 3 失败，失败未达重试上限时回到待处理（触发时间 +30s）。

项目结构

├── docs/               # 变更说明与本地测试文档
├── sql/                # 数据库初始化与增量脚本
├── src/main/java/com/reposync/
│   ├── common/         # 通用响应、异常、枚举
│   ├── config/         # 应用配置（属性、异步、OpenAPI）
│   ├── controller/     # REST 接口层
│   ├── dto/            # 请求/响应 DTO
│   ├── entity/         # JPA 实体
│   ├── repository/     # 数据访问层
│   ├── git/            # 同步引擎与 git 执行器
│   ├── platform/       # 平台 Hook 适配器
│   ├── security/       # Cookie 解码、安全过滤器
│   ├── service/        # 业务逻辑层
│   └── webhook/        # Webhook 解析、分发、延迟调度
└── src/main/resources/ # application.yml 及 profile 配置