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 直连架构 - 完成编译验证
276 lines
6.8 KiB
Markdown
276 lines
6.8 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.*` 相关公共配置。
|
||
|
||
当前状态：
|
||
|
||
- `FtpClientService` 已降为占位类
|
||
- 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 当前遗留占位类
|
||
|
||
- [ProdConsumeDevPackageJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/ProdConsumeDevPackageJob.java)
|
||
- [ProdPullConfigJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/ProdPullConfigJob.java)
|
||
- [DevGitScanJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/DevGitScanJob.java)
|
||
- [DevConsumeProdPackageJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/DevConsumeProdPackageJob.java)
|
||
- [DevAckScanJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/DevAckScanJob.java)
|
||
|
||
说明：
|
||
|
||
- 这些类目前保留为兼容占位
|
||
- 已不再作为正式运行入口
|
||
- 由于当前环境删除权限受限，暂时保留为空占位实现
|
||
|
||
### 7.5 当前遗留代码
|
||
|
||
以下内容仍然存在于代码库，但属于旧架构遗留：
|
||
|
||
- `dev-agent` 相关 job/coordinator
|
||
- `FtpClientService`
|
||
- ACK 文件相关模型和服务
|
||
|
||
这些不是当前推荐运行路径。
|
||
|
||
## 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)
|
||
|
||
## 10. 当前主要风险
|
||
|
||
### 10.1 Git 写权限
|
||
|
||
如果生产环境对 Git 没有 push 权限，则“生产 -> Git”链路无法完成。
|
||
|
||
### 10.2 旧代码残留
|
||
|
||
当前主运行面已经切到 Git 直连，但源码树里仍保留少量退役占位类。
|
||
|
||
当前状态：
|
||
|
||
- 文件名和类名仍可能误导维护者
|
||
- 极少量退役文件仍保留在源码树中
|
||
|
||
### 10.3 双向同步闭环
|
||
|
||
如果误把生产回写分支也作为下发分支扫描，会造成循环同步。
|
||
|
||
## 11. 推荐的下一轮改造
|
||
|
||
建议按下面顺序继续：
|
||
|
||
1. 删除或隔离 `dev-agent` 运行路径
|
||
2. 在文件系统允许时物理删除退役占位类
|
||
3. 统一清理残留的 `ftp` 命名
|
||
4. 补充管理接口和健康检查接口
|
||
5. 增加集成测试
|
||
|
||
## 12. 结论
|
||
|
||
当前系统已经从“FTP 中转”开始转向“Git 直连”。
|
||
|
||
现阶段最重要的不是继续增强旧链路，而是彻底收敛到：
|
||
|
||
- 单 `prod-agent`
|
||
- 两个核心任务
|
||
- 一个 Git 仓库入口
|
||
- 一组生产 `push/pull` 接口
|