dcfdc83444
- 重写主设计文档与详细设计文档，移除 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 直连架构 - 完成编译验证
248 lines
5.1 KiB
Markdown
248 lines
5.1 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 权限，那么第二条链路“生产 -> 开发 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. 幂等设计
|
||
|
||
建议继续使用：
|
||
|
||
```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 应该逐步下线的部分
|
||
|
||
- `FtpClientService`
|
||
- FTP 目录配置
|
||
- 包上传/下载流程
|
||
- ACK 文件机制
|
||
- 双端部署假设
|
||
|
||
### 11.3 推荐重构方向
|
||
|
||
把系统收敛为：
|
||
|
||
- 一个 `prod-agent`
|
||
- 两个核心任务
|
||
|
||
即：
|
||
|
||
1. `GitToProdSyncJob`
|
||
2. `ProdToGitSnapshotJob`
|
||
|
||
## 12. 结论
|
||
|
||
现在最合理的做法不是“在旧 FTP 方案上修修补补”，而是直接把架构收敛成：
|
||
|
||
- **生产环境单点部署**
|
||
- **直连开发 Git**
|
||
- **继续调用生产 `push/pull` 接口**
|
||
- **保留 H2 做状态控制**
|
||
|
||
这是一次简化，不是一次退化。
|
||
|
||
## 13. 下一步建议
|
||
|
||
建议按这个顺序推进：
|
||
|
||
1. 先确认生产环境是否具备开发 Git 的 push 权限
|
||
2. 确认生产 `push/pull` 接口最终协议
|
||
3. 重写主设计文档和详细设计文档，去掉 FTP 相关内容
|
||
4. 收敛代码为单 `prod-agent`
|
||
5. 删除 FTP 相关配置和服务
|