dark dcfdc83444 refactor: 收敛同步工具为 Git 直连单 prod-agent 架构

- 重写主设计文档与详细设计文档，移除 FTP 中转方案口径
- 新增 Git 直连架构设计文档，明确单 prod-agent 部署模式
- 将生产侧主同步流程切换为 Git -> PROD 和 PROD -> Git 两条直连链路
- 新增正式调度任务 GitToProdSyncJob 与 ProdToGitSnapshotJob
- 移除 commons-net 主依赖并将 FTP 能力退出主运行面
- 清理 application.properties 中 FTP/ACK 相关公共配置
- 收敛 SyncProperties，删除 FTP 远端目录与 ACK 扫描字段
- 精简 schema.sql，移除 sync_ack 表，仅保留 sync_checkpoint 与 sync_task
- 将 dev-agent、FTP、ACK 相关旧类降级为退役占位实现
- 调整项目命名与默认配置，统一到 Git 直连架构
- 完成编译验证

2026-04-20 14:30:43 +08:00

5.1 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 权限，那么第二条链路“生产 -> 开发 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 作用，可以：

继续保留为接口调用结果日志表
或后续简化下线

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 应该逐步下线的部分

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

11.3 推荐重构方向

把系统收敛为：

一个 prod-agent
两个核心任务

即：

GitToProdSyncJob
ProdToGitSnapshotJob

12. 结论

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

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

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

13. 下一步建议

建议按这个顺序推进：

先确认生产环境是否具备开发 Git 的 push 权限
确认生产 push/pull 接口最终协议
重写主设计文档和详细设计文档，去掉 FTP 相关内容
收敛代码为单 prod-agent
删除 FTP 相关配置和服务

5.1 KiB Raw Blame History Unescape Escape