TraceStudio-dev/docs/server/feature.md

TraceStudio — Server 核心功能与组件说明

本文档概述 server/ 目录的核心功能、模块职责、执行流程以及可扩展点，便于新贡献者快速理解后端体系与关键逻辑。

目标

• 将 Unreal Insights 导出的数据通过可编程节点图进行二次加工与可视化。
• 后端职责: 解析/存储数据、管理用户文件、加载/验证/执行节点、调度工作流、并提供可供前端调用的 REST API。

--

一、核心模块（按目录）

• server/main.py

  • FastAPI 应用入口，负责应用初始化、路由挂载、CORS 配置与 startup 事件（例如 reload custom nodes、初始化 cache）。

• server/app/api/ — HTTP 路由集合

  • endpoints_upload.py / server/file_manager.py — 文件浏览、上传、下载、文件操作 API。
  • endpoints_graph.py — Graph/Node 相关 API：插件列表、节点预览、图执行、用户管理等。
  • endpoints_custom_nodes.py — 自定义节点的验证/上传/保存/加载/列表/下载接口。

• server/app/core/ — 后端核心逻辑

  • node_base.py — 节点基类 (TraceNode) 与常用接口（get_metadata(), execute() / wrap_process() 等）。
  • node_loader.py、node_registry.py — 自定义节点扫描、动态加载与注册。
  • node_validator.py — 节点代码静态校验与安全审查。
  • workflow_executor.py — 工作流执行器，负责节点调度、依赖解析与运行时上下文管理。
  • cache_manager.py — 缓存层，用于缓存节点结果或插件元数据以提升性能。
  • user_manager.py — 用户路径、profile 与基本用户 CRUD。

• server/custom_nodes/ — 用户可编辑节点代码（非核心但受支持）

--

二、主要功能点（Feature List）

1. 文件管理

   • 多用户文件根 (cloud/)，支持 shared, users/{username}/workflows, data, results。
   • 安全路径校验、上传去重、文件操作（move/rename/delete/mkdir）、下载流式返回。

2. 自定义节点生命周期

   • 上传/验证: validate_node_code 进行静态分析，阻止可疑代码。
   • 保存/备份: 保存前备份旧版本，支持 force 覆盖。
   • 加载/卸载: node_loader 动态导入并注册节点类到 NodeRegistry。
   • 运行时已加载查询与批量重载。

3. 节点图执行引擎

   • 接受 GraphExecuteRequest（nodes/edges/settings），将前端节点映射为内部执行单元。
   • 支持参数兼容（data / params），并统一传入 params 给执行器。
   • 执行器返回多种格式（兼容旧版 node_infos/node_results 或新的报告结构），后端负责序列化输出并将 DataFrame 转为预览格式。

4. 节点预览（快速迭代）

   • 允许前端在编辑器中对单个节点做即时预览（限制行数），返回 columns + preview。

5. 用户与权限（基础）

   • 用户列表与新增用户接口；为新用户创建工作目录结构。

--

三、核心执行流程（文本流程图）

1. 用户发起 POST /api/graph/execute 请求。
2. endpoints_graph.execute_graph 做入参校验、将 NodeSchema/EdgeSchema 转换为内部执行单元。
3. 创建 WorkflowExecutor（含用户上下文），并调用 executor.execute(nodes, edges, global_context)。
4. WorkflowExecutor 根据 DAG 拓扑计算执行序列，按节点调用对应 TraceNode.wrap_process()。
5. 各节点运行时可读写缓存（CacheManager），并可以访问 context（例如 user_id、preview_mode）。
6. 执行完成后，执行器返回 node_infos/node_results 或早期格式，execute_graph 对输出进行兼容处理并将复杂对象（DataFrame）序列化为预览对象。
7. 返回给客户端完整 results 映射与执行统计信息。

--

四、关键实现要点与注意事项

• DataFrame 处理: 使用 Polars（或兼容 pandas 的转换），但在 API 层返回 preview 而非完整表，避免大 payload。
• 自定义代码安全: 目前实现为保存后加载，强烈建议在生产环境中添加沙箱隔离或手动审查流程。
• 兼容性: executor 的返回格式存在历史差异，API 层做了兼容处理。新增 executor 功能时应保持向后兼容或更新文档并通知前端。
• 缓存失效策略: 对于依赖外部数据的节点，cache key 需要包含数据版本与节点参数，避免脏数据复用。

--

五、扩展点（供后续开发）

• 提供 OpenAPI 完整 schema 并在 CI 中自动校验前后端契约。
• 增加节点运行时沙箱（例如使用 Subprocess + seccomp 或 Wasm 运行自定义代码）。
• 支持异步/分布式执行器，利用外部任务队列（例如 Celery / RabbitMQ / Redis）以支持长耗时任务与横向扩展。
• 为自定义节点提供版本化（metadata 中含 version 字段）与回滚机制。

--

引用文件与快速查阅:

• server/main.py
• server/file_manager.py
• server/app/api/endpoints_upload.py
• server/app/api/endpoints_graph.py
• server/app/api/endpoints_custom_nodes.py