strepsiades
144 lines
6.1 KiB
Markdown
144 lines
6.1 KiB
Markdown
# 运行配置业务说明
|
||
|
||
本文档从业务视角说明配置字段含义、对阶段行为的影响，以及推荐的覆盖方式。
|
||
|
||
## 1. 推荐使用方式（先 default，再覆盖）
|
||
|
||
1. 先使用基线配置运行：
|
||
- `run_profiles/preset/jsonl_to_jsonl.default.yaml`
|
||
2. 若需项目定制，再复制为：
|
||
- `run_profiles/jsonl_to_jsonl.local.yaml`
|
||
3. 仅改有业务差异的字段，避免一次改太多导致排障困难。
|
||
|
||
占位符：
|
||
- `${PROJECT_ROOT}` 会在运行时替换为项目根目录绝对路径。
|
||
|
||
## 2. 顶层字段（你在改什么）
|
||
|
||
- `node_types`
|
||
- 本轮参与同步的业务类型列表。
|
||
- 顺序会影响依赖链执行时机（当前按 node_type 串行执行 bind/create/update）。
|
||
- `target_project_ids`
|
||
- 兼容字段。作为两侧 datasource 的项目白名单兜底值。
|
||
- 若 datasource 自身配置了 `target_project_ids`，则优先使用 datasource 级配置。
|
||
- `local_datasource` / `remote_datasource`
|
||
- 分别定义两侧数据来源与执行端。
|
||
- `strategies`
|
||
- 每个业务类型的行为策略（依赖、自动绑定、创建方向、更新方向、跳过等）。
|
||
- `persist`
|
||
- 持久化开关与数据库位置。
|
||
- `logging`
|
||
- 运行日志输出位置与级别。
|
||
|
||
## 3. 数据源字段（DataSource）
|
||
|
||
### 3.1 JSONL 数据源
|
||
|
||
- `type=jsonl`：使用本地 JSONL 文件作为数据源。
|
||
- `jsonl_dir`：JSONL 目录路径。
|
||
- `read_only=false`：允许该侧执行 create/update 回写；若为 true，通常用于只读加载。
|
||
- `target_project_ids=[]`：该侧项目白名单；为空时不进行项目筛选。
|
||
- `handler_configs`：预留给各业务 handler 的扩展参数。
|
||
|
||
### 3.2 API 数据源
|
||
|
||
- `type=api`：对接 HTTP API。
|
||
- `api_base_url` / `api_uid` / `api_secret`：接口访问参数。
|
||
- `api_debug`：开启后输出更多调试信息。
|
||
- `poll_max_retries` / `poll_interval`：异步任务轮询次数与间隔。
|
||
- `target_project_ids`：**必填**，该侧项目白名单；至少需要指定一个项目ID，以避免加载过多远程数据。
|
||
- `handler_configs`：业务 handler 扩展参数。
|
||
|
||
## 4. 策略字段（Strategy）
|
||
|
||
每个 node_type 都建议显式写出以下字段，便于审阅与排障。
|
||
|
||
### 4.1 `update_direction`
|
||
|
||
- `push`：本地变更推送到远端。
|
||
- `pull`：远端变更拉取到本地。
|
||
- `bidirectional`：双向更新（需要明确冲突策略，谨慎使用）。
|
||
- `none`：关闭 update 阶段。
|
||
|
||
### 4.2 `local_orphan_action` / `remote_orphan_action`
|
||
|
||
- `create_remote`：本地孤儿创建到远端。
|
||
- `create_local`：远端孤儿创建到本地。
|
||
- `none`：不自动创建。
|
||
- `delete_local` / `delete_remote`：当前主流程未作为默认路径，谨慎使用。
|
||
|
||
### 4.3 `auto_bind` / `auto_bind_fields` / `pre_bind_data_id`
|
||
|
||
- `auto_bind=true`：在 `S02(MISSING)` 上尝试自动匹配。
|
||
- `auto_bind=false`：不会做自动匹配，也不会走自动创建识别路径；通常会进入阻断态等待人工处理。
|
||
- `auto_bind_fields`：自动匹配使用的业务键字段。
|
||
- `pre_bind_data_id`：显式 data_id 预绑定清单（通用能力），格式为：
|
||
- `- local_data_id: "..."`
|
||
` remote_data_id: "..."`
|
||
- 规则：若两侧数据源都存在这对 data_id 对应节点，且当前无绑定记录，则直接绑定。
|
||
- 不依赖 `auto_bind/auto_bind_fields`，即使 `auto_bind=false` 也会执行。
|
||
- 不做业务键一对一匹配检查，按你给定的映射对优先执行。
|
||
|
||
### 4.4 `depend_fields`
|
||
|
||
- 定义依赖字段到依赖 node_type 的映射，例如：`company_id -> company`。
|
||
- 依赖节点状态非 `NORMAL` 时，会在 bind 的依赖检查阶段进入 `DEPENDENCY_ERROR`。
|
||
|
||
### 4.5 `skip_sync`
|
||
|
||
- 运行配置中已不建议使用 `skip_sync`。
|
||
- 推荐使用显式组合：
|
||
- `local_orphan_action: none`
|
||
- `remote_orphan_action: none`
|
||
- `update_direction: none`
|
||
- 当三者同时为 `none/none/none` 时，pipeline 会跳过该 node_type 的 bind/create/update。
|
||
|
||
### 4.6 Handler 级参数（`handler_configs`）
|
||
|
||
- 建议将 handler 特有参数放在 datasource 的 `handler_configs.<node_type>` 下。
|
||
- 示例：
|
||
- `remote_datasource.handler_configs.supplier.load_mode: persisted_only`
|
||
- `persisted_only` 表示只使用已持久化数据，不主动从外部拉新数据（具体以对应 handler 实现为准）。
|
||
|
||
## 5. 阶段行为与配置关系
|
||
|
||
- bind 阶段
|
||
- `depend_fields` 决定是否做依赖校验。
|
||
- `pre_bind_data_id` 先按显式 local/remote data_id 映射做预绑定。
|
||
- `auto_bind/auto_bind_fields` 决定是否继续进行业务键自动绑定。
|
||
- create 阶段
|
||
- `local_orphan_action` / `remote_orphan_action` 决定孤儿是否创建。
|
||
- update 阶段
|
||
- `update_direction` 决定是否和向哪侧更新。
|
||
- 写入后 reload（Pipeline 内置）
|
||
- 当某个 node_type 的 create 或 update 发生实际写入成功后，pipeline 会自动对该 node_type 重新执行两侧 `load`。
|
||
- 目的：让后续 update 判断基于最新远端/本地数据，支持“create 后再补一次 update”的链路。
|
||
- 同步后一致性检查（Pipeline 内置）
|
||
- 每个 node_type 在本轮同步后会基于绑定对执行数据一致性校验（比较时忽略 `id/_id` 字段）。
|
||
- 若发现差异，会在日志中打印差异样本，并在汇总表新增 `Consistent` 列展示 `Y` / `N(差异数)`。
|
||
- 全局跳过
|
||
- `local_orphan_action=none` + `remote_orphan_action=none` + `update_direction=none`
|
||
可直接跳过该类型的 bind/create/update。
|
||
|
||
## 6. 覆盖配置建议
|
||
|
||
- 先在 default 跑通一轮，再做 local 覆盖。
|
||
- 每次只改一类问题相关字段（例如只改 `project` 的依赖与自动绑定）。
|
||
- 覆盖后优先看 `sync_log` 是否出现预期状态迁移。
|
||
|
||
## 7. 持久化与日志字段
|
||
|
||
### `persist`
|
||
|
||
- `enable`：是否开启持久化。
|
||
- `db_path`：SQLite 路径。
|
||
- `wipe_on_start`：启动是否清理历史持久化。
|
||
|
||
### `logging`
|
||
|
||
- `file_dir`：日志目录。
|
||
- `file_name_pattern`：文件命名模板。
|
||
- `level`：日志级别。
|
||
|
||
排障建议：运行失败时优先看日志中的 `状态机流转` 与 `reason=`，再对照 `docs/state_machine.md` 与 `docs/node_state_definition.md` 理解含义。
|