# 天璇 v5 — 18 Issues Full Fix Plan ## TL;DR (For humans) 修复上传管理、列检测、大规模数据处理、Globe可视化、聚类可视化等18个问题。 --- ## Workstream A: 上传管理修复 (Issues 1, 2, 3, 10, 11) ### A1 重启后端后旧数据可分析 **Files**: `analysis/views.py`, `analysis/session_store.py` **Root Cause**: 旧分析的 `AnalysisRun` 记录在 DB 中，但 `csv_glob` 指向的目录是 `%APPDATA%/TianXuan/data/uploads/{timestamp}/`。重启后 session_store 内存清空，但上传文件仍在磁盘。`globe_view` 和 `run_detail` 尝试加载旧运行时会调用 `load_csv_directory(run.csv_glob)` 重新读取 CSV。 **Fix**: 确保 `load_csv_directory` 能处理已删除的上传目录 → 优雅降级。在 `globe_view` 和 `_background_process` 中添加 `os.path.isdir()` 检查，目录不存在时将 run 标记为 `failed` 并设置友好的错误消息。 ### A2 Web图标在所有页面显示 **Files**: `templates/base.html`, `static/tianxuan/` **Root Cause**: `base.html` 没有 ``。浏览器自动请求 `/favicon.ico` 但项目无此文件。 **Fix**: 1. 创建 `static/tianxuan/favicon.svg` 或使用基于主题的 HTML favicon 2. `base.html` 的 `` 中添加 `` ### A3 上传按钮在页面顶部 **File**: `templates/tianxuan/upload.html` **Root Cause**: 上传 `
` 在 "已上传数据集" 表格之前，但上传按钮 (`#submitBtn`) 初始 `display:none`，只有在选择文件后才显示。 **Fix**: 将上传按钮移到 dropZone 下方、紧跟在选择文件后显示。或者将上传区域移到页面顶部的固定/粘性位置。 ### A10 Django文件上传无限制 **Files**: `tianxuan/settings.py`, `analysis/views.py` **Root Cause**: 当前限制：`DATA_UPLOAD_MAX_NUMBER_FIELDS=10000`、`DATA_UPLOAD_MAX_MEMORY_SIZE=50MB`、`views.py` 中硬编码 2000 文件/10GB 总大小限制。用户说"只能上传100文件"可能是由于 `FILE_UPLOAD_MAX_MEMORY_SIZE=10MB` 导致大文件被写入临时文件时出现问题。 **Fix**: - 移除 `DATA_UPLOAD_MAX_NUMBER_FIELDS` 限制（设为 0 或大幅增加） - 增大 `DATA_UPLOAD_MAX_MEMORY_SIZE` 到 256MB - 移除 `views.py` 中的 2000 文件限制（改为仅警告） ### A11 上传页删除功能完善 **Files**: `templates/tianxuan/upload.html`, `analysis/views.py` **Root Cause**: 删除按钮只显示在 `status` 为 `ready/completed/failed` 的运行上。`loading/profiling/aggregating` 状态的运行没有删除按钮（可能是为了安全）。 **Fix**: - 修改模板，在所有状态下显示删除按钮（`loading` 状态时弹出确认："后台处理中，删除将中断分析"） - 确保 `delete_upload` 视图能安全处理正在处理的运行（`shutil.rmtree` + ORM delete） --- ## Workstream B: 列检测与类型分类修复 (Issues 7, 15, 18) ### B7 TLS 0ver hex格式识别 **Files**: `analysis/type_classifier.py`, `analysis/views.py`, `templates/tianxuan/globe.html` **Root Cause**: `0ver` 列名不在名称启发式规则中（需要 `^ver_` 前缀）。TLS版本检测在 `views.py` 中硬编码为 `'1.3' in tls` / `'1.2' in tls`，不知道 hex 格式如 `03 03` (TLS 1.2) / `03 04` (TLS 1.3)。 **Fix**: 1. `type_classifier.py` 的 `_NAME_TYPE_MAP` 添加 `0ver` → ENUM 映射 2. `views.py` 的 `globe_view` 中添加 hex→TLS版本映射： ```python TLS_HEX_MAP = {'0303': 'TLSv1.2', '0304': 'TLSv1.3', '0302': 'TLSv1.1', '0301': 'TLSv1.0'} hex_val = tls.replace(' ', '') # "03 03" → "0303" tls_label = TLS_HEX_MAP.get(hex_val, 'other') ``` 3. Globe legend 添加对 hex 版本的说明 ### B15 "+"字符串被识别为数字 **Files**: `analysis/type_classifier.py`, `analysis/data_loader.py` **Root Cause**: 独立 `+` 在 `_coerce_to_float` 中被列为 artifact（正常），但值如 `+5`、`+0.5` 等前导加号的值会通过 `float("+5")` 解析。在 `_values_to_type` 中，LAT_LON 检测会过滤独立 `+`，但列中混有 `+` 和数字的列可能被分类为 FLOAT。 **Fix**: 1. 在 `_values_to_type` 的 FLOAT 检测步骤中，检查采样中是否有 `+` 或 `-` 开头的字符串值 2. 如果存在前导 `+`/`-` 且并非所有值都是有效数字，降级为 STRING 3. 在 `_coerce_to_float` 中添加对 `+` 前缀值的更严格检查 ### B18 根据真实列名配置实体检测 **Files**: `analysis/entity_detector.py`, `analysis/entity_aggregator.py`, `config/config.yaml` **Changes**: 1. `entity_detector.py` 的 `ENTITY_KEYWORDS` 添加用户全部列名 2. `entity_aggregator.py` 的关键词集合添加用户列名 3. `config.yaml` 更新 `entity.ip_columns` 和 column 覆盖 4. `type_classifier.py` 的 `_NAME_TYPE_MAP` 添加全部列名映射 **用户列名映射表**: | 列名 | 类型 | 聚合用途 | 检测关键词 | |------|------|---------|-----------| | `:ips` | IPv4 (已存在) | src IP | `:ips` | | `:ipd` | IPv4 (已存在) | dst IP | `:ipd` | | `:prs` | ENUM/端口 | src port | `:prs` | | `:prd` | ENUM/端口 | dst port | `:prd` | | `scnt` | STRING/ENUM | source country | `scnt` | | `dcnt` | STRING/ENUM | dest country | `dcnt` | | `server-ip` | IPv4 | server IP | `server_ip` | | `client-ip` | IPv4 | client IP | `client_ip` | | `0ver` | ENUM | TLS version | `0ver` | | `cnam` | STRING | cert common name | `cnam` | | `snam` | STRING | server name | `snam` | | `4dur` | FLOAT | duration | `4dur` | | `8ses` | FLOAT | session offset | `8ses` | | `2tmo` | FLOAT | timeout offset | `2tmo` | | `4ksz` | INT | key size | `4ksz` | | `cnrs` | BOOL_ENUM | recoverable | `cnrs` | | `isrs` | BOOL_ENUM | is recovered | `isrs` | | `8ack` | INT | backward bytes | `8ack` | | `8ppk` | INT | payload packets | `8ppk` | | `8dbd` | TIMESTAMP | db timestamp | `8dbd` | | `1ipp` | ENUM | IP protocol | `1ipp` | | `4dbn` | ENUM | database number | `4dbn` | | `tabl` | STRING | table name | `tabl` | | `name` | STRING | link name | `name` | | `source-node` | STRING | source node | `source_node` | | `cipher-suite` | HEX | TLS cipher | `cipher_suite` | | `ecdhe-named-curve` | STRING | ECDHE curve | `ecdhe_named_curve` | | `0cph` | HEX | TLS cipher hex | `0cph` | | `0crv` | HEX | TLS curve hex | `0crv` | | `0rnd` | STRING | TLS random | `0rnd` | | `0rnt` | FLOAT/TIMESTAMP | TLS random time | `0rnt` | | `4dbn` | STRING | db number | `4dbn` | | `time` | TIMESTAMP | time | `time` | | `timestamp` | TIMESTAMP | timestamp | `timestamp` | | `row` | INT | row number | `row` | | `+.latd` | LAT_LON | latitude (entity_aggregator 子串匹配) | `latd` | | `+.lond` | LAT_LON | longitude | `lond` | | `+.ispn` | STRING | ISP name | `ispn` | | `+.orgn` | STRING | org name | `orgn` | | `+.city` | STRING | city | `city` | **关键的 `_find_column` 改进**： `entity_aggregator.py` 中的 `_find_column` 使用严格匹配。对于 `:prs` 需要匹配 dst_port keywords → 不匹配。需要在 `_find_column` 中添加 `+` 和 `:` 前缀剥离： ```python normalised = name.lower().lstrip(':+').replace('-', '_').replace(' ', '_') ``` **Lat/Lon 列检测修复**： `+.latd` / `+.lond` 列： - `type_classifier._values_to_type` 中如果值 max_abs ≤ 10 则 LAT_LON 检测失败 - 需要在 `_NAME_TYPE_MAP` 中添加 `latd|lond` 模式 → LAT_LON - 或在 `_name_to_type` 中添加对 `+.` 前缀的感知 --- ## Workstream C: Traceback截断修复 (Issue 4) ### C4 清理所有 traceback 截断 **File**: `analysis/tool_registry.py` line 1138 **Current**: `traceback.format_exc()[:200]` 截断 PCA 错误到 200 字符 **Fix**: 改为完整 traceback。同时审计整个项目： - `tianxuan/llm_orchestrator.py` line 71: `json.dumps(...)[:1200]` — 这是工具结果截断，合理，保留 - `analysis/tool_registry.py` line 43: `_truncate_response()` — 工具响应截断，合理，保留 - **只修复** line 1138 的 `[:200]` --- ## Workstream D: 大规模数据处理 (Issues 5, 6, 14, 16) ### D5 大数据量卡顿优化 (1M-20M行) **Root Cause**: 当前 `MAX_ROWS_PER_RUN = 300` 但分析流水线是一次性 collect 所有数据到内存。 **Fix**: 1. `data_loader.py` 的 `load_csv_directory` 添加 `head=N` 参数用于预览场景 2. 聚类分析使用 Polars streaming (`engine='streaming'`) 3. 在 `tool_registry.py` 的 `_cluster_sync` 中添加数据降采样：>50K 行时随机采样 4. `views.py` 中 globe_view 的 `MAX_ROWS_PER_RUN` 从 300 改为 500（对于 20M 数据来说 300 行太稀疏了） ### D6 进度条 + 静默处理 **Root Cause**: 当前状态机只有 `loading→profiling→aggregating→ready→clustering→extracting→completed/failed`，无百分比。 **Fix**: 1. 在 `AnalysisRun` model 添加 `progress_pct` (IntegerField, default=0) 和 `progress_msg` (CharField) 2. 后台线程在每一步更新 `progress_pct`（loading=10, profiling=30, aggregating=50, clustering=70, extracting=90, completed=100） 3. `run_status_api` 返回 `progress_pct` 和 `progress_msg` 4. `upload.html` 中的进度条显示实际百分比 5. **无前端静默处理**：添加 `?background=true` 参数，后端仍全速分析但前端不轮询 ### D14 低内存设备聚类崩溃 **Root Cause**: 8GB 设备上，20M 行 × 30 列的数据在聚类时会产生巨大 float64 ndarray。 **Fix**: 1. `_cluster_sync` 中添加内存检查：`psutil.virtual_memory().available < 2GB` 时自动启用流式模式 2. 自动降采样：>100K 行时使用 `sklearn.utils.resample` 采样到 50K 行 3. 使用 `MiniBatchKMeans` 替代 `KMeans`（内存效率更高） 4. 在聚类前使用 `sklearn.decomposition.PCA(n_components=min(50, n_features))` 降维 ### D16 空闲时高磁盘IO **Root Cause**: `session_store.py` 是纯内存的，不应有磁盘 IO。但 Django 日志 `RotatingFileHandler` 可能在后台写入。另外 SQLite 使用 DELETE 模式（非 WAL）可能导致写入阻塞。 **Fix**: 1. 审计后台线程是否有不必要的 ORM 轮询 2. 如果 `settings.py` 中的 `LOGGING` 配置了低级别（如 DEBUG），改为 INFO+ 3. 检查是否有任何定时任务或 watchdog --- ## Workstream E: Globe可视化修复 (Issues 8, 9) ### E8 Globe响应式缩放 **File**: `templates/tianxuan/globe.html` **Root Cause**: 当前高度固定为 700px（`H = 700`），resize 只更新宽度和 aspect。缩放（wheel）只移动 `camera.position.z`（zoom），不按比例调整数据点大小。 **Fix**: 1. resize handler 中根据容器尺寸动态计算高度：`H = container.clientHeight || window.innerHeight * 0.8` 2. 添加设备像素比处理：`renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))` 3. 弧线粗细使用相对比例（根据 zoom level 调整 `TubeGeometry.radius` 或 `LineBasicMaterial.linewidth`） ### E9 `?data=` 访问拒绝支持 **File**: `analysis/views.py` (globe_view), `templates/tianxuan/globe.html` **Root Cause**: globe_view 只识别 `?runs=1&runs=2` 格式，没有 `?data=` 参数的处理逻辑。 **Fix**: 1. `globe_view` 添加 `?data=dataset_id` 参数支持 2. 当提供 `data=` 时，直接从 `SessionStore` 按 dataset_id 读取数据 3. Globe 模板更新 JavaScript 以支持 dataset 模式 --- ## Workstream F: LLM日志 (Issue 12) ### F12 LLM运行过程打印到前端 **Files**: `tianxuan/llm_orchestrator.py`, `analysis/views.py`, `templates/tianxuan/auto.html` **Root Cause**: LLM 在 thread 中运行，`logger.info` 写入日志文件，但前端 `auto.html` 通过轮询 `/logs/?pos=N` 显示日志。问题是日志缓冲可能延迟写入。 **Fix**: 1. 添加 `llm_status_api` 视图返回当前 LLM 运行状态 2. `llm_orchestrator` 使用回调函数报告进度（步骤/工具调用/中间结果） 3. `_run_llm_analysis` worker 写入 `AnalysisRun.run_log` 字段 --- ## Workstream G: 聚类可视化修复 (Issue 13) ### G13 聚类图表完善 **Files**: `templates/analysis/cluster_overview.html`, `analysis/views.py` **Root Cause**: 当前只有 PCA 散点图 + 地理散点图（两个 Canvas）。用户要求更丰富的图表。 **Fix**: 1. 添加簇大小饼图/柱状图（Canvas） 2. 添加 Silhouette 得分的簇间对比图 3. 添加特征重要性水平条形图（top 10 features per cluster） 4. 确保 PCA 坐标在 web 分析流程中正确保存（当前 `_handle_extract_features` 在 tool_registry.py 中保存，但异常被 `[:200]` 截断 → 先修 C4） --- ## Workstream H: 聚类质量改进 (Issue 17) ### H17 预处理降维+特征工程后聚类 **Files**: `analysis/tool_registry.py`, `analysis/entity_aggregator.py` **Root Cause**: 当前聚类直接对原始聚合特征（flow_count, total_bytes, unique_dst_ips 等）做 StandardScaler + HDBSCAN。没有特征选择、PCA/UMAP 预处理。 **Fix**: 1. 在 `_cluster_sync` 中添加可选的 PCA 预处理步骤 2. 添加方差过滤：去除方差为 0 或接近 0 的特征 3. 添加相关性过滤：去除相关性 >0.95 的特征对中的冗余特征 4. HDBSCAN 超参数根据数据规模自动调整 --- ## Dependencies - C4 (traceback fix) is prerequisite for G13 (PCA fix won't be debuggable without full traceback) - B18 (column mapping) is prerequisite for B7 (0ver hex detection needs 0ver in column map) and G17 (proper features need proper column detection) - D5 (optimization) is partially prerequisite for D14 (memory handling both affect clustering path) ## Must-Not-Have - 不修改 `runtime/` 目录下的任何文件 - 不删除或重命名现有数据库表 - 不添加新的 Python 包依赖（除非绝对必要且用户批准） - 不修改 Polars 版本锁定