Harmon/insar-management-system-v2

Fork 0

Files

T

Harmon cb518b431f Apply current workspace changes

2026-04-22 01:52:21 +08:00

18 KiB

Raw Blame History

PyINT + Gamma 集成总体设计

日期: 2026-04-18
状态: 总体设计
范围: D-InSAR 生产引擎接入、Gamma 精配对接入、配置管理、数据库策略、运维自检、前端入口

1. 结论

本次集成建议采用两条并行但相互衔接的路线：

将 PyINT 作为新的 D-InSAR 生产引擎接入现有多引擎框架，统一走现有任务队列、运行日志、结果登记与结果目录治理链路。
将 Gamma 配对能力接入现有“配对基础 -> 配对规划 -> 生产执行”链路，作为数据库粗配对结果之上的精化步骤，而不是替换当前配对基础缓存。

核心判断如下：

PyINT 更适合作为“受控外部引擎”集成，而不是直接作为后端内部 Python 库深度嵌入。
Gamma 精配对是可集成的，但更适合针对“已经筛出的场景集合/网络运行”做二次优化，不适合直接取代当前全库候选对缓存。
一期集成建议不强制修改数据库主结构；优先复用现有 pairing_network_runs / pairing_network_edges 的 JSON 承载精配对元数据。
如果二期需要对 Gamma 精配对历史做独立检索、统计和运维闭环，再引入单独迁移文件，并通过现有数据库自维护机制自动落库。

2. 现状与约束

2.1 当前系统已有基础

已有 D-InSAR 多引擎抽象：backend/app/dinsar_engines/base.py
已有引擎注册表：backend/app/dinsar_engines/registry.py
已有生产任务接口与队列：backend/app/routers/dinsar_production.py
已有配对基础缓存、网络运行与边追踪：
- backend/app/models/orm.py
- backend/app/services/pairing_cache_service.py
- backend/app/services/pairing_state_service.py
- backend/app/services/spatial_service.py
已有数据库自维护与 SQL 迁移自动执行：backend/app/db_maintenance.py
已有运维自检面板与健康检查汇总：backend/app/services/health_service.py、frontend/src/HealthCheckPanel.jsx
已有生产页与配对规划页：
- frontend/src/DinsarProductionPanel.jsx
- frontend/src/panels/PairPlanningPanel.jsx

2.2 PyINT 项目特征

从 D:\Code\PyINT 现状看，PyINT 不是干净的 SDK，而是以模板和脚本为中心的流程编排层：

主入口为 pyint/pyintApp.py
配对能力入口为 pyint/select_pairs.py
严重依赖环境变量：
- SCRATCHDIR
- TEMPLATEDIR
- DEMDIR
运行方式偏 Linux / WSL，广泛调用外部命令与 GAMMA CLI
更适合作为“流程执行器”被调用，而不是被后端直接 import 后逐步复用内部函数

2.3 明确约束

本机只有一个 WSL 环境，不需要设计多 distro 调度系统。
系统级 Windows Python 解释器已经在根 .env 中维护，可复用，不应再为 PyINT 额外复制一套 Windows Python 配置。
管理员口令不应进入设计文档、代码或 .env.example。权限控制继续复用现有登录态与管理员角色校验。
现有运维自检面板已经较重，PyINT/Gamma 的“操作入口”不应继续堆在健康检查页里。

3. 总体集成架构

3.1 总体原则

不新建平行子系统，优先复用现有引擎、作业、配对、结果目录与目录扫描体系。
不改变现有 pairing_metric_cache.spatial_baseline_meters 的语义。
不把 Gamma 精配对结果直接覆盖数据库粗配对缓存。
运维页只看状态，实际操作放在生产页与配对规划页。

3.2 架构分层

A. 生产引擎层

新增 pyint 引擎，挂到现有 registry 中，与 sarscape / isce2 / landsar 并列。

B. WSL 执行适配层

新增受控执行服务，负责：

读取 .env 配置
复用现有 WSL 命令执行与路径转换能力
组装 PyINT 所需环境变量
生成模板文件和运行目录
执行 PyINT 包装脚本
将输出归一化到系统现有结果结构

C. 配对精化层

保留现有数据库候选对缓存与网络运行。

在此基础上新增“Gamma 精配对”步骤：

先由当前配对接口生成候选网络
再将该网络对应场景集送入 Gamma / PyINT 配对流程
生成新的精化网络结果
前端允许用户查看并选择使用精化后的网络结果

D. 结果治理层

PyINT/Gamma 原始工作目录不直接作为系统正式结果。

必须经过适配层输出统一结果包，保证继续兼容：

结果目录扫描
结果目录发布
结果目录桥接一致性
预览图/缩略图生成
AI 诊断与 catalog 追踪

4. PyINT 生产引擎设计

4.1 目标

目标不是把 PyINT 原封不动暴露给用户，而是把它包装成当前系统理解的“一个可选生产引擎”。

4.2 推荐实现方式

新增以下后端组件：

backend/app/dinsar_engines/pyint_engine.py
backend/app/services/pyint_service.py
backend/app/pyint_pipeline/run_lt1_pyint_pipeline.py

职责划分：

pyint_engine.py
- 实现 DinsarEngine
- 暴露 engine_code=pyint
- 提供可用性检查、处理 profile、参数 schema
pyint_service.py
- WSL 执行
- 路径转换
- 模板写入
- 环境变量组装
- 烟测检查
run_lt1_pyint_pipeline.py
- 作为受控包装脚本在 WSL 中运行
- 负责把系统已有 Task_* / 配对任务目录映射成 PyINT 项目工作区
- 调用 pyintApp.py 或更细粒度子脚本
- 收集输出并生成系统结果清单

4.3 与当前生产链路的关系

沿用现有生产链路：

前端生产页 -> /dinsar-production/run -> job queue -> pyint_engine.run() -> WSL -> PyINT -> 统一结果包 -> catalog/scan

这样做的收益：

不需要新增独立任务中心
不需要新增另一套运行日志
不需要新增另一套前端生产入口
与当前 DinsarProductionPanel.jsx 的多引擎 UI 完全兼容

4.4 输入与工作区组织

建议一期仍以当前系统已有的任务目录为输入，不要求用户先手工构造原生 PyINT 项目。

推荐工作区结构：

系统输入根目录：沿用当前生产面板 root_dir
PyINT 工作根目录：系统管理目录，例如 backend/runtime/pyint_work
模板目录：系统管理目录，例如 backend/runtime/pyint_templates
每次运行独立 run_key
每个 pair/task 独立 workspace，避免相互污染

4.5 结果输出策略

PyINT 原始输出不能直接作为系统正式结果目录暴露。

推荐新增“输出归一化”步骤，将 PyINT/Gamma 输出转为系统现有 bundle 约定，至少包含：

结果主清单
关键输出文件路径
运行元数据
pair trace 信息
engine/profile 信息

必须保证与现有结果目录扫描机制兼容。

4.6 Profile 设计建议

一期建议只开放一个稳定 profile：

lt1_gamma_dinsar

不建议一开始把 PyINT 全部开关都暴露到前端。应只暴露对当前业务必要的参数，例如：

是否强制重跑
多视参数
相干阈值
geocode 开关
unwrap 开关
超时

其余细节由模板生成器按系统默认值填充。

5. Gamma 精配对设计

5.1 目标定位

Gamma 精配对不替代当前数据库候选对缓存，而是建立在现有候选网络之上的二次精化机制。

推荐定位为：

当前数据库配对：全库级、粗筛级、可快速响应
Gamma 精配对：项目级、网络级、精筛级、可生成更可靠的时空基线网络

5.2 推荐流程

用户在现有配对规划页完成粗配对查询
后端返回 network_run_id
用户在“Gamma 精配对”区域发起精化
系统根据该网络运行对应的场景集合，构建 PyINT/Gamma 工作区
调用 select_pairs.py / base_calc 生成精配对网络
后端将结果落回系统网络结果表示
前端展示“粗配对结果”和“Gamma 精配对结果”的对比摘要
用户选择使用哪一版网络继续生产

5.3 为什么不能直接覆盖当前 pairing cache

当前 pairing_metric_cache 里的 spatial_baseline_meters 已经在系统内承担既有语义与下游用途。
Gamma 计算出的垂直基线/网络属性与当前字段不等价，直接覆盖会带来语义混乱和回归风险。

因此必须坚持：

现有缓存保留原语义
Gamma 精配对结果单独存储
精配对结果仅作为网络选择依据，不回写粗配对主缓存

5.4 一期存储策略

一期推荐不新建强结构化表，优先复用：

pairing_network_runs.request_params_json
pairing_network_edges.selection_meta_json

建议约定写入内容：

refinement_engine: gamma_pyint
refinement_source_run_id
gamma_bperp_m
gamma_tbase_days
gamma_rank
gamma_ifgram_list_path
gamma_artifact_dir
gamma_selection_reason

同时新增一个新的 network_run_id，把“精配对结果”作为新的网络运行保存，而不是修改原粗配对运行。

这样做的收益：

一期可不改数据库结构
保留粗配对和精配对双轨结果，便于审计与回退
复用现有 network run / edge 追踪模型

5.5 二期可选扩展

如果后续有以下需求，再引入数据库迁移：

精配对历史独立检索
精配对任务状态长期统计
精配对工作区清理与资产追踪
精配对失败类型聚合运维

二期建议新增表，例如：

pairing_refinement_runs
pairing_refinement_artifacts

但这不是一期必须项。

6. 配置与运行管理方案

6.1 配置原则

Windows 侧解释器继续复用根 .env 中已有的 PYTHON_PATH
WSL 侧只维护 PyINT/Gamma 运行必须配置
因为本机只有一个 WSL 环境，PyINT 与 ISCE2 默认共用 distro

6.2 建议新增配置项

建议在 .env / .env.example / backend/app/config.py 中新增：

PYINT_ENABLED=false
PYINT_WSL_DISTRO=
PYINT_WSL_PYTHON=
PYINT_HOME=
PYINT_APP_SCRIPT=
PYINT_TEMPLATE_ROOT=
PYINT_WORK_ROOT=
PYINT_OUTPUT_ROOT=
PYINT_DEM_ROOT=
PYINT_GAMMA_ENV_SCRIPT=
PYINT_DEFAULT_TIMEOUT_SECONDS=43200
PYINT_SMOKE_TEST_ENABLED=false

PAIRING_GAMMA_ENABLED=false
PAIRING_GAMMA_WORK_ROOT=
PAIRING_GAMMA_TEMPLATE_ROOT=
PAIRING_GAMMA_TIMEOUT_SECONDS=7200

默认策略建议：

PYINT_WSL_DISTRO 为空时，默认取 ISCE2_WSL_DISTRO
PYINT_WSL_PYTHON 为空时，默认取 ISCE2_PYTHON
PYINT_APP_SCRIPT 指向 pyintApp.py
PYINT_WORK_ROOT / PAIRING_GAMMA_WORK_ROOT 使用系统托管目录，不直接让用户任意指定

6.3 不建议写入设计或配置的内容

管理员明文密码
ASF/GACOS 邮箱密码
WSL sudo 密码

这些信息如确需使用，也应通过运行时安全注入或机器本地安全配置处理，不写入仓库文档。

6.4 管理与治理策略

建议增加以下治理规则：

所有 PyINT/Gamma 工作目录按 run_key 或 network_run_id 分目录
所有运行都必须写运行摘要 JSON
所有正式产物必须进入统一结果发布目录
中间工作区可按保留策略定期清理
清理动作仅允许管理员执行

7. 数据库与数据库自维护策略

7.1 一期结论

一期建议：

PyINT 生产引擎接入不强制改库
Gamma 精配对接入不强制改库
优先复用现有 run/edge JSON 元数据承载扩展信息

7.2 二期改库触发条件

当满足以下任意条件时，再进入改库：

需要独立查询 Gamma 精配对运行历史
需要单独统计 Gamma 精配对失败率
需要把精配对资产纳入长期运维对象
需要做更细粒度的后台管理界面

7.3 改库时的落地方式

如果二期改库，必须沿用现有数据库自维护机制：

在 backend/migrations/ 新增 SQL 迁移文件，例如 007_pyint_gamma_integration.sql
在 backend/app/db_maintenance.py 的 MIGRATION_FILES 中追加文件名
由 ensure_database_ready() 在启动时自动执行迁移

约束：

不修改既有字段语义
不破坏现有 pairing_metric_cache / pairing_network_* 查询逻辑
迁移必须支持重复执行幂等

8. 运维自检与健康检查设计

8.1 设计原则

运维自检页继续只做“状态观察”，不做主操作入口。

PyINT/Gamma 的正式操作入口放在：

生产页
配对规划页

8.2 健康检查应新增的内容

建议在引擎可用性检查中加入 PyINT 项：

PYINT_ENABLED
WSL distro 可访问
WSL Python 可执行
PYINT_HOME 存在
pyintApp.py 存在
GAMMA_ENV_SCRIPT 可 source
关键命令如 base_calc 可执行
模板目录可读
工作目录可写
DEM 根目录可读

8.3 健康页展示策略

不建议在 HealthCheckPanel.jsx 再新增一大块复杂操作区。

建议只保留两类展示：

在现有 D-InSAR 引擎 卡片中自然显示 PyINT
在健康详情或备注中显示 PyINT/Gamma 的简要检查摘要

不建议：

在健康页提供精配对执行按钮
在健康页提供模板编辑入口
在健康页堆叠大量结果目录说明

8.4 运维修复入口位置

引擎级问题：在生产页提示不可用原因
配对级问题：在配对规划页处理
只有“环境诊断/烟测”可以保留在运维页

9. 后端接口设计

9.1 生产接口

现有 /dinsar-production/engines 和 /dinsar-production/run 可继续复用。

需要做的只是：

在引擎注册表中加入 pyint
list_engines() 自动返回 PyINT
submit_run() 允许 engine_code=pyint

9.2 配对接口

建议新增以下接口：

POST /pairing/refine-gamma
- 输入：network_run_id 或明确场景列表
- 输出：新的精配对 network_run_id、摘要、警告、产物位置
GET /pairing/networks/{network_run_id}
- 继续复用现有接口查看粗配对/精配对网络详情
可选：GET /pairing/refine-gamma/{network_run_id}/artifacts
- 用于查看 artifact 摘要，不建议一期必做

9.3 管理接口

建议增加一个轻量管理接口用于 PyINT/Gamma 环境烟测，例如：

POST /dinsar-production/engines/pyint/smoke-check

用途仅限管理员环境校验，不参与正式生产提交。

10. 前端入口与交互布局

10.1 生产页

位置：frontend/src/DinsarProductionPanel.jsx

建议改动：

新增 PyINT 引擎卡片
显示 PyINT 可用性状态
根据 profile 展示少量必要参数
保留当前“根目录 + 参数 + 提交任务”交互，不新造独立页面

10.2 配对规划页

位置：frontend/src/panels/PairPlanningPanel.jsx

建议新增一个独立区域：

标题：Gamma 精配对
放置位置：配对基础 卡片下方，结果与刷新 卡片上方

该区域建议包含：

粗配对网络摘要
发起 Gamma 精配对按钮
精配对结果摘要
粗配对 / 精配对差异提示
选择采用哪一版网络继续生产

不建议把精配对塞进现有健康检查页。

10.3 健康检查页

位置：frontend/src/HealthCheckPanel.jsx

建议只做最小改动：

让 D-InSAR 引擎 卡片中自动出现 PyINT
如需要，增加一条 PyINT/Gamma 环境说明

不增加复杂控制区，避免界面继续变重。

11. 涉及改动位置

11.1 后端

backend/app/dinsar_engines/registry.py
backend/app/dinsar_engines/pyint_engine.py 新增
backend/app/services/pyint_service.py 新增
backend/app/pyint_pipeline/run_lt1_pyint_pipeline.py 新增
backend/app/routers/dinsar_production.py
backend/app/routers/pairing.py
backend/app/services/health_service.py
backend/app/config.py
.env.example

11.2 前端

frontend/src/DinsarProductionPanel.jsx
frontend/src/panels/PairPlanningPanel.jsx
frontend/src/HealthCheckPanel.jsx
frontend/src/api/dinsarProduction.js
frontend/src/api/pairing.js

11.3 数据库

一期可不改。

二期若改，涉及：

backend/migrations/007_pyint_gamma_integration.sql 新增
backend/app/db_maintenance.py

12. 分阶段实施建议

Phase 1: PyINT 引擎接入

新增 pyint_engine
完成 WSL 可用性检查
完成模板生成与工作目录治理
完成生产页引擎选择
完成结果归一化与目录扫描兼容

Phase 2: Gamma 精配对 MVP

新增 /pairing/refine-gamma
基于现有 network_run_id 做精化
精配对结果复用现有 network run / edge 模型表达
前端在配对规划页增加精配对区块

Phase 3: 运维与治理补齐

增加烟测接口
增加工作区清理策略
增加 artifact 摘要与失败类型归档

Phase 4: 二期结构化增强

若业务确认需要，再加数据库迁移
把精配对历史与资产纳入更细粒度可检索对象

13. 风险与规避

13.1 PyINT 代码稳定性

风险：

模板字段和脚本依赖较多
对目录命名和环境变量较敏感

规避：

不做深度 import 复用
使用受控包装脚本
限制一期只开放一个稳定 profile

13.2 WSL 与路径问题

风险：

Windows 路径和 WSL 路径混用
工作区权限与可写性问题

规避：

所有路径统一通过适配层转换
工作目录和模板目录由系统托管

13.3 配对语义污染

风险：

把 Gamma 垂直基线直接混写进现有粗配对缓存字段

规避：

明确不覆盖 pairing_metric_cache 语义
精配对结果单独落在网络运行元数据中

13.4 前端继续膨胀

风险：

把运维、配对、生产操作继续堆到健康检查页

规避：

健康页只显示状态
生产操作只放生产页
配对操作只放配对规划页

14. 最终建议

建议按以下判断执行：

PyINT 生产引擎接入：必要，且应尽快按现有多引擎架构落地。
Gamma 精配对接入：可行，但应作为“粗配对之后的精化层”落地。
数据库：一期不强制改库；二期若需更强管理能力，再走数据库自维护迁移。
运维自检：只加状态，不加大块操作区。
前端入口：生产页接 PyINT，配对规划页接 Gamma 精配对。

18 KiB Raw Blame History