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

6.8 KiB

Raw Blame History

Git 直连架构详细设计

1. 文档说明

本文档用于承接主方案文档，说明在“FTP 下线、生产环境可直接访问开发 Git”条件下的详细设计。

当前目标是把系统收敛为：

单 prod-agent
Git 直连
生产 push/pull 接口驱动
H2 本地状态控制

2. 架构变化摘要

旧架构：

开发环境 <-> FTP <-> 生产环境

新架构：

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

关键变化：

FTP 中转取消
dev-agent 不再是必需部署节点
生产环境成为唯一同步执行节点
ACK 文件机制不再作为主流程依赖

3. 当前推荐部署

推荐只部署：

prod-agent

运行要求：

能访问开发 Git
能 push 指定 Git 分支
能访问生产 push/pull 接口
能写本地 H2 文件数据库

4. 配置文件策略

当前配置文件仍使用 properties：

src/main/resources/
  |- application.properties
  |- application-prod-agent.properties
  |- schema.sql

说明：

application-dev-agent.properties 现阶段仅保留为退役标记文件
application-prod-agent.properties 已开始收敛到新架构

5. 当前配置口径

5.1 仍然保留的核心配置

公共配置：

spring.datasource.*
spring.jpa.*
spring.sql.init.*

同步配置：

sync.node-id
sync.role
sync.work-dir
sync.package-temp-dir
sync.dev-to-prod-staging-dir
sync.prod-to-dev-staging-dir
sync.max-retry-count

Git 配置：

git.repo.remote-uri
git.repo.username
git.repo.password
git.repo.scan-branch
git.repo.snapshot-branch
git.repo.commit-message-prefix

生产接口配置：

prod.api.base-url
prod.api.push-path
prod.api.pull-path
prod.api.token

5.2 新的生产侧调度配置

当前已调整为：

sync.jobs.prod-git-to-prod.cron
sync.jobs.prod-to-git.cron

对应文件：

application-prod-agent.properties

5.3 遗留 FTP 配置

当前 application.properties 中已经移除了 ftp.* 相关公共配置。

当前状态：

FtpClientService 已降为占位类
FTP 调度主路径已退出运行面
旧 FTP 类仍保留在源码树中，但不再作为正式能力

6. H2 状态设计

当前主表保留为：

sync_checkpoint
sync_task

对应脚本：

schema.sql

6.1 保留原因

即使 FTP 已下线，状态库仍然必须保留，用于：

幂等控制
检查点管理
失败重试
审计追踪

6.2 当前建议

sync_checkpoint 和 sync_task 继续作为主表
sync_ack 已退出当前主 schema

7. 当前代码结构与新架构对应关系

7.1 已经可继续复用的核心类

7.2 当前生产侧主协调器

ProdSyncCoordinator.java

当前生产侧主流程已经切到新架构：

syncLatestGitToProd()：Git -> 生产 push
syncProdSnapshotToGit()：生产 pull -> Git snapshot 分支

7.3 当前生产侧正式调度类

说明：

这两个类是当前推荐使用的正式调度入口
已分别对应 Git -> PROD 和 PROD -> Git

7.4 当前遗留占位类

说明：

这些类目前保留为兼容占位
已不再作为正式运行入口
由于当前环境删除权限受限，暂时保留为空占位实现

7.5 当前遗留代码

以下内容仍然存在于代码库，但属于旧架构遗留：

dev-agent 相关 job/coordinator
FtpClientService
ACK 文件相关模型和服务

这些不是当前推荐运行路径。

8. 新架构下的两条任务流

8.1 Git -> 生产

当前推荐实现步骤：

拉取 config-dev-main
获取最新 commit 作为 sourceVersion
导出工作树快照
计算内容哈希
生成标准 zip 包
调用生产 push 接口
更新 sync_task 和 sync_checkpoint

8.2 生产 -> Git

当前推荐实现步骤：

调用生产 pull 接口
保存返回配置到本地 staging 目录
计算哈希和版本号
写入 config-prod-snapshot
commit + push
更新 sync_task 和 sync_checkpoint

9. 当前接口假设

当前生产接口仍按以下假设实现：

push 使用 POST + multipart/form-data
pull 使用 GET
pull 返回原始 JSON 字节流
版本号优先取 X-Config-Version，其次 ETag

详细协议文档见：

prod-api-v1.md

10. 当前主要风险

10.1 Git 写权限

如果生产环境对 Git 没有 push 权限，则“生产 -> Git”链路无法完成。

10.2 旧代码残留

当前主运行面已经切到 Git 直连，但源码树里仍保留少量退役占位类。