dark/FtpTool

Fork 0

dark 00b81bf7ef feat:支持正则匹配轮询分支

2026-04-28 17:00:58 +08:00

7.0 KiB

Raw Permalink Blame History

Git 直连架构详细设计

1. 文档说明

本文档描述当前实现层面的详细设计，重点覆盖：

Git 版本分支和目录结构约定
Git -> PROD 的增量与参数映射逻辑
PROD -> Git 的落盘与回写逻辑
运行配置、工作目录和已知限制

2. 当前推荐部署

当前推荐只部署：

prod-agent

运行要求：

能访问开发 Git
能向 Git 推送 snapshotBranch
能访问生产 push/pull/login 接口
能写本地 H2 文件数据库

3. 配置文件策略

当前使用：

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

说明：

application.properties 提供公共默认值
application-prod-agent.properties 提供生产侧 profile 配置

4. 核心配置口径

4.1 Git 配置

配置项	说明
`git.repo.remote-uri`	Git 远端地址
`git.repo.username`	Git 用户名
`git.repo.password`	Git 密码或 token
`git.repo.scan-branch`	当前待同步的单个版本分支名
`git.repo.scan-branch-pattern`	批量扫描的版本分支匹配规则
`git.repo.snapshot-branch`	动态生产快照分支前缀
`git.repo.commit-message-prefix`	PROD -> Git 提交前缀

4.2 生产接口配置

配置项	说明
`prod.api.base-url`	生产接口基础地址
`prod.api.push-path`	`pushConfig` 路径
`prod.api.pull-path`	`pullConfig` 路径
`prod.api.login-path`	`login` 路径
`prod.api.token`	静态 token，可选
`prod.api.token-header-name`	token 请求头名称
`prod.api.airport-id`	`pullConfig` 可选过滤
`prod.api.app-name`	`pullConfig` 可选过滤
`prod.api.pull-config-version`	`pullConfig` 可选版本过滤
`prod.api.pull-file-name`	`pullConfig` 可选文件过滤

说明：

prod.api.airport-id、prod.api.app-name 当前只用于 pullConfig 的可选过滤
它们已经不再用于 Git -> PROD 参数解析

4.3 调度配置

当前生产侧调度：

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

5. Git 仓库约定

5.1 版本分支

当前实现约定：

Git -> PROD 支持两种入口：
- git.repo.scan-branch：单分支定向同步
- git.repo.scan-branch-pattern：批量枚举版本分支
分支名本身就是 configVersion

例如：

R_XXX_V3.0.3_XXX

5.2 分支内目录结构

当前分支内目录必须为：

<airportId>/<appName>/<模块内文件相对路径>

示例：

R_XXX_V3.0.3_XXX
├─ PEK
│  └─ monitor
│     ├─ application.yml
│     └─ jobs/sync-job.json
└─ SHA
   └─ gate
      └─ gate-rule.json

5.3 路径校验

当前实现要求每个待推送文件都至少有 3 段路径：

airportId / appName / fileName

否则直接视为非法仓库结构并终止同步。

6. 工作目录设计

当前工作目录：

work/
├─ package/
├─ staging/
│  ├─ dev-to-prod/
│  └─ prod-to-dev/
└─ baseline/
   └─ git-to-prod/
      └─ <scan-branch>/

说明：

dev-to-prod/：保存导出的 Git 版本快照与增量目录
prod-to-dev/：保存 pullConfig 恢复出的临时目录
baseline/git-to-prod/<scan-branch>/：保存某个版本分支上次成功下发后的基线

7. Git -> PROD 详细流程

7.1 流程步骤

解析单分支或批量匹配规则
逐个拉取命中的版本分支
读取当前 HEAD revision
以分支名作为 sourceVersion
导出分支工作树到 staging 目录
计算目录内容哈希
按 direction + sourceVersion + contentHash 做幂等判断
计算本次推送目录：
- 首次全量
- 删除回退全量
- 其余场景最小增量
遍历目录内所有文件，按路径解析出 airportId/appName/fileName
组装 pushConfig JSON 数组并提交
成功后刷新 checkpoint、task 和 baseline

7.2 参数映射规则

Git 信息	pushConfig 字段
`scan-branch`	`configVersion`
路径第 1 段	`airportId`
路径第 2 段	`appName`
第 3 段及之后	`fileName`
文件 UTF-8 内容	`configContent`

7.3 当前实现说明

HEAD revision 仅用于日志和 staging 目录名
不再用 commit SHA 作为对外业务版本号
configContent 目前仍是明文

8. PROD -> Git 详细流程

8.1 流程步骤

调用 pullConfig
可选附带 airportId/appName 过滤
自动附带本地待回传的 ackSuc/ackFail
解析响应项
按 airportId/appName/fileName 落盘到 staging 目录
计算内容哈希和来源版本
按幂等键判断是否已处理
提交到 git.repo.snapshot-branch/<configVersion>
成功后更新 checkpoint、task 和本地 ACK 状态

8.2 来源版本规则

当前实现：

如果本次 pullConfig 返回项里的 configVersion 全部一致，则该值作为 sourceVersion
如果返回多种不同 configVersion，则退回为内容哈希

8.3 动态快照分支规则

每个 ProdPullResult 都会写入独立目标分支：

git.repo.snapshot-branch/<sourceVersion>

当 sourceVersion 就是接口返回的统一 configVersion 时，目标分支即按版本动态展开
当某组缺少版本号时，会退回为基于内容哈希的 sourceVersion

9. 当前接口协议实现口径

9.1 pushConfig

方法：POST
载荷：JSON 数组
每个文件一条记录
ackFail 非空时本次同步直接失败
configContent 已统一通过 ConfigCryptoService 处理，当前默认实现仍为透传

9.2 pullConfig

方法：GET
参数：query string
当前已支持：
- airportId
- appName
- ackSuc
- ackFail
当前已支持：
- configVersion
- fileName
对于本地处理失败的 ackFail 项，当前会持久化重试上下文，并在下一个周期按 airportId/appName/configVersion/fileName 定向重拉

方法：POST
如果未配置静态 token，则自动调用
token 会按 expireTime 缓存

10. 状态表设计

当前主表：

sync_checkpoint
sync_task
prod_pull_ack

作用：

sync_checkpoint：方向级最后成功版本和哈希
sync_task：任务状态、重试次数、错误摘要
prod_pull_ack：待回传给生产侧的 ACK 状态

11. 当前已实现能力

Git -> PROD 主链路已可用
PROD -> Git 主链路已可用
pushConfig/pullConfig/login 已适配正式协议
ackSuc/ackFail 已接入回传与本地落库
Git -> PROD 已支持最小增量推送
管理接口已提供最近任务、失败任务和检查点视图

12. 当前主要 TODO

将 ConfigCryptoService 的透传实现替换为正式加解密算法

13. 结论

当前详细设计已经不再是“固定主分支 + 全局机场配置”的口径，而是：

版本靠分支表达
机场和模块靠目录表达
路径直接决定接口参数

后续再扩展功能时，应在这个模型上继续演进。

7.0 KiB Raw Permalink Blame History Unescape Escape