94 lines
5.2 KiB
Markdown
94 lines
5.2 KiB
Markdown
# 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/main.py#L1-L1)
|
||
- [server/file_manager.py](server/file_manager.py#L1-L400)
|
||
- [server/app/api/endpoints_upload.py](server/app/api/endpoints_upload.py#L1-L400)
|
||
- [server/app/api/endpoints_graph.py](server/app/api/endpoints_graph.py#L1-L400)
|
||
- [server/app/api/endpoints_custom_nodes.py](server/app/api/endpoints_custom_nodes.py#L1-L400)
|