# Git 直连架构补充方案

## 1. 背景变化

旧方案的前提是：

- 开发环境和生产环境不能直接交换同步数据
- 需要通过 `开发环境 -> FTP -> 生产环境` 中转

现在条件已经变化为：

- FTP 不再使用
- 生产环境可以直接访问开发 Git 仓库

这意味着旧架构里的 FTP 中转层已经没有存在价值，应该直接删除。

## 2. 新架构结论

推荐把原来的“双端代理 + FTP 中转”收敛为：

- **单端代理 + Git 直连 + 本地状态库**

也就是只在生产环境部署一套同步服务：

- `Sync-Agent-Prod`

整体拓扑如下：

```text
开发 Git 仓库 <----> 生产环境 Sync-Agent-Prod <----> 生产系统 push/pull 接口
```

## 3. 为什么这样改

新架构比旧架构更合理，原因很直接：

- 去掉 FTP，中间链路减少一跳
- 去掉打包上传、轮询下载、ACK 回执等中间机制
- 部署节点从 2 个变成 1 个
- 故障点减少，排查成本更低
- 数据路径更直接，状态控制更简单

## 4. 新方案的核心思路

既然生产环境已经能访问开发 Git，那么同步动作都可以在生产环境完成。

生产环境部署的 `Sync-Agent-Prod` 同时承担两条链路：

### 4.1 开发 Git -> 生产

流程：

1. 定时拉取开发 Git 的配置分支
2. 获取最新 commit 版本
3. 判断该版本是否已同步
4. 如果未同步，则读取配置内容
5. 调用生产 `push` 接口导入配置
6. 成功后更新本地检查点

### 4.2 生产 -> 开发 Git

流程：

1. 定时调用生产 `pull` 接口
2. 获取当前生产配置快照
3. 计算内容哈希或版本号
4. 判断该快照是否已同步
5. 如果未同步，则写入 Git 快照分支
6. commit 并 push 到开发 Git
7. 成功后更新本地检查点

## 5. 部署建议

### 5.1 推荐部署方式

推荐只保留：

- `prod-agent`

不再需要：

- `dev-agent`
- FTP 服务
- FTP ACK、包中转、失败目录等机制

### 5.2 运行前提

生产环境需要同时满足：

- 能读取开发 Git
- 能向开发 Git 推送指定分支
- 能调用生产 `push/pull` 接口
- 能持久化 H2 文件数据库

这里有一个必须先确认的关键点：

- **生产环境对开发 Git 是否有 push 权限**

如果只有读权限，没有 push 权限，那么第二条链路“生产 -> 开发 Git”无法闭环。

## 6. Git 分支策略

这个设计必须保留，不然非常容易形成同步闭环。

建议继续使用两个分支：

- `config-dev-main`：开发主配置分支
- `config-prod-snapshot`：生产配置镜像分支

同步规则：

- `Git -> PROD` 只读 `config-dev-main`
- `PROD -> Git` 只写 `config-prod-snapshot`

这样做的好处：

- 避免生产回写内容再次触发生产下发
- 生产快照不污染开发主线
- 便于审计和回溯

## 7. 状态管理

虽然 FTP 没了，但本地状态库仍然必须保留。

建议继续保留：

- `sync_checkpoint`
- `sync_task`

`sync_ack` 在新架构下不再承担跨节点 ACK 作用。

当前建议：

- 已退出主 schema
- 如后续需要审计，可独立恢复

## 8. 幂等设计

建议继续使用：

```text
direction + sourceVersion + contentHash
```

作为业务幂等键。

作用：

- 同一个开发版本不会重复推生产
- 同一个生产快照不会重复写 Git

## 9. 失败处理

建议自动重试以下场景：

- Git pull 失败
- Git push 失败
- 生产 `push` 接口失败
- 生产 `pull` 接口失败

建议策略：

- 最大重试次数：`3 ~ 5`
- 指数退避：`30s / 60s / 120s`

失败后：

- 更新 `sync_task` 状态
- 保留错误信息
- 不推进检查点

## 10. 安全建议

### 10.1 Git 访问

推荐使用：

- HTTPS + Token

或：

- SSH Deploy Key

### 10.2 权限控制

生产环境访问 Git 的账号建议最小权限化：

- 对 `config-dev-main` 有读权限
- 对 `config-prod-snapshot` 有写权限

更理想的做法：

- 使用专用机器人账号
- 对主分支做保护
- 机器人只写快照分支

## 11. 对现有代码的影响

这次需求变化对当前代码影响很大，结论如下：

### 11.1 可以继续保留的部分

- `GitClientService`
- `ProdConfigApiService`
- `SyncTaskService`
- `CheckpointService`
- H2 表结构
- 定时任务框架

### 11.2 已退出主运行面的部分

- FTP 目录配置
- 包上传/下载流程
- ACK 文件机制
- 双端部署假设

### 11.3 当前代码状态

当前代码已经收敛为：

- 一个正式运行角色 `prod-agent`
- 两个正式调度任务

即：

1. `GitToProdSyncJob`
2. `ProdToGitSnapshotJob`

旧架构源码主体已经删除，当前剩余问题主要是：

- 个别资源文件仍保留退役标记
- 工程内少量 `ftp` 命名仍待统一

## 12. 结论

现在最合理的做法不是“在旧 FTP 方案上修修补补”，而是直接把架构收敛成：

- **生产环境单点部署**
- **直连开发 Git**
- **继续调用生产 `push/pull` 接口**
- **保留 H2 做状态控制**

这是一次简化，不是一次退化。

## 13. 下一步建议

建议按这个顺序推进：

1. 先确认生产环境是否具备开发 Git 的 push 权限
2. 确认生产 `push/pull` 接口最终协议
3. 删除退役标记文件 `application-dev-agent.properties`
4. 继续清理工程中残留的 `ftp` 命名
5. 补充健康检查和管理能力