chore: sync production runtime and docs
This commit is contained in:
@@ -0,0 +1,274 @@
|
||||
# WSL Runtime 改造设计 2026-04-22
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 `ISCE2` 与 `Gamma/PyINT` 的 WSL 执行存在三个根问题：
|
||||
|
||||
1. 执行边界仍是 shell 字符串，后端直接把命令交给 `wsl.exe ... bash -lc`。
|
||||
2. `.env` 直接持有 WSL Python、pipeline、Gamma 环境脚本等执行型配置，配置权和执行权耦合。
|
||||
3. WSL 内的 conda 环境没有被定义成正式运行时资产，实际运行依赖“当前机器上碰巧可用的环境”。
|
||||
|
||||
这会带来四类风险：
|
||||
|
||||
- 参数或路径一旦逃逸 quote，直接进入 shell 解释边界。
|
||||
- 引擎服务自己拼命令，执行治理无法集中落地。
|
||||
- `ISCE2` 和 `Gamma/PyINT` 虽然物理上可以共用一套 WSL/conda，但逻辑上没有独立运行时标识，审计和迁移困难。
|
||||
- WSL 环境漂移无法被健康检查和运维流程正式识别。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
本次改造采用：
|
||||
|
||||
- 单 WSL distro
|
||||
- 单共享 conda env
|
||||
- 双逻辑 runtime
|
||||
- 单一 WSL broker 出口
|
||||
|
||||
目标形态：
|
||||
|
||||
```text
|
||||
业务服务
|
||||
-> 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 作业落盘目录
|
||||
|
||||
建议配置：
|
||||
|
||||
```env
|
||||
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 内的固定可信入口。
|
||||
|
||||
阶段划分：
|
||||
|
||||
1. V1：只承担 manifest 读取、参数校验和 dry-run 输出
|
||||
2. V2：接入实际 pipeline / PyINT / Gamma
|
||||
3. 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 新增配置
|
||||
|
||||
新增统一配置：
|
||||
|
||||
```env
|
||||
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. 目录规划
|
||||
|
||||
新增目录：
|
||||
|
||||
```text
|
||||
deploy/wsl/
|
||||
conda/
|
||||
profiles/
|
||||
runners/
|
||||
backend/app/services/
|
||||
wsl_runtime_registry.py
|
||||
wsl_broker.py
|
||||
```
|
||||
|
||||
运行时作业目录：
|
||||
|
||||
```text
|
||||
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 环境治理落点
|
||||
|
||||
下一步迁移优先级建议：
|
||||
|
||||
1. `ISCE2`
|
||||
2. `Gamma/PyINT`
|
||||
3. 健康检查与审计
|
||||
Reference in New Issue
Block a user