114bcf33d8
- Git -> PROD 改为按 branch 作为 configVersion - 按 airportId/appName/fileName 目录结构解析 pushConfig 参数 - PROD -> Git 改为写入 snapshot-branch/<configVersion> 动态分支 - pullConfig 支持 configVersion/fileName 可选过滤 - 抽出 ConfigCryptoService，统一收口加解密扩展点 - ackFail 落库增加重试上下文，支持按 airportId/appName/configVersion/fileName 定向重拉 - 同步更新测试、接口文档和 current.md
238 lines
5.3 KiB
Markdown
238 lines
5.3 KiB
Markdown
# Git 直连架构补充方案
|
|
|
|
## 1. 背景变化
|
|
|
|
旧方案依赖：
|
|
|
|
- 开发环境 -> FTP -> 生产环境
|
|
|
|
当前条件已经变为：
|
|
|
|
- FTP 不再使用
|
|
- 生产环境可以直接访问开发 Git
|
|
- 生产侧继续通过 `pushConfig/pullConfig/login` 接口与业务系统交互
|
|
|
|
因此当前架构已经收敛为：
|
|
|
|
- **单端代理 + Git 直连 + 本地状态库**
|
|
|
|
## 2. 新架构结论
|
|
|
|
当前推荐只在生产环境部署一套同步服务：
|
|
|
|
- `prod-agent`
|
|
|
|
整体拓扑：
|
|
|
|
```text
|
|
开发 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 分支内目录结构
|
|
|
|
每个版本分支内目录必须为：
|
|
|
|
```text
|
|
<airportId>/<appName>/<模块内文件相对路径>
|
|
```
|
|
|
|
示例：
|
|
|
|
```text
|
|
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` 会把生产拉回的配置写入：
|
|
|
|
```text
|
|
git.repo.snapshot-branch/<configVersion>
|
|
```
|
|
|
|
分支内目录结构同样为：
|
|
|
|
```text
|
|
<airportId>/<appName>/<fileName>
|
|
```
|
|
|
|
说明：
|
|
|
|
- `git.repo.snapshot-branch` 当前表示分支前缀，不再是唯一固定目标分支
|
|
- 实际写入目标由 `sourceVersion/configVersion` 动态展开
|
|
|
|
## 4. 两条核心链路
|
|
|
|
### 4.1 Git -> PROD
|
|
|
|
流程：
|
|
|
|
1. `prod-agent` 拉取 `git.repo.scan-branch` 指定的版本分支
|
|
2. 读取当前 `HEAD revision`，仅用于日志和 staging 隔离
|
|
3. 以 **分支名** 作为 `sourceVersion/configVersion`
|
|
4. 导出分支工作树
|
|
5. 按 `airportId/appName/fileName` 解析所有配置文件
|
|
6. 调用生产 `pushConfig`
|
|
7. 成功后更新本地检查点和任务状态
|
|
|
|
### 4.2 PROD -> Git
|
|
|
|
流程：
|
|
|
|
1. `prod-agent` 调用生产 `pullConfig`
|
|
2. 读取返回项中的 `airportId/appName/fileName`
|
|
3. 恢复到本地 staging 目录
|
|
4. 计算内容哈希和来源版本
|
|
5. 提交到 `git.repo.snapshot-branch/<configVersion>`
|
|
6. 成功后更新本地检查点和任务状态
|
|
|
|
## 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 回写结构
|
|
|
|
当前回写目录：
|
|
|
|
```text
|
|
<airportId>/<appName>/<fileName>
|
|
```
|
|
|
|
因此 `snapshotBranch` 应当被视为快照分支前缀，不建议在该前缀下混入其他开发分支。
|
|
|
|
## 6. 状态管理
|
|
|
|
当前继续保留：
|
|
|
|
- `sync_checkpoint`
|
|
- `sync_task`
|
|
- `prod_pull_ack`
|
|
|
|
作用分别是：
|
|
|
|
- `sync_checkpoint`：记录某个方向最后一次成功版本和哈希
|
|
- `sync_task`：记录同步任务生命周期和重试状态
|
|
- `prod_pull_ack`：记录下次 `pullConfig` 需要回传的 `ackSuc/ackFail`
|
|
|
|
## 7. 幂等设计
|
|
|
|
当前幂等键仍然是：
|
|
|
|
```text
|
|
direction + sourceVersion + contentHash
|
|
```
|
|
|
|
在 Git -> PROD 场景下：
|
|
|
|
- `sourceVersion` = 版本分支名
|
|
|
|
在 PROD -> Git 场景下：
|
|
|
|
- `sourceVersion` 优先取 `pullConfig` 返回的统一 `configVersion`
|
|
- 如果返回多版本混合数据，则退回为内容哈希
|
|
|
|
## 8. 当前配置口径
|
|
|
|
### 8.1 Git 配置
|
|
|
|
```properties
|
|
git.repo.scan-branch=R_XXX_V3.0.3_XXX
|
|
git.repo.snapshot-branch=config-prod-snapshot
|
|
```
|
|
|
|
说明：
|
|
|
|
- `scan-branch` 当前应直接配置为待同步版本分支名
|
|
- `snapshot-branch` 当前表示动态快照分支前缀
|
|
|
|
### 8.2 生产接口配置
|
|
|
|
```properties
|
|
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. 结论
|
|
|
|
当前最重要的变化不是“继续抽象通用分支”，而是先把仓库约定和接口参数映射对齐：
|
|
|
|
- 版本用分支表达
|
|
- 机场和模块用目录表达
|
|
- 生产接口参数由路径直接解析
|
|
|
|
这一层已经进入正式实现口径，后续文档和代码都应以此为准。
|