dark 0162117ae4 refactor: 收敛为 Git 直连同步架构并完成收尾

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

2026-04-22 13:51:27 +08:00

5.3 KiB

Raw Blame History

Git 直连架构补充方案

1. 背景变化

旧方案的前提是：

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

现在条件已经变化为：

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

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

2. 新架构结论

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

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

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

Sync-Agent-Prod

整体拓扑如下：

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

3. 为什么这样改

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

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

4. 新方案的核心思路

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

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

4.1 开发 Git -> 生产

流程：

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

4.2 生产 -> 开发 Git

流程：

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

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. 幂等设计

建议继续使用：

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
两个正式调度任务

即：

GitToProdSyncJob
ProdToGitSnapshotJob

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

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

12. 结论

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

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

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

13. 下一步建议

建议按这个顺序推进：

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

5.3 KiB Raw Blame History Unescape Escape