347 lines
14 KiB
Markdown
347 lines
14 KiB
Markdown
# 存储压力清理与治理设计
|
||
|
||
最后更新：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. 总原则
|
||
|
||
1. 源数据不清理。
|
||
LT-1 / Sentinel-1 源压缩包、高分三 `_geo` 原生成果、DEM、精密轨道池是生产输入或登记对象，普通存储清理不得删除。
|
||
|
||
2. 先 dry-run，后执行。
|
||
所有清理动作必须先生成计划，列出路径、大小、数据库影响、风险等级和预计释放空间。用户确认后才执行。
|
||
|
||
3. 清理动作必须可审计。
|
||
系统必须记录谁在什么时候按什么规则清理了哪些文件、释放了多少空间、哪些失败、哪些数据库记录被更新。
|
||
|
||
4. 优先清理可重建派生物。
|
||
日志、过期缓存、旧版本缓存、失败任务临时目录、运行时临时目录、过期隔离区优先进入第一阶段。
|
||
|
||
5. 正式成果不走普通清理。
|
||
`D:\production_results` 及其 catalog 注册成果不能被“一键清理”删除。成果删除或归档应走单独的结果管理流程。
|
||
|
||
6. Task_Pool 清理必须依赖生产状态。
|
||
`D:\Task_Pool` 下 materialize 出来的生产输入理论上可从源压缩包重建，但只有在任务已结束、无活动执行、结果已登记或用户明确确认后才能清理。
|
||
|
||
7. 文件状态和数据库状态必须同步。
|
||
如果删除了数据库引用的 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. 清理计划模型
|
||
|
||
后续实现时，清理流程应分为两个动作：
|
||
|
||
1. `PLAN`
|
||
只扫描并估算，不删除文件，不修改业务表。
|
||
|
||
2. `APPLY`
|
||
按用户确认的计划执行，逐项记录结果，必要时同步更新数据库。
|
||
|
||
清理计划每一项至少包含：
|
||
|
||
```json
|
||
{
|
||
"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. 路径安全规则
|
||
|
||
所有文件清理必须满足以下规则：
|
||
|
||
1. 路径必须位于白名单根目录下。
|
||
2. 禁止删除盘符根目录，例如 `D:\`。
|
||
3. 禁止删除项目根目录、数据库目录、Python 环境目录、Nginx 目录。
|
||
4. 禁止处理 UNC 路径。
|
||
5. 禁止跟随符号链接逃逸白名单根目录。
|
||
6. 删除目录前必须重新计算 resolved path 并确认仍在白名单内。
|
||
7. 默认先移动到隔离区，隔离区过期后再永久删除。
|
||
8. 单次执行应有最大删除数量和最大删除字节数上限。
|
||
|
||
建议白名单根目录来自配置和系统常量：
|
||
|
||
- `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. 前端工作台设计方向
|
||
|
||
入口建议放在“运行维护 / 存储治理”，而不是放在资产扫描、生产准备或数据分发按钮旁边。
|
||
|
||
页面结构建议：
|
||
|
||
1. 存储概览
|
||
- 按磁盘卷展示总容量、已用、剩余、压力等级；
|
||
- 展示系统可治理目录的估算占用；
|
||
- 单独标注“受保护源数据”和“可清理派生数据”。
|
||
|
||
2. 清理类别
|
||
- 任务日志；
|
||
- 图像缓存；
|
||
- 运行时临时目录；
|
||
- Task_Pool materialize；
|
||
- 隔离区。
|
||
|
||
3. 清理计划
|
||
- 预计释放空间；
|
||
- 文件数量；
|
||
- 数据库记录数量；
|
||
- 风险等级；
|
||
- 样例路径；
|
||
- 受保护跳过项。
|
||
|
||
4. 执行与审计
|
||
- 后台任务进度；
|
||
- 单项失败列表；
|
||
- 释放空间统计；
|
||
- 可下载 JSON 报告。
|
||
|
||
界面文案必须明确区分：
|
||
|
||
- “源数据，不会删除”；
|
||
- “缓存，可重建”；
|
||
- “运行临时目录，任务结束后可清”；
|
||
- “正式成果，不在本功能删除”。
|
||
|
||
## 11. 建议接口
|
||
|
||
后续实现可采用以下接口：
|
||
|
||
```text
|
||
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. 验收标准
|
||
|
||
后续实现完成后，至少满足：
|
||
|
||
1. dry-run 不改文件、不改业务表；
|
||
2. 清理计划能解释每一项为什么可清；
|
||
3. 源压缩包、GF3 `_geo`、DEM、精轨池和正式成果不会出现在普通清理执行项中；
|
||
4. 删除 WebP 缓存后，数据库状态不会继续显示 `READY`；
|
||
5. 活动任务相关目录不会被清理；
|
||
6. 所有删除动作有审计记录；
|
||
7. 清理失败不会导致整批数据库状态不一致；
|
||
8. 前端能展示释放空间、失败项和跳过原因。
|
||
|
||
## 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` 为准。
|
||
|
||
本文档只定义存储压力治理边界，不替代源数据、生产准备、结果管理或完整性审计文档。
|