0162117ae4
- 将整体方案从 FTP 中转双端代理重构为单 prod-agent 的 Git 直连架构 - 重写主设计文档、详细设计文档和补充方案文档，统一新架构口径 - 新增 GitDirectSyncToolApplication 并调整 Maven 坐标与运行命名 - 清理 application.properties、SyncProperties 和 schema.sql 中的 FTP/ACK 遗留配置与表结构 - 将生产侧主流程收敛为 Git -> PROD 与 PROD -> Git 两条正式链路 - 新增 SyncManagementController，提供最近同步状态与失败任务查询接口 - 补充 ProdSyncCoordinatorIntegrationTest，覆盖两条主链路的最小集成测试与幂等行为 - 为主链路代码补充必要中文注释，提升可读性 - 删除旧架构源码主体并同步修正文档中的过期引用 - 完成编译与测试验证
282 lines
6.7 KiB
Markdown
282 lines
6.7 KiB
Markdown
# Git 直连架构详细设计
|
||
|
||
## 1. 文档说明
|
||
|
||
本文档用于承接主方案文档，说明在“FTP 下线、生产环境可直接访问开发 Git”条件下的详细设计。
|
||
|
||
当前目标是把系统收敛为：
|
||
|
||
- 单 `prod-agent`
|
||
- Git 直连
|
||
- 生产 `push/pull` 接口驱动
|
||
- H2 本地状态控制
|
||
|
||
## 2. 架构变化摘要
|
||
|
||
旧架构：
|
||
|
||
```text
|
||
开发环境 <-> FTP <-> 生产环境
|
||
```
|
||
|
||
新架构：
|
||
|
||
```text
|
||
开发 Git <-> 生产环境 Sync-Agent-Prod <-> 生产 push/pull 接口
|
||
```
|
||
|
||
关键变化：
|
||
|
||
- FTP 中转取消
|
||
- `dev-agent` 不再是必需部署节点
|
||
- 生产环境成为唯一同步执行节点
|
||
- ACK 文件机制不再作为主流程依赖
|
||
|
||
## 3. 当前推荐部署
|
||
|
||
推荐只部署：
|
||
|
||
- `prod-agent`
|
||
|
||
运行要求：
|
||
|
||
- 能访问开发 Git
|
||
- 能 push 指定 Git 分支
|
||
- 能访问生产 `push/pull` 接口
|
||
- 能写本地 H2 文件数据库
|
||
|
||
## 4. 配置文件策略
|
||
|
||
当前配置文件仍使用 `properties`：
|
||
|
||
```text
|
||
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](e:/AIcoding/FtpTool/src/main/resources/application-prod-agent.properties)
|
||
|
||
### 5.3 遗留 FTP 配置
|
||
|
||
当前 `application.properties` 中已经移除了 `ftp.*` 相关公共配置。
|
||
|
||
当前状态：
|
||
|
||
- FTP 调度主路径已退出运行面
|
||
- FTP 相关主类已从当前源码树中移除
|
||
|
||
## 6. H2 状态设计
|
||
|
||
当前主表保留为：
|
||
|
||
- `sync_checkpoint`
|
||
- `sync_task`
|
||
|
||
对应脚本：
|
||
|
||
- [schema.sql](e:/AIcoding/FtpTool/src/main/resources/schema.sql)
|
||
|
||
### 6.1 保留原因
|
||
|
||
即使 FTP 已下线，状态库仍然必须保留，用于：
|
||
|
||
- 幂等控制
|
||
- 检查点管理
|
||
- 失败重试
|
||
- 审计追踪
|
||
|
||
### 6.2 当前建议
|
||
|
||
- `sync_checkpoint` 和 `sync_task` 继续作为主表
|
||
- `sync_ack` 已退出当前主 schema
|
||
|
||
## 7. 当前代码结构与新架构对应关系
|
||
|
||
### 7.1 已经可继续复用的核心类
|
||
|
||
- [GitClientService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/GitClientService.java)
|
||
- [ProdConfigApiService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/ProdConfigApiService.java)
|
||
- [PackageService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/PackageService.java)
|
||
- [SyncTaskService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/SyncTaskService.java)
|
||
- [CheckpointService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/CheckpointService.java)
|
||
|
||
### 7.2 当前生产侧主协调器
|
||
|
||
- [ProdSyncCoordinator.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/orchestrator/ProdSyncCoordinator.java)
|
||
|
||
当前生产侧主流程已经切到新架构：
|
||
|
||
- `syncLatestGitToProd()`：Git -> 生产 `push`
|
||
- `syncProdSnapshotToGit()`：生产 `pull` -> Git snapshot 分支
|
||
|
||
### 7.3 当前生产侧正式调度类
|
||
|
||
- [GitToProdSyncJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/GitToProdSyncJob.java)
|
||
- [ProdToGitSnapshotJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/ProdToGitSnapshotJob.java)
|
||
|
||
说明：
|
||
|
||
- 这两个类是当前推荐使用的正式调度入口
|
||
- 已分别对应 `Git -> PROD` 和 `PROD -> Git`
|
||
|
||
### 7.4 当前遗留占位类
|
||
|
||
这批旧调度类已经从当前源码树中删除：
|
||
|
||
说明：
|
||
|
||
- 已不再作为正式运行入口
|
||
- 当前代码树只保留 Git 直连架构需要的正式 job
|
||
|
||
### 7.5 当前遗留代码
|
||
|
||
以下内容仍然存在于代码库，但属于旧架构遗留：
|
||
|
||
- `application-dev-agent.properties` 退役标记文件
|
||
- 少量文件名或文档中的 `ftp` 语义残留
|
||
|
||
这些不是当前推荐运行路径。
|
||
|
||
## 8. 新架构下的两条任务流
|
||
|
||
### 8.1 Git -> 生产
|
||
|
||
当前推荐实现步骤：
|
||
|
||
1. 拉取 `config-dev-main`
|
||
2. 获取最新 commit 作为 `sourceVersion`
|
||
3. 导出工作树快照
|
||
4. 计算内容哈希
|
||
5. 生成标准 zip 包
|
||
6. 调用生产 `push` 接口
|
||
7. 更新 `sync_task` 和 `sync_checkpoint`
|
||
|
||
### 8.2 生产 -> Git
|
||
|
||
当前推荐实现步骤：
|
||
|
||
1. 调用生产 `pull` 接口
|
||
2. 保存返回配置到本地 staging 目录
|
||
3. 计算哈希和版本号
|
||
4. 写入 `config-prod-snapshot`
|
||
5. commit + push
|
||
6. 更新 `sync_task` 和 `sync_checkpoint`
|
||
|
||
## 9. 当前接口假设
|
||
|
||
当前生产接口仍按以下假设实现：
|
||
|
||
- `push` 使用 `POST + multipart/form-data`
|
||
- `pull` 使用 `GET`
|
||
- `pull` 返回原始 JSON 字节流
|
||
- 版本号优先取 `X-Config-Version`，其次 `ETag`
|
||
|
||
详细协议文档见：
|
||
|
||
- [prod-api-v1.md](e:/AIcoding/FtpTool/docs/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](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/web/SyncManagementController.java)
|
||
|
||
## 10. 当前主要风险
|
||
|
||
### 10.1 Git 写权限
|
||
|
||
如果生产环境对 Git 没有 push 权限，则“生产 -> Git”链路无法完成。
|
||
|
||
### 10.2 旧代码残留
|
||
|
||
当前主运行面已经切到 Git 直连，但源码树里仍保留少量退役占位类。
|
||
|
||
当前状态：
|
||
|
||
- 文件名和类名仍可能误导维护者
|
||
- 旧架构源码主体已经删除
|
||
- 主要剩余问题转为命名和文档口径统一
|
||
|
||
### 10.3 双向同步闭环
|
||
|
||
如果误把生产回写分支也作为下发分支扫描，会造成循环同步。
|
||
|
||
## 11. 推荐的下一轮改造
|
||
|
||
建议按下面顺序继续：
|
||
|
||
1. 删除或隔离 `dev-agent` 运行路径
|
||
2. 删除退役标记文件 `application-dev-agent.properties`
|
||
3. 统一清理残留的 `ftp` 命名
|
||
4. 补充管理接口和健康检查接口
|
||
5. 增加集成测试
|
||
|
||
## 12. 结论
|
||
|
||
当前系统已经从“FTP 中转”开始转向“Git 直连”。
|
||
|
||
现阶段最重要的不是继续增强旧链路，而是彻底收敛到：
|
||
|
||
- 单 `prod-agent`
|
||
- 两个核心任务
|
||
- 一个 Git 仓库入口
|
||
- 一组生产 `push/pull` 接口
|