# 生产节点子系统设计：D-InSAR 与单景影像生产（2026-06-27）

## 1. 结论

当前 `LANDSAR_CLUSTER_ITEM` 已经证明：LandSAR D-InSAR 可以从主服务器拆分 pair，并在远端 Windows 节点完成输入搬运、LandSAR 执行和结果回传。

但这仍是 LandSAR D-InSAR 的集群 MVP，不应直接扩展成长期架构。后续陆探一号和 Sentinel-1 的“只生产影像、不做 D-InSAR”能力也会进入生产管理域。陆探一号这条线应优先承认 LandSAR 已有的 `100016` LT-1 数据导入/统一格式转换能力，再决定是否继续扩展为地理编码或正射影像产品。因此远端节点不能只理解 `LANDSAR_CLUSTER_ITEM`，而应该抽象成一个受控的“生产节点子系统”。

建议把后续设计目标调整为：

1. 主服务器继续负责资产索引、任务编排、调度策略、结果 catalog 和权限边界。
2. 子服务器只部署生产节点运行包，不部署完整项目仓库、前端、管理后台和无关源码。
3. 所有生产任务按“产品类型 + 处理器能力”分发，同一任务可以选择本机执行或集群执行。
4. LandSAR、Gamma/PyINT、未来 Sentinel-1 影像生产处理器都通过 adapter 接入生产节点协议。
5. 结果以标准产品 manifest 回传，由主服务器统一入库，而不是让子服务器直接写主库或扫描任意目录。

## 2. 当前事实

### 2.1 已有设计边界

- [THREE_SENSOR_LOCAL_PRODUCTION_CONTRACT_20260616.md](THREE_SENSOR_LOCAL_PRODUCTION_CONTRACT_20260616.md) 明确 LT-1、Sentinel-1 当前管理对象是本机压缩包源池，生产时才按任务 materialize 到 `Task_Pool`。
- [DINSAR_TASK_POOL_THREE_ENGINE_REFACTOR_20260614.md](DINSAR_TASK_POOL_THREE_ENGINE_REFACTOR_20260614.md) 明确 D-InSAR 保留 `sarscape`、`landsar`、`pyint` 三条主线，其中 LandSAR 只处理 LT-1，Gamma/PyINT 同时支持 LT-1 和 Sentinel-1。
- [LANDSAR_CLUSTER_DATA_TRANSPORT_DESIGN_20260625.md](LANDSAR_CLUSTER_DATA_TRANSPORT_DESIGN_20260625.md) 已经为 LandSAR D-InSAR 定义了输入下载和结果上传链路。
- 当前 192.168.1.6 节点已能执行 LandSAR D-InSAR 集群 item，并调用与本机一致的 `LandsarEngine.run()`。
- `third_party/LandSAR/LT-1_数据导入功能说明.md` 明确 `100016` 是 LT-1 数据导入算法 ID；当前 `backend/app/dinsar_engines/landsar_engine.py` 已经能生成 `100016.txt` 并调用 `InSAR_Console.exe`，但这段能力目前只作为 D-InSAR 前置导入阶段存在。

### 2.2 仍未完成的能力

- 生产管理里的陆探一号已接入第一阶段本机生产链：`100016` LT-1 导入生成 LandSAR `Input_Data`，并支持可选 `100206` 精轨注入。它仍不是正射/地理编码影像产品。
- 生产管理里的 Sentinel-1“只生产影像”仍是占位，不是已实现链路。
- 陆探一号单景生产至少应拆成两层：`landsar.import.lt1` 表示 LandSAR `100016` 导入/统一格式转换，`landsar.image.lt1` 表示后续地理编码、正射或业务可用影像产品。前者已在本机任务/API/前端/catalog 中产品化；后者仍需要确认 LandSAR 调用链和输出规格。
- Sentinel-1 影像生产的处理器尚未最终确认，不能把 Sentinel-1 影像生产硬编码到 LandSAR 集群链路。
- 当前集群 worker 更接近“把后端生产代码部署到远端执行”，还不是一个最小权限、最小源码暴露的生产节点运行包。

## 3. 需要解决的问题

### 3.1 不要把集群等同于 LandSAR D-InSAR

如果继续按 `LANDSAR_CLUSTER_ITEM` 的方式增长，后续很容易出现：

- `LANDSAR_IMAGE_CLUSTER_ITEM`
- `S1_IMAGE_CLUSTER_ITEM`
- `PYINT_CLUSTER_ITEM`
- `SBAS_CLUSTER_ITEM`

每新增一种生产能力都复制一套领取、搬运、执行、上传、入库逻辑，技术债会快速扩大。

更稳妥的边界是：

```text
生产任务协议
  ├─ 输入 manifest
  ├─ 处理器 adapter
  ├─ 执行状态上报
  ├─ 结果 manifest
  └─ 结果上传与 catalog

具体处理器
  ├─ landsar.dinsar.lt1
  ├─ landsar.import.lt1
  ├─ landsar.image.lt1
  ├─ pyint.dinsar.lt1
  ├─ pyint.dinsar.s1
  └─ s1.image.<待定处理器>
```

### 3.2 单景影像生产也需要本机/集群双模式

LT-1 和 Sentinel-1 的影像生产虽然不是 D-InSAR，但仍可能是重计算、重 IO、长耗时任务。它们不应该只作为本机按钮实现。

推荐统一执行模式：

| 模式 | 含义 | 适用场景 |
| --- | --- | --- |
| `local` | 主服务器本机执行 adapter | 调试、小批量、没有可用节点 |
| `cluster` | 远端生产节点领取执行 | 大批量、长耗时、需要释放主服务器 |
| `auto` | 主服务器按能力、负载、数据位置选择 | 正式生产默认模式 |

前端可以先只暴露“本机执行 / 集群执行”，内部仍按统一任务协议创建任务。

### 3.3 子服务器不应长期部署完整代码仓库

当前 MVP 为了快速跑通，子服务器需要较完整的项目运行环境。这对验证是可接受的，但长期有三个问题：

1. 源码暴露面过大：子服务器不需要前端、后台管理、资产扫描、用户接口等源码。
2. 配置权限过宽：子服务器不应持有主库高权限连接信息。
3. 升级不可控：完整仓库部署容易出现主服务器和子服务器代码版本漂移。

长期应改为生产节点运行包：

```text
production-node/
  worker_service.py
  config.py
  client.py
  adapters/
    landsar_dinsar.py
    landsar_lt1_image.py
    pyint_dinsar.py
    s1_image.py
  contracts/
    job_manifest.py
    product_manifest.py
    status_event.py
  scripts/
    install_windows_service.ps1
  requirements.lock
```

这个运行包只包含：

- 任务领取和心跳客户端。
- 输入下载和结果上传客户端。
- 必要的生产 adapter。
- 与主服务器共享的 manifest schema。
- Windows 服务安装脚本。

不包含：

- 前端源码。
- 管理后台路由。
- 数据扫描入口。
- 用户认证管理。
- 数据库迁移脚本。
- 与该节点能力无关的处理器源码。

## 4. 目标架构

```mermaid
flowchart LR
  UI["生产管理前端"] --> API["主服务器 API"]
  API --> Scheduler["调度器"]
  Scheduler --> Queue["生产任务队列"]
  API --> Catalog["结果 catalog"]
  API --> Assets["源数据/精轨资产库"]

  NodeA["本机生产节点"] --> Queue
  NodeB["远端生产节点 1.6"] --> Queue
  NodeC["远端生产节点 N"] --> Queue

  NodeB --> Adapter1["landsar.dinsar.lt1"]
  NodeB --> Adapter2["landsar.image.lt1"]
  NodeC --> Adapter3["pyint.dinsar.s1"]
  NodeC --> Adapter4["s1.image.<待定>"]

  Queue --> Manifest["输入 manifest"]
  Manifest --> NodeB
  NodeB --> Upload["结果上传 API"]
  Upload --> Catalog
```

### 4.1 主服务器职责

- 维护源数据、精轨、DEM、Task_Pool、结果 catalog。
- 根据资产状态生成生产任务。
- 决定任务执行模式：本机、指定节点、自动调度。
- 为 worker 生成输入 manifest，包含文件清单、hash、大小、产品类型、处理器 profile。
- 接收 worker 状态、日志摘要、进度事件和结果包。
- 校验结果 manifest 后入库。
- 维护节点注册、能力、版本、心跳和并发上限。

### 4.2 生产节点职责

- 启动后向主服务器注册或发送心跳。
- 上报能力，例如 `landsar.dinsar.lt1`、`landsar.import.lt1`、`landsar.image.lt1`、`pyint.dinsar.s1`。
- 按能力领取任务。
- 下载输入文件或复用本地缓存。
- 调用本机已安装的生产软件或 adapter。
- 将运行日志、状态、结果 manifest 和产品文件上传回主服务器。
- 清理本地临时目录，保留可配置缓存。

### 4.3 Adapter 职责

Adapter 是生产节点中唯一知道具体软件细节的层：

| Adapter | 输入 | 输出 | 备注 |
| --- | --- | --- | --- |
| `landsar.dinsar.lt1` | LT-1 pair Task_Pool | D-InSAR 标准产品包 | 当前集群 MVP 已覆盖核心执行 |
| `landsar.import.lt1` | LT-1 单景源包、解包 scene，或多景导入目录 | LandSAR `Input_Data` 统一格式、缩略图、导入 manifest | 基于 `100016`，当前代码已有 pair-shaped 前置调用，需要拆成一等单景 adapter |
| `landsar.image.lt1` | `landsar.import.lt1` 输出 + 可选精轨/DEM | LT-1 地理编码、正射或业务影像产品 | 需要确认 LandSAR 后续 proID/参数和产品规格 |
| `pyint.dinsar.lt1` | LT-1 pair Task_Pool | D-InSAR 标准产品包 | 可后续接入 |
| `pyint.dinsar.s1` | S1 pair Task_Pool + EOF | D-InSAR 标准产品包 | 当前只应按 Gamma/PyINT 能力开放 |
| `s1.image.<待定>` | S1 ZIP/SAFE + EOF | S1 单景影像产品 | 处理器未确定前保持占位 |

主服务器不应该把某个 adapter 的内部目录结构暴露给前端；前端只看到任务类型、执行位置、状态和结果。

## 5. 统一任务类型

### 5.1 产品族

建议把生产任务按产品族建模，而不是按按钮建模：

| 产品族 | 数据粒度 | 当前状态 | 目标执行模式 |
| --- | --- | --- | --- |
| `dinsar_pair` | 两景 pair | LandSAR LT-1 集群 MVP 已跑通 | 本机 + 集群 |
| `single_scene_import` | 单景或多景导入 | LT-1 LandSAR `100016/100206` 已作为本机 `LANDSAR_LT1_IMPORT` 任务、API、前端入口和 `lt1_landsar` catalog 产品发布；集群执行尚未接入 | 本机 + 集群 |
| `single_scene_image` | 单景 | LT-1 后续影像产品和 S1 均为占位 | 本机 + 集群 |
| `sbas_stack` | 多景 stack | 当前不纳入本轮集群化 | 后续再设计 |
| `gf3_native_register` | 外部结果登记 | 本机登记 `_geo` | 不建议进入生产节点 |

### 5.2 推荐任务字段

```json
{
  "job_id": 123,
  "product_family": "single_scene_image",
  "sensor": "LT1",
  "processor": "landsar",
  "profile": "landsar.image.lt1",
  "execution_mode": "cluster",
  "input_manifest_url": "/api/production-node/jobs/123/input-manifest",
  "result_contract": "standard_product_manifest.v1",
  "priority": 50,
  "retry_policy": {
    "max_retries": 2,
    "timeout_seconds": 7200
  }
}
```

### 5.3 结果 manifest

D-InSAR 和单景影像生产都应该回传标准 manifest，差异放在 `product_family` 和 `product_type` 中：

```json
{
  "manifest_version": 1,
  "product_family": "single_scene_image",
  "sensor": "LT1",
  "processor": "landsar",
  "profile": "landsar.image.lt1",
  "scene_id": "LT1A_MONO_KSC_STRIP1_...",
  "run_key": "run_20260627T010203Z_landsar_image_lt1_456",
  "products": [
    {
      "role": "main_image",
      "path": "products/main.tif",
      "format": "GeoTIFF",
      "crs": "EPSG:4326"
    },
    {
      "role": "preview",
      "path": "preview/main.webp",
      "format": "WEBP"
    },
    {
      "role": "metadata",
      "path": "metadata/product.json",
      "format": "JSON"
    }
  ]
}
```

## 6. 陆探一号单景生产设计方向

陆探一号单景生产如果由 LandSAR 承担，应先把“导入/统一格式转换”和“正式影像产品”分开。

### 6.1 `landsar.import.lt1`

这是当前最清楚、风险最低的第一版能力。

LandSAR `100016` 的语义是 LT-1 数据导入：把 LT-1A/LT-1B SLC XML/TIFF 转成 LandSAR 统一内部格式，形成 `Task_*/Input_Data` 可消费的 XML/TIF 组织，并生成缩略图等辅助文件。当前代码已经在 `_ensure_imported_input_data()` 中调用这条链路，但有两个限制：

- 它被包在 D-InSAR 执行内部，只在缺少 `Input_Data` 时作为前置阶段触发。
- 当前参数生成器按 `master/slave` 两文件夹导入写死，不是正式的单景产品 adapter。

第一版应把它产品化为：

```text
landsar.import.lt1
  输入：LT-1 单景源包、解包 scene，或显式 scene 目录
  执行：InSAR_Console.exe + 100016.txt
  输出：LandSAR Input_Data 统一格式 + import_manifest.json + 缩略图/日志
  入库：单景预处理/影像生产 catalog
  执行模式：local / cluster / auto
```

这个产品不应伪装成正射影像或地理编码强度图。它的价值是把陆探源数据转成 LandSAR 后续 D-InSAR、SBAS、影像处理可复用的标准输入。

### 6.2 `landsar.image.lt1`

如果“只生产影像”指的是业务可用影像，例如地理编码强度图、幅度图、正射 GeoTIFF、洪涝分析输入图，那么还需要确认 LandSAR 是否有对应单景 proID 或可复用处理链。不能把 `100016` 的导入输出直接命名为正射产品。

需要确认的产品规格：

- 输入是源压缩包、解包目录，还是现有 Task_Pool scene 目录。
- 输出是 SLC/SSC 的标准化影像、地理编码强度图、幅度图、还是系统用于浏览和洪水分析的 GeoTIFF。
- 是否需要精轨。
- 是否需要 DEM。
- 是否需要生成 WebP 预览。
- 是否进入 `radar_data`、`source_product_assets`、D-InSAR catalog，还是新的影像产品 catalog。

如果后续确认 LandSAR 能从 `Input_Data` 继续生成地理编码/正射产品，再实现第二层：

```text
LT-1 single scene image product
  输入：landsar.import.lt1 输出 + 可选精轨 + 可选 DEM
  执行器：LandSAR
  输出：标准产品目录 + product_manifest.json + preview.webp
  入库：影像产品 catalog
  执行模式：local / cluster / auto
```

不要在第一版同时承诺“原始归档标准化、地理编码、洪水分析输入、全部极化派生物、可视化浏览缓存”这些目标。先把一个产品闭环做对，再扩展产品角色。

## 7. Sentinel-1 影像生产设计方向

Sentinel-1 单景影像生产目前不能直接套用 LandSAR。需要先确定处理器：

- 如果走 Gamma/PyINT，需要定义单景预处理 profile。
- 如果走 GDAL/SNAP/其他工具，需要单独 adapter。
- 如果只是生成浏览预览，应该归入资产扫描/预览缓存，不应叫正式生产任务。

建议在处理器未确认前只保留协议占位：

```text
s1.image.<processor>
  状态：设计占位
  不进入正式调度
  不在 UI 上展示为可执行生产能力
```

这样可以避免前端提前出现“哨兵影像集群生产”按钮，但后端没有可信处理链。

## 8. 调度与效率

### 8.1 节点能力上报

生产节点心跳应包含：

```json
{
  "node_id": "production-node-192-168-1-6",
  "version": "2026.06.27",
  "capabilities": [
    "landsar.dinsar.lt1",
    "landsar.import.lt1",
    "landsar.image.lt1"
  ],
  "max_concurrency": 1,
  "active_jobs": 0,
  "free_disk_gb": 512,
  "runtime": {
    "os": "windows",
    "landsar_available": true,
    "python_version": "3.12"
  }
}
```

LandSAR 类任务的并发不能只看 CPU 核心数。需要同时考虑：

- LandSAR 是否支持多实例并发。
- 许可证或硬件锁是否允许并行。
- 工作目录是否互相隔离。
- 磁盘 IO 是否成为瓶颈。
- 单任务内部是否已经使用多线程。

因此第一版远端 LandSAR 节点建议 `max_concurrency=1`。等确认 LandSAR 多实例隔离和资源占用后，再按节点开放 2 个或更多并发。

### 8.2 缓存策略

单景影像生产和 D-InSAR 可以共享部分输入缓存：

- LT-1 源包下载缓存。
- LT-1 解包缓存。
- LandSAR 导入后的中间目录。
- DEM 裁剪缓存。
- Sentinel-1 ZIP/SAFE 和 EOF 缓存。

缓存键应基于源文件 hash、mtime、size、processor profile 和关键参数，不应只基于文件名。否则源包被替换后容易复用错误缓存。

### 8.3 数据搬运策略

优先级建议：

1. 第一阶段：沿用 HTTP manifest + file download + result upload，路径最清楚。
2. 第二阶段：增加断点续传和文件级 hash 校验。
3. 第三阶段：支持节点本地缓存命中，避免重复下载同一源包。
4. 第四阶段：在受控环境下可选共享只读源池，但不作为默认安全模型。

不要让 worker 任意访问主服务器磁盘路径。worker 应只根据主服务器签发的 manifest 下载白名单文件。

## 9. 安全边界

长期目标：

- worker 不持有主数据库账号。
- worker 只持有节点 token。
- token 按节点、能力和有效期管理。
- 所有输入下载和结果上传都走主服务器 API。
- 主服务器校验每个上传文件的相对路径，拒绝目录逃逸。
- 主服务器校验 result manifest，只有白名单产品角色进入 catalog。
- worker 运行包只包含生产节点必要代码。
- worker 版本和 adapter 版本必须上报，主服务器可以拒绝过旧节点领取任务。

当前 LandSAR 集群 MVP 可以作为过渡，但文档上应明确：完整仓库部署、DB 直接领取队列、共享 token 都不是长期安全边界。

## 10. 实施路线

### 阶段 0：保持现状可用

- 保留当前 LandSAR D-InSAR 集群能力。
- 不在未设计清楚前扩展新的集群 job type。
- 继续记录 1.6 节点运行结果、失败原因、传输耗时和 LandSAR 执行耗时。

### 阶段 1：抽取生产节点协议

- 定义 `job_manifest`、`input_manifest`、`product_manifest`、`status_event`。
- 把 LandSAR D-InSAR 当前输入下载、执行、上传流程映射到协议。
- 主服务器保留当前 API，同时新增通用 `/api/production-node/*` 命名空间。

### 阶段 2：拆出 worker-only 运行包

- 从完整仓库部署改成生产节点运行包部署。
- Windows 节点用服务方式启动。
- 节点只配置主服务器 URL、节点 token、工作根、结果根、缓存根和能力列表。
- 先支持 `landsar.dinsar.lt1`。

### 阶段 3：陆探一号单景生产

- 先实现 `landsar.import.lt1` adapter，把 LandSAR `100016` 从 D-InSAR 前置阶段拆成一等生产能力。
- 当前 `_generate_import_param_file()` 按 master/slave 两文件夹导入写死，单景 adapter 需要支持单 scene 输入、单文件夹导入或显式 file import。
- 本机模式和集群模式同时接入同一任务协议。
- 结果进入单景预处理/影像产品 catalog，而不是混入 D-InSAR 结果 catalog。
- 确认 LandSAR 后续单景地理编码或正射处理链后，再实现 `landsar.image.lt1`。

### 阶段 4：Sentinel-1 单景影像生产

- 先确认处理器和产品规格。
- 再实现 `s1.image.<processor>` adapter。
- 未确认前不开放 UI 执行入口。

### 阶段 5：节点运维和调度完善

- 节点版本管理。
- 能力矩阵管理。
- 节点禁用/启用。
- 任务重分配。
- 节点磁盘清理。
- 节点运行日志集中查看。

## 11. 近期不建议做的事

- 不建议继续复制 `LANDSAR_CLUSTER_ITEM` 形成多个专用 cluster item。
- 不建议在子服务器长期部署完整项目仓库。
- 不建议让子服务器直接扫描主服务器源数据目录。
- 不建议让子服务器直接写主数据库结果表。
- 不建议在 Sentinel-1 处理器未确认前实现“哨兵影像生产”按钮。
- 不建议把资产扫描阶段的 WebP 预览生成混同为正式影像生产。

## 12. 待确认问题

1. 陆探一号“只生产影像”的正式产品定义是什么：只做 LandSAR `100016` 导入/统一格式转换，还是继续生成地理编码强度图、幅度图、正射 GeoTIFF？
2. 陆探一号单景影像生产是否必须使用精轨和 DEM？
3. Sentinel-1 单景影像生产准备用哪个处理器承担？
4. 单景影像产品是否需要新建 catalog，还是复用现有 `radar_data` 资产表加产品 manifest？
5. 远端节点是否允许访问只读共享源池，还是严格走 HTTP 下载？
6. LandSAR 在同一台 Windows 节点上是否允许多个实例并发？

这些问题确认前，可以继续完善 LandSAR D-InSAR 集群，但不宜把新的影像生产能力直接硬接到当前 MVP worker 上。