Harmon/insar-management-system-v2

Fork 0

Files

T

Harmon da09ba05cb Add LandSAR cluster worker deployment

2026-06-24 14:10:58 +08:00

14 KiB

Raw Blame History

存储压力清理与治理设计

最后更新：2026-06-23

本文档记录系统后续增加“释放存储压力”能力的设计边界。当前阶段仅作为维护和设计依据，不代表已经实现清理按钮、接口或数据库表。

1. 背景

当前系统已经明确退出 UNC 活动生产链路，LT-1、Sentinel-1、高分三、精密轨道、DEM、Task_Pool、运行时和结果发布目录均要求走本机路径。

本机化以后，磁盘压力主要来自：

LT-1 / Sentinel-1 源压缩包持续增长；
WebP、预览图源缓存和雷达缩略缓存持续增长；
D-InSAR / SBAS-InSAR 的 Task_Pool materialize 目录持续增长；
LandSAR、ENVI/SARscape、Gamma/PyINT、IDL、WSL broker 等运行时临时目录持续增长；
system_tasks / task_logs、生产运行日志、诊断日志等数据库记录持续增长；
失败任务、调试任务和隔离区残留。

清理能力必须服务于生产稳定性，不能把“释放空间”做成粗暴删除目录。系统需要先判断数据角色、数据库引用、任务状态和可重建性，再生成清理计划。

2. 总原则

源数据不清理。 LT-1 / Sentinel-1 源压缩包、高分三 _geo 原生成果、DEM、精密轨道池是生产输入或登记对象，普通存储清理不得删除。
先 dry-run，后执行。所有清理动作必须先生成计划，列出路径、大小、数据库影响、风险等级和预计释放空间。用户确认后才执行。
清理动作必须可审计。系统必须记录谁在什么时候按什么规则清理了哪些文件、释放了多少空间、哪些失败、哪些数据库记录被更新。
优先清理可重建派生物。日志、过期缓存、旧版本缓存、失败任务临时目录、运行时临时目录、过期隔离区优先进入第一阶段。
正式成果不走普通清理。 D:\production_results 及其 catalog 注册成果不能被“一键清理”删除。成果删除或归档应走单独的结果管理流程。
Task_Pool 清理必须依赖生产状态。 D:\Task_Pool 下 materialize 出来的生产输入理论上可从源压缩包重建，但只有在任务已结束、无活动执行、结果已登记或用户明确确认后才能清理。
文件状态和数据库状态必须同步。如果删除了数据库引用的 WebP 缓存、运行记录、结果资产或任务日志，必须同步更新对应表，避免前端显示“可用”但文件已不存在。

3. 永不进入普通清理的对象

以下对象默认不可被普通“释放存储压力”功能删除：

对象	典型路径 / 配置	原因
LT-1 源压缩包	`SOURCE_PRODUCT_DIRS` 中的 `D:\LuTan1_Image_Pool_Zip`	源数据，是按需解包和重新生产的根
Sentinel-1 源压缩包	`SOURCE_PRODUCT_DIRS` 中的 `D:\Sentinel1_Image_Pool_ZIP`	源数据，是按需解包和重新生产的根
高分三 `_geo` 成果池	`GF3_SARSCAPE_NATIVE_DIRS=D:\GaoFen3_Pool\native_geo`	本机登记对象，WebP 从这里生成
高分三 catalog	`GF3_STORAGE_DIRS=D:\GaoFen3_Pool\catalog`	平台登记 manifest 和追踪材料
LT-1 / S1 原生精轨源池	`ORBIT_SOURCE_DIRS`	轨道源资产
LT-1 生产精轨池	`ORBIT_POOL_ENVI` / `PYINT_ORBIT_POOL_TXT` / `GAMMA_SBAS_ORBIT_ROOTS`	ENVI、LandSAR、Gamma/PyINT 生产依赖
DEM	`D:\DEM` 及相关 DEM 配置	D-InSAR / SBAS / GF3 生产依赖
正式发布成果	`RESULT_PUBLISH_ROOT`、`DINSAR_PRODUCT_DIR`、`TIMESERIES_PRODUCT_DIR`	结果 catalog 管理对象，不走普通清理

如确需删除以上对象，必须另设“源数据归档/删除”或“成果归档/删除”专项流程，不能复用普通清理按钮。

4. 可清理对象分级

4.1 低风险：第一阶段优先实现

类别	规则	数据库动作
任务日志	清理已结束任务的旧日志，保留最近 N 天或每任务最后 N 条	删除 `task_logs`，可保留任务摘要
已结束旧任务记录	只清 `COMPLETED` / `FAILED` / `CANCELLED`，不得清 `PENDING` / `RUNNING`	删除 `system_tasks` 及日志，或仅压缩日志
无引用缓存文件	`backend\image_cache` 下没有数据库引用、文件不存在于当前版本策略的缓存	文件删除即可，记录清理项
旧版本 WebP 缓存	`RADAR_GEO_CACHE_VERSION` 已变化且数据库不再引用	删除文件；如仍被引用，先更新数据库
过期隔离区	隔离超过保留期的文件	删除隔离记录或更新清理项

4.2 中风险：第二阶段实现

类别	规则	数据库动作
雷达 WebP 缓存	可从源压缩包或 GF3 `_geo` 重建；默认只清旧版本、孤立文件	若删除当前引用缓存，`radar_data.preview_cache_status` 改为 `NONE`，写入 `preview_cache_error=storage_cleanup_removed`
预览图源缓存	`radar_archive_preview_sources` 等从压缩包提取的中间缓存	可删除，后续扫描或预览重建
运行时临时目录	`production_runtime`、IDL runtime、WSL jobs、PyINT work、临时 DEM 裁剪	仅清无活动任务、超过保留期的目录
GF3 SARscape runtime	`GF3_TASK_POOL_ROOT` / `GF3_SARSCAPE_RUNTIME_DIR`	当前本机 GF3 不生产，原则上仅清失败/过期 runtime，不清 `_geo`

4.3 高风险：第三阶段谨慎实现

类别	规则	数据库动作
D-InSAR Task_Pool materialize 目录	任务结束、无活动执行、可由源压缩包重建、用户确认	更新批次/任务的 materialize 状态
SBAS Task_Pool materialize 目录	任务结束、无活动执行、结果或失败状态明确	更新 SBAS 生产运行状态
D-InSAR / SBAS 中间文件	只清已发布结果之外的中间产物	必须依赖 result catalog 和 run manifest

4.4 不在本功能处理

源压缩包去重、归档、外发；
正式结果删除；
DEM 版本删除；
精轨池删除；
PostgreSQL VACUUM / 备份压缩；
洪水检测专项数据清理。

5. 清理计划模型

后续实现时，清理流程应分为两个动作：

PLAN 只扫描并估算，不删除文件，不修改业务表。
APPLY 按用户确认的计划执行，逐项记录结果，必要时同步更新数据库。

清理计划每一项至少包含：

{
  "category": "radar_preview_cache",
  "action": "delete_file",
  "path": "D:\\Code\\Insar_management_system_v2\\backend\\image_cache\\radar_geo\\xxx.webp",
  "size_bytes": 123456,
  "risk_level": "low",
  "reason": "old_cache_version",
  "db_table": "radar_data",
  "db_pk": 123,
  "db_update": {
    "preview_cache_status": "NONE",
    "preview_cache_error": "storage_cleanup_removed"
  }
}

6. 建议新增数据库表

为了审计和可追溯，建议新增两张表。

6.1 `storage_cleanup_runs`

字段	含义
`run_id`	清理任务 ID
`status`	`PLANNED` / `RUNNING` / `COMPLETED` / `FAILED` / `CANCELLED`
`dry_run`	是否只生成计划
`categories`	本次涉及类别
`planned_bytes`	计划释放空间
`released_bytes`	实际释放空间
`planned_count`	计划项数量
`succeeded_count`	成功项数量
`failed_count`	失败项数量
`started_at` / `ended_at`	执行时间
`operator_user_id`	操作用户
`report_json`	汇总报告

6.2 `storage_cleanup_items`

字段	含义
`run_id`	所属清理任务
`category`	清理类别
`action`	`delete_file` / `delete_dir` / `quarantine` / `delete_db_rows` / `update_db_rows`
`path`	文件或目录路径
`size_bytes`	大小
`risk_level`	`low` / `medium` / `high`
`reason`	命中规则
`db_table` / `db_pk`	关联数据库对象
`before_json` / `after_json`	数据库变更前后摘要
`quarantine_path`	隔离路径
`status`	单项执行状态
`error`	失败原因

第一阶段也可以先不建表，使用 system_tasks + JSON 报告落地，但正式实现建议单独建表。

7. 路径安全规则

所有文件清理必须满足以下规则：

路径必须位于白名单根目录下。
禁止删除盘符根目录，例如 D:\。
禁止删除项目根目录、数据库目录、Python 环境目录、Nginx 目录。
禁止处理 UNC 路径。
禁止跟随符号链接逃逸白名单根目录。
删除目录前必须重新计算 resolved path 并确认仍在白名单内。
默认先移动到隔离区，隔离区过期后再永久删除。
单次执行应有最大删除数量和最大删除字节数上限。

建议白名单根目录来自配置和系统常量：

backend\image_cache
TASK_POOL_ROOT
DINSAR_TASK_POOL_ROOT
SBAS_TASK_POOL_ROOT
GF3_TASK_POOL_ROOT
DATA_DISTRIBUTION_ROOT
IDL_WORKER_RUNTIME_DIR
SAR_ANALYSIS_WORK_ROOT
WSL_BROKER_JOB_ROOT
PYINT_WORK_ROOT
PYINT_DEM_ROOT
GAMMA_SBAS_TRIAL_ROOT
RESULT_QUARANTINE_ROOT

其中 RESULT_PUBLISH_ROOT 只允许扫描统计，不允许普通清理删除。

8. 任务互斥和运行保护

执行清理前必须检查活动任务：

存在 WebP 构建任务时，禁止清理 backend\image_cache；
存在资产扫描任务时，禁止清理预览图源缓存；
存在 D-InSAR 生产任务时，禁止清理 DINSAR_TASK_POOL_ROOT 和 D-InSAR runtime；
存在 SBAS 生产任务时，禁止清理 SBAS_TASK_POOL_ROOT、GAMMA_SBAS_WORK_ROOT 和 SBAS runtime；
存在 GF3 标准化或 WebP 生成任务时，禁止清理 GF3_TASK_POOL_ROOT；
禁止清理任何 PENDING / RUNNING 任务关联的目录。

后端实现应使用任务类型锁或 PostgreSQL advisory lock，避免多个清理任务并发执行。

9. 建议默认保留策略

以下值是初始建议，后续可放入 .env：

配置	建议默认值	含义
`RUNTIME_CLEANUP_TASK_LOG_RETENTION_DAYS`	30	已结束任务日志保留天数
`RUNTIME_CLEANUP_TASK_RECORD_RETENTION_DAYS`	90	已结束任务记录保留天数
`RUNTIME_CLEANUP_IMAGE_CACHE_RETENTION_DAYS`	60	无引用缓存保留天数
`RUNTIME_CLEANUP_RUNTIME_RETENTION_DAYS`	30	运行时临时目录保留天数
`RUNTIME_CLEANUP_FAILED_RUNTIME_RETENTION_DAYS`	7	失败任务临时目录保留天数
`RUNTIME_CLEANUP_TASK_POOL_RETENTION_DAYS`	30	可重建 Task_Pool materialize 目录保留天数
`RUNTIME_CLEANUP_QUARANTINE_RETENTION_DAYS`	14	隔离区永久删除前保留天数

默认只启用低风险类别。Task_Pool 和中间文件清理应默认关闭，需要用户显式勾选。

10. 前端工作台设计方向

入口建议放在“运行维护 / 存储治理”，而不是放在资产扫描、生产准备或数据分发按钮旁边。

页面结构建议：

存储概览
- 按磁盘卷展示总容量、已用、剩余、压力等级；
- 展示系统可治理目录的估算占用；
- 单独标注“受保护源数据”和“可清理派生数据”。
清理类别
- 任务日志；
- 图像缓存；
- 运行时临时目录；
- Task_Pool materialize；
- 隔离区。
清理计划
- 预计释放空间；
- 文件数量；
- 数据库记录数量；
- 风险等级；
- 样例路径；
- 受保护跳过项。
执行与审计
- 后台任务进度；
- 单项失败列表；
- 释放空间统计；
- 可下载 JSON 报告。

界面文案必须明确区分：

“源数据，不会删除”；
“缓存，可重建”；
“运行临时目录，任务结束后可清”；
“正式成果，不在本功能删除”。

11. 建议接口

后续实现可采用以下接口：

GET  /maintenance/storage/overview
POST /maintenance/storage-cleanup/plan
POST /maintenance/storage-cleanup/runs
GET  /maintenance/storage-cleanup/runs/{run_id}
GET  /maintenance/storage-cleanup/runs/{run_id}/items
POST /maintenance/storage-cleanup/quarantine/purge-plan
POST /maintenance/storage-cleanup/quarantine/purge

plan 接口只返回计划，不创建删除动作。runs 接口基于某次计划执行，并创建后台任务。

12. 实施阶段

阶段 0：文档维护

固化清理边界；
确认不清源压缩包、不清 GF3 _geo、不清 DEM、精轨和正式成果；
后续设计和编码必须引用本文档。

阶段 1：低风险清理

存储概览；
任务日志清理；
旧任务记录清理；
无引用缓存 dry-run；
清理任务审计报告。

阶段 2：缓存治理

WebP 缓存计划；
旧版本缓存清理；
数据库 preview_cache_* 同步；
缓存按需重建入口。

阶段 3：运行时治理

production_runtime、IDL、PyINT、WSL job、GF3 runtime 清理；
运行任务保护；
隔离区机制。

阶段 4：Task_Pool materialize 治理

D-InSAR / SBAS Task_Pool 目录识别；
与生产批次、生产运行、结果 catalog 关联；
可重建性验证；
用户确认后清理或隔离。

阶段 5：成果归档专项

不纳入普通清理；
单独设计结果产品归档、下线、删除和恢复流程。

13. 验收标准

后续实现完成后，至少满足：

dry-run 不改文件、不改业务表；
清理计划能解释每一项为什么可清；
源压缩包、GF3 _geo、DEM、精轨池和正式成果不会出现在普通清理执行项中；
删除 WebP 缓存后，数据库状态不会继续显示 READY；
活动任务相关目录不会被清理；
所有删除动作有审计记录；
清理失败不会导致整批数据库状态不一致；
前端能展示释放空间、失败项和跳过原因。

14. 与现有文档的关系

三类数据本机生产边界以 THREE_SENSOR_LOCAL_PRODUCTION_CONTRACT_20260616.md 为准。
源压缩包管理和按需 materialize 以 UNC_SOURCE_ARCHIVE_AND_MATERIALIZE_DESIGN_20260615.md 为准。
源压缩包完整性审计以 SOURCE_ARCHIVE_INTEGRITY_AUDIT_20260620.md 为准。
D-InSAR Task_Pool 和中间文件治理参考 DINSAR_TASK_POOL_THREE_ENGINE_REFACTOR_20260614.md。
正式成果包和 result catalog 以 PRODUCTION_RESULTS_MULTI_ENGINE_DESIGN_20260423.md 为准。

14 KiB Raw Blame History Unescape Escape