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

6.7 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.* 相关公共配置。

当前状态：

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 当前遗留占位类

这批旧调度类已经从当前源码树中删除：

说明：

已不再作为正式运行入口
当前代码树只保留 Git 直连架构需要的正式 job

7.5 当前遗留代码

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

application-dev-agent.properties 退役标记文件
少量文件名或文档中的 ftp 语义残留

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

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

9.1 管理接口

当前已新增一组只读管理接口，用于查看最近同步状态和失败任务：

GET /api/admin/sync/overview
GET /api/admin/sync/tasks/recent
GET /api/admin/sync/tasks/failed

对应实现：

SyncManagementController.java

10. 当前主要风险

10.1 Git 写权限

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

10.2 旧代码残留

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