604 lines
14 KiB
Markdown
604 lines
14 KiB
Markdown
# 基于 FTP 中转的配置双向同步工具设计方案
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档用于说明一套基于 FTP 中转的配置同步工具设计方案，满足以下目标：
|
||
|
||
- 开发环境定时从 Git 拉取新配置，并通过生产环境 `push` 接口推送到生产
|
||
- 生产环境定时从 `pull` 接口拉取新配置，并同步回开发环境 Git
|
||
- 在开发环境与生产环境不能直接互通时，通过 FTP 服务作为中转通道完成双向同步
|
||
|
||
## 2. 已知约束
|
||
|
||
### 2.1 技术约束
|
||
|
||
- JDK：`1.8`
|
||
- Spring Boot：`2.7.18`
|
||
- 轻量数据库：`H2` 或同类开源可商用数据库
|
||
- 其他依赖必须为开源可商用组件
|
||
|
||
### 2.2 网络与部署约束
|
||
|
||
- 无法登录 FTP 所在服务器主机
|
||
- 只能访问 FTP 服务：`IP + 端口 + 用户名/密码`
|
||
- 网络拓扑如下：
|
||
|
||
```text
|
||
开发环境 <----> FTP A <----> 生产环境
|
||
```
|
||
|
||
说明：
|
||
|
||
- 开发环境可以访问 FTP A
|
||
- 生产环境可以访问 FTP A
|
||
- 开发与生产不假设可以直接互通
|
||
|
||
## 3. 设计原则
|
||
|
||
- 同一套程序，按不同 `profile` 部署在开发和生产两端
|
||
- 通过 FTP 传递标准化同步包，避免环境间直接通信依赖
|
||
- 使用本地状态库记录同步任务、检查点、应答信息，保证可追踪、可恢复
|
||
- 同步流程必须具备幂等控制，避免重复推送、重复提交
|
||
- 开发到生产、生产回开发必须隔离处理，避免双向同步形成死循环
|
||
|
||
## 4. 总体方案
|
||
|
||
推荐采用“**双端代理 + FTP 中转 + 本地状态库**”架构：
|
||
|
||
- `Sync-Agent-Dev`：部署在开发环境
|
||
- `Sync-Agent-Prod`：部署在生产环境
|
||
- `FTP A`：作为唯一中转通道
|
||
- `H2`：记录同步状态、任务、检查点、重试信息
|
||
|
||
整体结构如下：
|
||
|
||
```text
|
||
开发环境
|
||
Sync-Agent-Dev
|
||
|- 拉取 Git
|
||
|- 上传/下载 FTP A
|
||
|- 写入 Git
|
||
|
||
生产环境
|
||
Sync-Agent-Prod
|
||
|- 调用生产 pull 接口
|
||
|- 调用生产 push 接口
|
||
|- 上传/下载 FTP A
|
||
|
||
中转
|
||
FTP A
|
||
|- dev-to-prod/
|
||
|- prod-to-dev/
|
||
|- ack/
|
||
|- failed/
|
||
```
|
||
|
||
## 5. 部署模式
|
||
|
||
建议只维护一套代码，通过 Spring Profile 控制角色：
|
||
|
||
- `dev-agent`：启用开发侧能力
|
||
- `prod-agent`：启用生产侧能力
|
||
|
||
### 5.1 开发侧职责
|
||
|
||
- 定时拉取 Git 指定分支的新配置
|
||
- 判断是否存在新的有效版本
|
||
- 打包配置并上传到 FTP
|
||
- 下载生产侧回传的同步包
|
||
- 将生产侧回传配置写入 Git
|
||
- 提交并推送到远端仓库
|
||
|
||
### 5.2 生产侧职责
|
||
|
||
- 轮询 FTP，获取开发侧上传的配置包
|
||
- 校验后调用生产 `push` 接口导入配置
|
||
- 定时调用生产 `pull` 接口拉取最新配置
|
||
- 打包并上传回 FTP，供开发侧消费
|
||
|
||
## 6. 技术选型
|
||
|
||
| 分类 | 选型 | 说明 |
|
||
| --- | --- | --- |
|
||
| 运行时 | JDK 1.8 | 满足约束 |
|
||
| 框架 | Spring Boot 2.7.18 | 主体框架 |
|
||
| 调度 | Spring Scheduling | 实现定时任务 |
|
||
| 重试 | Spring Retry | 失败重试 |
|
||
| 数据库 | H2 File Mode | 轻量、嵌入式、可持久化 |
|
||
| Git 操作 | JGit | 纯 Java 实现 |
|
||
| FTP 操作 | Apache Commons Net | 主流 FTP 客户端 |
|
||
| JSON | Jackson | 标准序列化组件 |
|
||
| 日志 | SLF4J + Logback | 默认日志能力 |
|
||
|
||
### 6.1 数据库模式建议
|
||
|
||
虽然需求提到“类似 H2 的轻量化内存数据库”，但本场景不建议纯内存模式，原因如下：
|
||
|
||
- 服务重启后需要保留同步检查点
|
||
- 失败任务需要支持补偿和人工追踪
|
||
- 需要记录包处理状态，避免重复消费
|
||
|
||
因此建议使用：
|
||
|
||
- `H2 File Mode`
|
||
|
||
即本地文件数据库，仍然轻量，但支持状态持久化。
|
||
|
||
## 7. 核心业务流程
|
||
|
||
系统包含两条主链路。
|
||
|
||
### 7.1 链路一：开发 Git -> 生产 push 接口
|
||
|
||
用途：将开发环境 Git 中的新配置推送到生产环境。
|
||
|
||
流程如下：
|
||
|
||
1. `dev-agent` 定时拉取 Git 指定分支
|
||
2. 判断 Git 最新提交是否为新的有效配置版本
|
||
3. 将配置目录打包为标准同步包
|
||
4. 上传至 FTP 路径 `dev-to-prod/out/`
|
||
5. `prod-agent` 轮询 FTP，发现新包后下载
|
||
6. 校验包完整性、幂等键和来源信息
|
||
7. 调用生产环境 `push` 接口导入配置
|
||
8. 成功后生成 `ack` 文件上传到 FTP
|
||
9. `dev-agent` 读取 `ack`，将任务状态更新为成功
|
||
|
||
建议时序图如下：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant G as Git(开发)
|
||
participant D as Sync-Agent-Dev
|
||
participant F as FTP A
|
||
participant P as Sync-Agent-Prod
|
||
participant API as 生产Push接口
|
||
|
||
D->>G: 定时 pull 配置
|
||
D->>D: 检查是否有新版本
|
||
D->>D: 打包 zip + manifest
|
||
D->>F: 上传 dev-to-prod/out/
|
||
P->>F: 轮询并下载新包
|
||
P->>P: 校验 hash/traceId
|
||
P->>API: 调用 push 接口
|
||
API-->>P: 返回处理结果
|
||
P->>F: 上传 ack
|
||
D->>F: 读取 ack
|
||
D->>D: 更新状态为成功
|
||
```
|
||
|
||
### 7.2 链路二：生产 pull 接口 -> 开发 Git
|
||
|
||
用途：将生产环境当前配置回传到开发环境，形成配置镜像或审计记录。
|
||
|
||
流程如下：
|
||
|
||
1. `prod-agent` 定时调用生产 `pull` 接口
|
||
2. 将返回配置标准化后计算版本标识或内容哈希
|
||
3. 如果与上次同步结果不同，则打包上传到 FTP `prod-to-dev/out/`
|
||
4. `dev-agent` 轮询 FTP 并下载新包
|
||
5. 解包后写入本地 Git 工作目录
|
||
6. 提交 commit 并推送到远端 Git
|
||
7. 成功后写回 `ack`
|
||
|
||
建议时序图如下：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant API as 生产Pull接口
|
||
participant P as Sync-Agent-Prod
|
||
participant F as FTP A
|
||
participant D as Sync-Agent-Dev
|
||
participant G as Git(开发)
|
||
|
||
P->>API: 定时调用 pull 接口
|
||
API-->>P: 返回当前配置
|
||
P->>P: 标准化并计算 hash
|
||
P->>F: 上传 prod-to-dev/out/
|
||
D->>F: 轮询并下载新包
|
||
D->>D: 解包并写入工作区
|
||
D->>G: commit + push
|
||
D->>F: 上传 ack
|
||
```
|
||
|
||
## 8. 标准同步包设计
|
||
|
||
为保证跨环境处理一致，建议所有同步内容封装为统一格式的压缩包。
|
||
|
||
### 8.1 包结构
|
||
|
||
```text
|
||
package.zip
|
||
|- manifest.json
|
||
|- config/
|
||
|- sha256.txt
|
||
```
|
||
|
||
### 8.2 manifest 字段建议
|
||
|
||
```json
|
||
{
|
||
"traceId": "uuid",
|
||
"direction": "DEV_TO_PROD",
|
||
"sourceEnv": "DEV",
|
||
"sourceVersion": "gitCommitId",
|
||
"contentHash": "sha256",
|
||
"createdAt": "2026-04-15T10:00:00+08:00"
|
||
}
|
||
```
|
||
|
||
### 8.3 字段说明
|
||
|
||
- `traceId`：本次同步唯一流水号
|
||
- `direction`：同步方向，例如 `DEV_TO_PROD`、`PROD_TO_DEV`
|
||
- `sourceEnv`：来源环境
|
||
- `sourceVersion`：来源版本号，开发侧通常为 Git Commit ID
|
||
- `contentHash`：配置内容哈希，便于判断重复包
|
||
- `createdAt`：包生成时间
|
||
|
||
## 9. FTP 目录规划
|
||
|
||
建议在 FTP A 上使用如下目录结构：
|
||
|
||
```text
|
||
/dev-to-prod/out/
|
||
/dev-to-prod/ack/
|
||
/prod-to-dev/out/
|
||
/prod-to-dev/ack/
|
||
/failed/
|
||
```
|
||
|
||
目录说明：
|
||
|
||
- `/dev-to-prod/out/`：开发侧发往生产侧的同步包
|
||
- `/dev-to-prod/ack/`：生产侧返回的处理应答
|
||
- `/prod-to-dev/out/`：生产侧发往开发侧的同步包
|
||
- `/prod-to-dev/ack/`：开发侧返回的处理应答
|
||
- `/failed/`：失败包归档目录
|
||
|
||
### 9.1 上传规范
|
||
|
||
为避免消费端读取到半截文件，建议采用临时文件上传策略：
|
||
|
||
1. 先上传为 `.tmp`
|
||
2. 上传完成后重命名为正式 `.zip`
|
||
3. 消费端只处理 `.zip` 文件
|
||
|
||
## 10. Git 分支策略
|
||
|
||
这是方案中的关键设计点。
|
||
|
||
不建议将“开发配置推生产”和“生产配置回传开发”写到同一个 Git 分支，否则极易形成循环同步。
|
||
|
||
建议拆分为两个分支：
|
||
|
||
- `config-dev-main`：开发主配置分支
|
||
- `config-prod-snapshot`：生产配置镜像分支
|
||
|
||
同步规则：
|
||
|
||
- `DEV -> PROD` 只消费 `config-dev-main`
|
||
- `PROD -> DEV` 只写入 `config-prod-snapshot`
|
||
|
||
### 10.1 这样设计的好处
|
||
|
||
- 避免双向同步形成闭环
|
||
- 生产回传配置不会覆盖开发主线
|
||
- 便于审计“生产当前实际配置”
|
||
|
||
### 10.2 机器人提交标记
|
||
|
||
建议同步工具在 commit message 中增加固定前缀，例如：
|
||
|
||
```text
|
||
sync(prod->git): traceId=xxx version=xxx
|
||
```
|
||
|
||
开发侧扫描 Git 时应忽略同步机器人生成的提交，进一步降低环路风险。
|
||
|
||
## 11. 本地状态库设计
|
||
|
||
建议至少建立以下 3 张表。
|
||
|
||
### 11.1 `sync_checkpoint`
|
||
|
||
用于记录各方向的最后一次成功检查点。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint | 主键 |
|
||
| direction | varchar | 同步方向 |
|
||
| last_success_version | varchar | 最后成功版本 |
|
||
| last_success_hash | varchar | 最后成功内容哈希 |
|
||
| updated_at | timestamp | 更新时间 |
|
||
|
||
### 11.2 `sync_task`
|
||
|
||
用于记录每次同步任务生命周期。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint | 主键 |
|
||
| trace_id | varchar | 流水号 |
|
||
| direction | varchar | 同步方向 |
|
||
| source_version | varchar | 来源版本 |
|
||
| package_name | varchar | 包文件名 |
|
||
| status | varchar | 状态 |
|
||
| retry_count | int | 重试次数 |
|
||
| error_msg | clob | 错误信息 |
|
||
| created_at | timestamp | 创建时间 |
|
||
| updated_at | timestamp | 更新时间 |
|
||
|
||
### 11.3 `sync_ack`
|
||
|
||
用于记录应答信息。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| id | bigint | 主键 |
|
||
| trace_id | varchar | 流水号 |
|
||
| ack_side | varchar | 应答方 |
|
||
| ack_status | varchar | 应答状态 |
|
||
| ack_time | timestamp | 应答时间 |
|
||
| remark | varchar | 备注 |
|
||
|
||
## 12. 幂等与一致性设计
|
||
|
||
### 12.1 幂等键建议
|
||
|
||
建议以如下组合作为幂等键：
|
||
|
||
```text
|
||
direction + sourceVersion + contentHash
|
||
```
|
||
|
||
约束效果：
|
||
|
||
- 已经处理过的包不能重复推送
|
||
- 已经提交过的生产快照不能重复写 Git
|
||
|
||
### 12.2 一致性策略
|
||
|
||
本方案属于跨系统、跨网络的异步同步，不适合做强一致事务。
|
||
|
||
建议采用：
|
||
|
||
- “本地落库 + 外部调用 + 最终一致”模式
|
||
- 每一步记录状态
|
||
- 失败后允许自动重试或人工补偿
|
||
|
||
## 13. 失败处理与补偿机制
|
||
|
||
### 13.1 自动重试
|
||
|
||
以下场景建议自动重试：
|
||
|
||
- FTP 上传失败
|
||
- FTP 下载失败
|
||
- 生产 `push` 接口调用失败
|
||
- 生产 `pull` 接口调用失败
|
||
- Git push 失败
|
||
|
||
建议策略：
|
||
|
||
- 最大重试次数：`3 ~ 5`
|
||
- 重试间隔：指数退避，例如 `30s / 60s / 120s`
|
||
|
||
### 13.2 失败归档
|
||
|
||
连续失败后建议：
|
||
|
||
- 将包移动到 FTP 的 `/failed/`
|
||
- 将任务状态置为 `FAILED`
|
||
- 记录完整错误信息
|
||
- 触发告警
|
||
|
||
### 13.3 人工补偿
|
||
|
||
后续可以增加一个管理接口，支持：
|
||
|
||
- 按 `traceId` 重新执行
|
||
- 重置任务状态
|
||
- 查看失败原因
|
||
|
||
## 14. 安全设计
|
||
|
||
### 14.1 传输安全
|
||
|
||
优先级建议如下：
|
||
|
||
1. 优先使用 `FTPS`
|
||
2. 如果只能使用普通 FTP，建议对同步包内容做 AES 加密
|
||
|
||
### 14.2 凭据管理
|
||
|
||
以下信息不得写死在代码中：
|
||
|
||
- FTP 地址、端口、用户名、密码
|
||
- Git 用户名、密码或 Token
|
||
- 生产接口认证信息
|
||
|
||
建议通过以下方式外置：
|
||
|
||
- `application-*.properties`
|
||
- 环境变量
|
||
- 启动参数
|
||
|
||
### 14.3 审计日志
|
||
|
||
建议记录：
|
||
|
||
- 谁发起了同步
|
||
- 同步方向
|
||
- 来源版本
|
||
- 包名
|
||
- 接口调用结果
|
||
- 异常原因
|
||
|
||
## 15. 项目结构建议
|
||
|
||
有两种实现方式。
|
||
|
||
### 15.1 方案 A：单工程 + Profile 切换
|
||
|
||
适用于项目规模较小、交付快的场景。
|
||
|
||
```text
|
||
sync-tool
|
||
|- src/main/java
|
||
| |- config
|
||
| |- ftp
|
||
| |- git
|
||
| |- job
|
||
| |- package
|
||
| |- repository
|
||
| |- service
|
||
| |- web
|
||
|- src/main/resources
|
||
| |- application.properties
|
||
| |- application-dev-agent.properties
|
||
| |- application-prod-agent.properties
|
||
```
|
||
|
||
### 15.2 方案 B：多模块拆分
|
||
|
||
适用于后续可能演化较多、职责更清晰的场景。
|
||
|
||
```text
|
||
sync-tool
|
||
|- common
|
||
|- dev-agent
|
||
|- prod-agent
|
||
```
|
||
|
||
当前建议优先采用：
|
||
|
||
- `方案 A：单工程 + Profile`
|
||
|
||
理由：
|
||
|
||
- 实现成本低
|
||
- 运维简单
|
||
- 早期更适合快速打通链路
|
||
|
||
## 16. 核心模块划分
|
||
|
||
建议按职责拆分以下模块：
|
||
|
||
- `GitService`
|
||
- 拉取仓库
|
||
- 检查最新提交
|
||
- 提交并推送生产回传配置
|
||
- `FtpService`
|
||
- 上传、下载、重命名、目录扫描
|
||
- `PackageService`
|
||
- 生成 zip
|
||
- 生成 manifest
|
||
- 校验 hash
|
||
- `SyncTaskService`
|
||
- 任务创建
|
||
- 状态变更
|
||
- 检查点维护
|
||
- `ProdPushService`
|
||
- 调用生产 `push` 接口
|
||
- `ProdPullService`
|
||
- 调用生产 `pull` 接口
|
||
- `AckService`
|
||
- 生成和消费 ack 文件
|
||
- `JobScheduler`
|
||
- 各类定时任务调度
|
||
|
||
## 17. 定时任务建议
|
||
|
||
### 17.1 开发侧任务
|
||
|
||
- `GitPullJob`
|
||
- 周期拉取 Git 并检查是否有新配置
|
||
- `UploadDevPackageJob`
|
||
- 将待同步配置上传到 FTP
|
||
- `ConsumeProdPackageJob`
|
||
- 下载生产回传包并写入 Git
|
||
- `AckScanJob`
|
||
- 扫描生产侧 ack 并更新任务状态
|
||
|
||
### 17.2 生产侧任务
|
||
|
||
- `ConsumeDevPackageJob`
|
||
- 下载开发侧同步包并调用生产 `push`
|
||
- `PullProdConfigJob`
|
||
- 定时调用生产 `pull` 接口
|
||
- `UploadProdPackageJob`
|
||
- 将拉取结果上传到 FTP
|
||
- `AckScanJob`
|
||
- 扫描开发侧 ack 并更新任务状态
|
||
|
||
## 18. 一期 MVP 建议
|
||
|
||
建议按最小可交付版本分阶段实施。
|
||
|
||
### 阶段 1：打通主链路
|
||
|
||
- 建立 Spring Boot 工程
|
||
- 集成 H2、JGit、FTP
|
||
- 实现开发到生产的全量包同步
|
||
- 实现生产 `push` 接口调用
|
||
|
||
### 阶段 2：打通回传链路
|
||
|
||
- 接入生产 `pull` 接口
|
||
- 实现生产到开发的 FTP 回传
|
||
- 实现开发侧写入 Git 并推送
|
||
|
||
### 阶段 3：增强稳定性
|
||
|
||
- 增加重试
|
||
- 增加 ack 机制
|
||
- 增加失败归档
|
||
- 增加告警与审计日志
|
||
|
||
## 19. 风险与注意事项
|
||
|
||
### 19.1 最大风险：双向同步闭环
|
||
|
||
如果生产回传配置写入开发主分支，再被开发侧识别为“新配置”，会再次推送到生产，形成无限循环。
|
||
|
||
规避措施：
|
||
|
||
- 使用独立镜像分支
|
||
- 识别机器人提交
|
||
- 使用幂等键
|
||
|
||
### 19.2 配置冲突风险
|
||
|
||
如果开发和生产都会修改同一份配置，且要求双向合并，则不能简单用文件覆盖方式处理。
|
||
|
||
当前建议：
|
||
|
||
- 将生产回传定义为“镜像/审计”
|
||
- 不直接回写开发主配置分支
|
||
|
||
### 19.3 FTP 能力限制
|
||
|
||
如果 FTP 不支持原子重命名、目录权限受限或稳定性较差，需要额外做兼容与重试。
|
||
|
||
## 20. 结论
|
||
|
||
在当前网络条件下，推荐采用“**开发代理 + 生产代理 + FTP 中转 + H2 状态库**”的双端部署方案。
|
||
|
||
该方案具备以下特点：
|
||
|
||
- 不依赖开发与生产直接互通
|
||
- 满足开发到生产、生产到开发的双向同步需求
|
||
- 支持状态记录、失败重试、幂等控制和审计追踪
|
||
- 适合使用 `Java 1.8 + Spring Boot 2.7.18` 快速落地
|
||
|
||
## 21. 后续可继续细化内容
|
||
|
||
后续可以基于本方案继续输出：
|
||
|
||
- `application.properties` 配置项设计
|
||
- H2 建表 SQL
|
||
- 核心类图与接口设计
|
||
- 各定时任务的时序与状态流转
|
||
- Spring Boot 工程骨架
|