# TraceStudio 服务器架构文档 ## 📁 目录结构 ``` server/ ├── 📜 main.py # 🚀 主启动入口（v2.0模块化架构） ├── 📜 system_config.yaml # ⚙️ 系统配置（端口/安全/存储/UE路径） ├── 📜 requirements.txt # 📦 依赖库列表 │ ├── 📂 app/ # 🧠 核心应用代码 │ ├── 📂 core/ # 🔧 引擎内核 │ │ ├── 📜 user_manager.py # 👤 用户目录管理 │ │ ├── 📜 security.py # 🔐 路径安全检查 │ │ ├── 📜 node_base.py # 🧩 节点基类（待实现） │ │ ├── 📜 registry.py # 📝 装饰器注册系统（待实现） │ │ └── 📜 executor.py # ⚙️ DAG执行引擎（待实现） │ ├── 📂 api/ # 🌐 API路由 │ │ ├── 📜 endpoints_graph.py # 📊 图执行与节点API │ │ └── 📜 endpoints_upload.py # 📤 文件管理API │ ├── 📂 nodes/ # 📦 内置节点库 │ │ ├── 📜 io.py # 加载器节点（待实现） │ │ ├── 📜 logic.py # 逻辑转换节点（待实现） │ │ └── 📜 vis.py # 可视化节点（待实现） │ └── 📂 locales/ # 🌍 多语言包 │ ├── 📂 custom_nodes/ # 🧩 第三方插件目录 ├── 📂 tests/ # 🧪 测试代码 │ └── 📜 web1.1_server.py # 旧版服务器（v1.1，供前端测试） └── 📂 cloud/ # ☁️ 云存储（自动生成） └── users/ # 用户隔离目录 └── {username}/ ├── data/ # 数据文件 ├── workflows/ # 工作流 ├── results/ # 结果输出 └── cache/ # 缓存 ``` --- ## 🚀 快速开始 ### 1. 创建 Python 环境（推荐） ```bash conda create -n tracestudio python=3.11 conda activate tracestudio ``` ### 2. 安装依赖 ```bash cd server pip install -r requirements.txt ``` ### 3. 启动服务器 #### **方式一：规范化服务器 (v2.0 - 推荐)** ```bash python main.py ``` #### **方式二：旧版测试服务器 (v1.1 - 供前端测试)** ```bash python tests/web1.1_server.py ``` ### 4. 访问 API 文档 - 交互式文档: http://127.0.0.1:8000/docs - 替代文档: http://127.0.0.1:8000/redoc --- ## 🔌 API 接口 ### 健康检查 ```http GET / ``` ### 图执行相关 (endpoints_graph.py) #### 获取节点插件列表 ```http GET /api/plugins ``` #### 节点预览 ```http POST /api/node/preview Content-Type: application/json { "nodeId": "n_xxx", "nodeType": "CSVLoader", "params": {...} } ``` #### 图执行 ```http POST /api/graph/execute Content-Type: application/json { "nodes": [...], "edges": [...] } ``` #### 获取用户列表 ```http GET /api/users/list ``` #### 保存节点配置 ```http POST /api/nodes/save Content-Type: application/json { "nodeId": "n_xxx", "nodeData": {...} } ``` ### 文件管理 (endpoints_upload.py) #### 列出目录 ```http GET /api/files/list?path=users/guest&username=guest ``` #### 上传文件 ```http POST /api/files/upload?path=users/guest/data&username=guest Content-Type: multipart/form-data ``` #### 下载文件 ```http GET /api/files/download?path=users/guest/data/file.csv ``` #### 获取文件信息（用于检查文件是否存在） ```http GET /api/files/info?path=users/guest/data/file.csv Response: { "exists": true, "path": "users/guest/data/file.csv", "size": 1024, "modified": "2026-01-07T12:00:00" } ``` #### 文件操作 ```http POST /api/files/action Content-Type: application/json { "action": "delete|mkdir|rename", "path": "users/guest/data", "new_name": "new_folder" } ``` --- ## 🖥️ 配置说明 编辑 `system_config.yaml`： ```yaml server: host: "127.0.0.1" # 监听地址 port: 8000 # 监听端口 reload: true # 自动重载（开发模式） security: allowed_ips: - "*" # 允许的IP地址（*表示全部） block_parent_traversal: true # 阻止 ../ 路径遍历 allowed_extensions: - .utrace # 允许的文件扩展名 - .csv - .json storage: cloud_root: "../cloud" # 云存储根目录 user_dirs: # 用户子目录结构 - "data" - "workflows" - "results" - "cache" unreal: ue_editor_path: "C:/Program Files/Epic Games/UE_5.3/Engine/Binaries/Win64/UnrealEditor.exe" insights_path: "C:/Program Files/Epic Games/UE_5.3/Engine/Binaries/Win64/UnrealInsights.exe" logging: level: "INFO" # 日志级别 file: "../logs/server.log" max_size_mb: 10 ``` --- ## 🧩 扩展开发 ### 自定义节点 在 `custom_nodes/` 目录创建插件： ```python # custom_nodes/my_plugin.py from app.core.node_base import TraceNode class MyCustomNode(TraceNode): @staticmethod def get_metadata(): return { "display_name": "我的自定义节点", "category": "Custom", "inputs": [ {"name": "input_data", "type": "DataFrame"} ], "outputs": [ {"name": "output", "type": "Any"} ], "params": [ {"name": "threshold", "type": "float", "default": 0.5} ] } def execute(self, inputs): # 处理逻辑 result = ... return {"output": result} ``` --- ## 🔐 安全机制 ### 1. 路径安全检查 (security.py) - ✅ 阻止 `../` 路径遍历攻击 - ✅ 限制访问范围在用户目录内 - ✅ 使用 `Path.resolve()` 规范化路径 ### 2. 文件名验证 (security.py) - ✅ 禁止特殊字符: `< > : " | ? *` - ✅ 禁止Windows保留名: `CON`, `PRN`, `AUX`, `NUL` 等 - ✅ 清理路径字符串 ### 3. IP 白名单 - ⏳ 可配置允许的访问IP段（配置已创建，待实现中间件） --- ## 📦 依赖库 核心依赖： - `fastapi` - 现代Web框架 - `uvicorn` - ASGI服务器 - `pyyaml` - YAML配置解析 - `python-multipart` - 文件上传支持 - `pydantic` - 数据验证 --- ## 🧪 测试 ### 运行旧版服务器（供前端开发） ```bash cd server python tests/web1.1_server.py ``` 该服务器提供模拟数据，包含完整的旧版API实现。 ### 测试API ```bash # 健康检查 curl http://127.0.0.1:8000/ # 获取用户列表 curl http://127.0.0.1:8000/api/users/list # 列出文件 curl "http://127.0.0.1:8000/api/files/list?path=users/guest&username=guest" ``` --- ## 📝 开发规范 ### 代码组织 - `app/core/` - 核心功能，不依赖具体业务 - `app/api/` - API路由和请求处理 - `app/nodes/` - 内置节点实现 - `custom_nodes/` - 第三方扩展节点 ### 命名约定 - 文件名: `snake_case.py` - 类名: `PascalCase` - 函数名: `snake_case` - 常量: `UPPER_SNAKE_CASE` ### 导入规范 ```python # 标准库 import os from pathlib import Path # 第三方库 from fastapi import APIRouter # 本地模块 from app.core.user_manager import get_user_path ``` --- ## 🐛 故障排除 ### 1. 端口占用 ```bash # Windows netstat -ano | findstr :8000 taskkill /PID <进程ID> /F # Linux/Mac lsof -i :8000 kill -9 <进程ID> ``` ### 2. 模块导入错误 确保在 `server/` 目录下运行： ```bash cd d:\XGame\TraceStudio\server python main.py ``` ### 3. 配置文件错误 检查 `system_config.yaml` 格式是否正确，特别是缩进。 --- ## 🔄 版本历史 | 版本 | 日期 | 说明 | |------|------|------| | v2.0 | 2026-01-07 | 🎉 规范化架构重构，模块化设计 | | v1.1 | 2026-01-06 | 添加文件管理和多用户支持 | | v1.0 | 2026-01-05 | 初始版本 | --- ## 📋 开发状态 ### ✅ 已完成 - [x] 目录结构规范化 - [x] 用户目录管理 (user_manager.py) - [x] 路径安全检查 (security.py) - [x] 文件管理API (endpoints_upload.py) - [x] 图执行API骨架 (endpoints_graph.py) - [x] YAML配置系统 (system_config.yaml) - [x] 旧代码保留 (tests/web1.1_server.py) ### ⏳ 待实现 - [ ] 节点基类和类型系统 (node_base.py) - [ ] 装饰器注册系统 (registry.py) - [ ] DAG执行引擎 (executor.py) - [ ] 内置节点库 (nodes/io.py, logic.py, vis.py) - [ ] 缓存策略实现 - [ ] 多语言支持 (locales/) --- ## 📧 联系方式 - **Issues**: GitHub Issues - **文档**: [项目文档](../docs/)