TianXuan Developer
829729943c
核心改进: - 节点数据丰富: TLS版本/加密套件/SNI/端口/流量统计/连接成功率 - 边数据丰富: 包数/持续时间/TLS/端口/SNI/分类标签 - 新增 edge_time_series 端点: 边流量时序图(北京时间) - 新增 cluster_nodes_edges 端点: 社区聚焦(zoom+高亮+专属边) - 社区点击: 自动缩放/高亮节点/显示社区边(可点击) - 边交互修复: 事件从layerGroup移至hitPoly,三处边渲染全修复 - 地图升级: ESRI卫星影像 + 255国矢量边界叠加 - 离线回退: 卫星→CartoDB→暗色矢量地图,完整可用 - 节点面板: 删除无意义社区标签,移至Host+组织同行 - sanitizeName: 清理5个非ASCII国家名避免乱码 - .gitignore: 补充geoip_chunks/和嵌套CSV规则 项目清理: - 删除 logs/ (20个调试文件,~2.5MB) - 删除 test_*.py (4个临时测试脚本) - 删除 _check_bool/_pipeline_test/_restart_server/start_server (硬编码路径) - 删除 node_modules/package.json/package-lock.json (18MB,不用Node) - 删除 tests/ 旧日志和调试脚本 - 删除 .pytest_cache/ .server_pid.txt RUNTIME_CHANGED.txt - AGENTS.md → CLAUDE.md Co-Authored-By: Claude <noreply@anthropic.com>
5.6 KiB
CLAUDE.md — 天璇 (TianXuan) 系统
项目概览 天璇 是一个 TLS 加密流量数据分析与实体画像系统，基于 Django + Polars + scikit-learn + Three.js 构建，支持从 CSV 导入、实体检测、聚合、聚类、特征提取到 3D 可视化的全自动离线分析流水线。
- 版本: v2.0.0beta
- 运行方式: 离线桌面应用，内置 Python 3.12 运行时，双击 run.bat 即可启动，无需安装任何依赖。
- 数据存储: SQLite (WAL 模式) + 内存缓存
- 分支策略: 后续所有改动直接提交到 main 分支，并推送到远程仓库 https://gitea.cattysteve.top/HJQ/tianxuan。
核心模块
| 模块 | 功能 |
|---|---|
| analysis/data_loader.py | CSV 加载、合并、列名规范化、GeoIP 解析 |
| analysis/entity_detector.py | 基于列名关键词和唯一值比率的实体列自动检测 |
| analysis/entity_aggregator.py | 按实体分组计算流量统计、TLS特征、时间模式等 |
| analysis/tool_registry.py | 12 个 MCP 工具注册（145KB） |
| simple_analysis/ | 新增的“简单分析”模块，独立 Django App，提供上传→筛选→聚类→地图可视化一站式工作流 |
| templates/ | 传统功能页面（仪表盘、上传、手动分析、LLM分析、3D地球等） |
| data/ | 离线 GeoIP 数据库 (GeoLite2-City.mmdb、GeoLite2-ASN.mmdb)、自定义 IP 数据 geoip_data.txt |
项目结构要点 天璇/ ├── analysis/ # 主分析 App ├── simple_analysis/ # 简单分析 App (新增) │ ├── views.py # API 视图 (upload, filter, cluster, edges) │ ├── urls.py # 路由 /simple/ │ ├── templates/simple_analysis/ │ │ └── simple_analysis.html # 单页应用 │ └── static/ ├── config/ │ ├── config.yaml # 全局配置（含 API Key、参数） │ └── loader.py ├── data/ │ ├── GeoLite2-City.mmdb # 130MB，城市级 GeoIP │ ├── GeoLite2-ASN.mmdb # 9.5MB，ASN 数据库 │ └── geoip_data.txt # 补充 IP 地理位置 ├── runtime/python/ # 嵌入式 Python 3.12 运行时 ├── db.sqlite3 # 主数据库 ├── main.py / manage.py └── run.bat
当前开发焦点：简单分析模块 (v3) 目标：构建一个完全离线、高性能的网络流量 IP 通信社区发现与可视化工具。 工作流（4 步）：
- 上传与预筛选：拖拽上传 CSV，支持高级筛选器（AND/OR/NOT 树状表达式），上传时立即过滤以减少内存占用。
- 高级手动筛选：可视化布尔表达式编辑器，对已加载数据进一步精筛。
- 网络聚类：基于 IP 通信图进行社区发现：
- 提取所有唯一 :ips / :ipd 作为节点。
- 先按 /24 子网分组，子网内部使用 HDBSCAN (haversine 距离) 二次聚类。
- 最终每个节点（IP）获得一个 cluster_id。
- 地图可视化与交互：
- 离线地图：使用 Leaflet + 离线瓦片缓存（leaflet-offline），无网络时回退到本地低级别瓦片。
- 节点按簇着色，支持 Canvas 渲染器和聚类插件优化性能。
- 点击节点展示：IP、运营商、组织、城市、关联对端IP、host/text 等。
- 点击边（IP 间连线）展示：通信次数、总流量、首次/末次北京时间、时间规律。
- 导出点表/边表 CSV。
重要技术约定
- 列名规范化：所有 CSV 列名通过 normalize_columns() 处理成小写+下划线格式，内部使用标准列名（如 src_ip, dst_ip, cnam 等）。
- GeoIP：完全抛弃 CSV 中自带经纬度（:ips.latd 等），所有坐标均使用离线 GeoLite2-City.mmdb 解析。
- 时间处理：原始时间戳/时间列统一转为北京时间 (UTC+8) 展示。
- 内存管理：上传后的数据保存在内存缓存（_cache dict），以 session_id（12位 hex）索引，无持久化。
- 性能要求：i7-10700 + 8GB RAM，十万级 IP 节点需在 1 分钟内完成聚类，内存占用 <2GB。
前端注意事项
- 所有静态资源（Leaflet, Chart.js, Three.js 等）必须本地托管，确保离线可用。
- 地图瓦片离线方案必须实现：在线时缓存 OSM 瓦片到 IndexedDB，离线时使用缓存或内置低级别瓦片。
- 按钮必须防重复点击，操作栏固定在顶部，调试信息面板实时显示。
- 需修复 Cannot set properties of null 类 DOM 操作错误。
API 端点 (简单分析)
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /simple/ | 主页面 |
| POST | /simple/upload/ | 上传文件 + 预设筛选 + GeoIP 解析 |
| POST | /simple/filter/advanced/ | 树状高级筛选 |
| GET | /simple/column-values/ | 列 Top 50 唯一值（供下拉菜单） |
| POST | /simple/cluster/ | 执行网络聚类 |
| GET | /simple/cluster// | 簇详情 |
| POST | /simple/edges/ | 获取边关系 |
已知问题与待办
- 离线地图瓦片缓存机制完善（目前仅低级别内置）。
- 边渲染时坐标查找需使用节点真实坐标，而非簇中心近似。
- 大数据量时地图标记性能优化（可换用 WebGL 渲染器）。
- 预设筛选器与 Step 2 筛选器 UI 统一为同一个高级筛选组件。
开发命令
- 启动开发服务器：python manage.py runserver
- 运行测试：python manage.py test simple_analysis
- 生成要求：pip freeze > requirements.txt (注意剔除内部路径)
提交规范
- 直接提交到 main 分支，git push origin main。
- 提交信息格式：feat: xxx / fix: xxx / refactor: xxx，简要描述改动。
最后更新: 2026-07-24 维护者: 天璇开发团队