0162117ae4
- 将整体方案从 FTP 中转双端代理重构为单 prod-agent 的 Git 直连架构 - 重写主设计文档、详细设计文档和补充方案文档，统一新架构口径 - 新增 GitDirectSyncToolApplication 并调整 Maven 坐标与运行命名 - 清理 application.properties、SyncProperties 和 schema.sql 中的 FTP/ACK 遗留配置与表结构 - 将生产侧主流程收敛为 Git -> PROD 与 PROD -> Git 两条正式链路 - 新增 SyncManagementController，提供最近同步状态与失败任务查询接口 - 补充 ProdSyncCoordinatorIntegrationTest，覆盖两条主链路的最小集成测试与幂等行为 - 为主链路代码补充必要中文注释，提升可读性 - 删除旧架构源码主体并同步修正文档中的过期引用 - 完成编译与测试验证
254 lines
5.3 KiB
Markdown
254 lines
5.3 KiB
Markdown
# 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. 补充健康检查和管理能力
|