dark 114bcf33d8 feat: 同步链路支持版本分支目录映射、动态快照分支和 ackFail 定向重拉

- Git -> PROD 改为按 branch 作为 configVersion
- 按 airportId/appName/fileName 目录结构解析 pushConfig 参数
- PROD -> Git 改为写入 snapshot-branch/<configVersion> 动态分支
- pullConfig 支持 configVersion/fileName 可选过滤
- 抽出 ConfigCryptoService，统一收口加解密扩展点
- ackFail 落库增加重试上下文，支持按 airportId/appName/configVersion/fileName 定向重拉
- 同步更新测试、接口文档和 current.md

2026-04-28 14:49:33 +08:00

5.3 KiB

Raw Blame History

Git 直连架构补充方案

1. 背景变化

旧方案依赖：

开发环境 -> FTP -> 生产环境

当前条件已经变为：

FTP 不再使用
生产环境可以直接访问开发 Git
生产侧继续通过 pushConfig/pullConfig/login 接口与业务系统交互

因此当前架构已经收敛为：

单端代理 + Git 直连 + 本地状态库

2. 新架构结论

当前推荐只在生产环境部署一套同步服务：

prod-agent

整体拓扑：

开发 Git 仓库 <----> 生产环境 prod-agent <----> 生产系统 push/pull 接口

3. Git 仓库模型

3.1 版本分支

当前需求下：

每个待下发版本对应一个 Git 分支
git.repo.scan-branch 指向当前待同步的版本分支
分支名本身就是 configVersion

例如：

R_XXX_V3.0.3_XXX
R_XXX_V3.0.4_XXX

3.2 分支内目录结构

每个版本分支内目录必须为：

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

示例：

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

3.3 当前快照分支

当前实现使用“固定前缀 + 动态版本段”的快照分支：

git.repo.snapshot-branch

PROD -> Git 会把生产拉回的配置写入：

git.repo.snapshot-branch/<configVersion>

分支内目录结构同样为：

<airportId>/<appName>/<fileName>

说明：

git.repo.snapshot-branch 当前表示分支前缀，不再是唯一固定目标分支
实际写入目标由 sourceVersion/configVersion 动态展开

4. 两条核心链路

4.1 Git -> PROD

流程：

prod-agent 拉取 git.repo.scan-branch 指定的版本分支
读取当前 HEAD revision，仅用于日志和 staging 隔离
以 分支名 作为 sourceVersion/configVersion
导出分支工作树
按 airportId/appName/fileName 解析所有配置文件
调用生产 pushConfig
成功后更新本地检查点和任务状态

4.2 PROD -> Git

流程：

prod-agent 调用生产 pullConfig
读取返回项中的 airportId/appName/fileName
恢复到本地 staging 目录
计算内容哈希和来源版本
提交到 git.repo.snapshot-branch/<configVersion>
成功后更新本地检查点和任务状态

5. 当前实现细节

5.1 Git -> PROD 版本语义

当前代码已经调整为：

sourceVersion = git.repo.scan-branch
不再使用 commit SHA 作为业务版本号

HEAD revision 仍然保留，但仅用于：

staging 目录命名
日志排查

5.2 增量推送

当前实现：

首次推送走全量
后续和本地 baseline 做对比
无删除时只推变更文件
检测到删除时自动回退为全量

并且 baseline 已按版本分支隔离，避免不同版本分支之间相互污染。

5.3 pushConfig 参数映射

当前映射关系如下：

airportId = Git 路径第 1 段
appName = Git 路径第 2 段
fileName = 模块内相对路径
configVersion = 当前版本分支名

5.4 pullConfig 回写结构

当前回写目录：

<airportId>/<appName>/<fileName>

因此 snapshotBranch 应当被视为快照分支前缀，不建议在该前缀下混入其他开发分支。

6. 状态管理

当前继续保留：

sync_checkpoint
sync_task
prod_pull_ack

作用分别是：

sync_checkpoint：记录某个方向最后一次成功版本和哈希
sync_task：记录同步任务生命周期和重试状态
prod_pull_ack：记录下次 pullConfig 需要回传的 ackSuc/ackFail

7. 幂等设计

当前幂等键仍然是：

direction + sourceVersion + contentHash

在 Git -> PROD 场景下：

sourceVersion = 版本分支名

在 PROD -> Git 场景下：

sourceVersion 优先取 pullConfig 返回的统一 configVersion
如果返回多版本混合数据，则退回为内容哈希

8. 当前配置口径

8.1 Git 配置

git.repo.scan-branch=R_XXX_V3.0.3_XXX
git.repo.snapshot-branch=config-prod-snapshot

说明：

scan-branch 当前应直接配置为待同步版本分支名
snapshot-branch 当前表示动态快照分支前缀

8.2 生产接口配置

prod.api.base-url=https://prod.example.com
prod.api.push-path=/pic_bus_manage_monitor/configSync/pushConfig
prod.api.pull-path=/pic_bus_manage_monitor/configSync/pullConfig
prod.api.login-path=/pic_bus_manage_monitor/pam-monitor/login
prod.api.token=replace-me
prod.api.token-header-name=token
prod.api.airport-id=
prod.api.app-name=
prod.api.pull-config-version=
prod.api.pull-file-name=

说明：

prod.api.airport-id、prod.api.app-name 不再用于 Git -> PROD 参数解析
它们当前只作为 pullConfig 的可选过滤参数
prod.api.pull-config-version、prod.api.pull-file-name 可用于精细过滤拉取范围

9. 当前仍保留的 TODO

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

10. 结论

当前最重要的变化不是“继续抽象通用分支”，而是先把仓库约定和接口参数映射对齐：

版本用分支表达
机场和模块用目录表达
生产接口参数由路径直接解析

这一层已经进入正式实现口径，后续文档和代码都应以此为准。

5.3 KiB Raw Blame History