Harmon/insar-management-system-v2

Fork 0

Files

T

Harmon 1e44101eb2 chore: sync production runtime and docs

2026-04-25 15:02:40 +08:00

5.9 KiB

Raw Blame History

WSL Runtime 改造设计 2026-04-22

1. 背景

当前 ISCE2 与 Gamma/PyINT 的 WSL 执行存在三个根问题：

执行边界仍是 shell 字符串，后端直接把命令交给 wsl.exe ... bash -lc。
.env 直接持有 WSL Python、pipeline、Gamma 环境脚本等执行型配置，配置权和执行权耦合。
WSL 内的 conda 环境没有被定义成正式运行时资产，实际运行依赖“当前机器上碰巧可用的环境”。

这会带来四类风险：

参数或路径一旦逃逸 quote，直接进入 shell 解释边界。
引擎服务自己拼命令，执行治理无法集中落地。
ISCE2 和 Gamma/PyINT 虽然物理上可以共用一套 WSL/conda，但逻辑上没有独立运行时标识，审计和迁移困难。
WSL 环境漂移无法被健康检查和运维流程正式识别。

2. 目标

本次改造采用：

单 WSL distro
单共享 conda env
双逻辑 runtime
单一 WSL broker 出口

目标形态：

业务服务
-> Engine Adapter
-> WslBroker
-> RuntimeRegistry
-> JobManifest
-> WSL Runner
-> shared conda env: insar_wsl_v1

其中：

ISCE2 使用 isce2_runtime_v1
Gamma/PyINT 使用 gamma_pyint_runtime_v1

二者可以共用：

WSL_DISTRO=Ubuntu-24.04
WSL_SHARED_CONDA_ENV=insar_wsl_v1

但不能共用“逻辑运行时定义”。

3. 运行时模型

3.1 共享运行时

共享运行时负责：

distro 选择
共享 conda env 名称
共享 Python 路径
broker 作业落盘目录

建议配置：

WSL_DISTRO=Ubuntu-24.04
WSL_SHARED_CONDA_ENV=insar_wsl_v1
WSL_SHARED_PYTHON=/home/administrator/miniconda3/envs/insar_wsl_v1/bin/python
WSL_BROKER_JOB_ROOT=<backend/runtime/wsl_jobs>

3.2 逻辑 runtime

每个逻辑 runtime 固定：

runtime_id
engine_code
runner
allowed_operations
固定 profile 路径
固定审计标识

当前规划：

runtime_id	engine	runner	说明
`isce2_runtime_v1`	`isce2`	`deploy/wsl/runners/isce2_runner.py`	LT-1 条带 D-InSAR
`gamma_pyint_runtime_v1`	`pyint`	`deploy/wsl/runners/gamma_pyint_runner.py`	Gamma / PyINT

Gamma 固定 profile：

deploy/wsl/profiles/gamma_env.sh

注意：Gamma profile 属于部署资产，不再建议继续由 .env 动态指定脚本路径。

4. 执行模型

4.1 Broker

Broker 负责：

解析 runtime_id
写入结构化 job manifest
生成固定 argv
通过 wsl.exe --exec 执行 runner

禁止的旧模式：

服务层直接拼 bash -lc "..."
服务层直接决定 source 哪个环境脚本
服务层直接把 .env 中的 Python 绝对路径当成执行入口

4.2 Manifest

建议 manifest 固定包含：

job_id
runtime_id
engine_code
operation
created_at
payload

payload 中再放：

输入路径
工作路径
输出路径
参数
操作人
引擎内部业务上下文

4.3 Runner

Runner 是 WSL 内的固定可信入口。

阶段划分：

V1：只承担 manifest 读取、参数校验和 dry-run 输出
V2：接入实际 pipeline / PyINT / Gamma
V3：补齐固定 profile、版本指纹、错误分类与审计摘要

5. Conda 环境治理

5.1 基本原则

不原地继续污染旧环境
先冻结现有环境
再建立共享正式环境 insar_wsl_v1
旧环境只保留回滚用途

5.2 版本资产

deploy/wsl/conda/ 下至少维护：

insar_wsl_v1.environment.yml
insar_wsl_v1.explicit.lock
insar_wsl_v1.fingerprint.json

说明：

environment.yml 用于人工维护和审阅
explicit.lock 用于精确重建
fingerprint.json 用于健康检查、审计和漂移检测

5.3 Gamma

Gamma 通常不作为 conda 包管理。

因此建议：

Gamma 以固定安装路径存在于 WSL
由 deploy/wsl/profiles/gamma_env.sh 统一注入环境变量
不再由 .env 直接提供动态 profile 路径

6. 配置迁移策略

6.1 新增配置

新增统一配置：

WSL_DISTRO=Ubuntu-24.04
WSL_SHARED_CONDA_ENV=insar_wsl_v1
WSL_SHARED_PYTHON=/home/administrator/miniconda3/envs/insar_wsl_v1/bin/python
WSL_BROKER_JOB_ROOT=...
ISCE2_RUNTIME_ID=isce2_runtime_v1
PYINT_RUNTIME_ID=gamma_pyint_runtime_v1

6.2 旧配置处理

旧配置短期保留，用于兼容现有业务链路：

ISCE2_PYTHON
PYINT_WSL_PYTHON
PYINT_GAMMA_ENV_SCRIPT
ISCE2_WSL_DISTRO
PYINT_WSL_DISTRO

但应逐步降级为：

历史兼容字段
启动检查告警来源
回滚开关

而不再是长期正式执行入口。

7. 目录规划

新增目录：

deploy/wsl/
  conda/
  profiles/
  runners/
backend/app/services/
  wsl_runtime_registry.py
  wsl_broker.py

运行时作业目录：

backend/runtime/wsl_jobs/<runtime_id>/<operation>/<job_id>.json

8. 实施阶段

Phase 1

新增 WSL shared runtime 配置
新增 RuntimeRegistry
新增 WslBroker
新增 runner/profile/conda 目录落点

Phase 2

迁移 ISCE2 到 runtime_id + manifest + broker
去掉服务层 shell 字符串拼接

Phase 3

迁移 Gamma/PyINT
把 PYINT_GAMMA_ENV_SCRIPT 收敛到固定 profile

Phase 4

增加环境指纹校验
健康检查显示 runtime 漂移
审计日志记录 runtime_id / fingerprint / runner / manifest

9. 本轮代码落点

本轮先完成 V1 骨架：

backend/app/services/wsl_service.py
- 新增 run_wsl_exec()，支持 wsl.exe --exec
backend/app/services/wsl_runtime_registry.py
- 新增共享 runtime 与双逻辑 runtime 定义
backend/app/services/wsl_broker.py
- 新增 manifest staging 与 broker 执行骨架
deploy/wsl/runners/*
- 新增 runner scaffold
deploy/wsl/profiles/gamma_env.sh
- 固定 profile 落点
deploy/wsl/conda/README.md
- 约束 conda 环境治理落点

下一步迁移优先级建议：

ISCE2
Gamma/PyINT
健康检查与审计

5.9 KiB Raw Blame History Unescape Escape