TraceStudio-dev/server

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 环境（推荐）

conda create -n tracestudio python=3.11
conda activate tracestudio

2. 安装依赖

cd server
pip install -r requirements.txt

3. 启动服务器

方式一：规范化服务器 (v2.0 - 推荐)

python main.py

方式二：旧版测试服务器 (v1.1 - 供前端测试)

python tests/web1.1_server.py

4. 访问 API 文档

• 交互式文档: http://127.0.0.1:8000/docs
• 替代文档: http://127.0.0.1:8000/redoc

---

🔌 API 接口

健康检查

GET /

图执行相关 (endpoints_graph.py)

获取节点插件列表

GET /api/plugins

节点预览

POST /api/node/preview
Content-Type: application/json

{
  "nodeId": "n_xxx",
  "nodeType": "CSVLoader",
  "params": {...}
}

图执行

POST /api/graph/execute
Content-Type: application/json

{
  "nodes": [...],
  "edges": [...]
}

获取用户列表

GET /api/users/list

保存节点配置

POST /api/nodes/save
Content-Type: application/json

{
  "nodeId": "n_xxx",
  "nodeData": {...}
}

文件管理 (endpoints_upload.py)

列出目录

GET /api/files/list?path=users/guest&username=guest

上传文件

POST /api/files/upload?path=users/guest/data&username=guest
Content-Type: multipart/form-data

下载文件

GET /api/files/download?path=users/guest/data/file.csv

获取文件信息（用于检查文件是否存在）

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"
}

文件操作

POST /api/files/action
Content-Type: application/json

{
  "action": "delete|mkdir|rename",
  "path": "users/guest/data",
  "new_name": "new_folder"
}

---

🖥️ 配置说明

编辑 system_config.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/ 目录创建插件：

# 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 - 数据验证

---

🧪 测试

运行旧版服务器（供前端开发）

cd server
python tests/web1.1_server.py

该服务器提供模拟数据，包含完整的旧版API实现。

测试API

# 健康检查
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

导入规范

# 标准库
import os
from pathlib import Path

# 第三方库
from fastapi import APIRouter

# 本地模块
from app.core.user_manager import get_user_path

---

🐛 故障排除

1. 端口占用

# Windows
netstat -ano | findstr :8000
taskkill /PID <进程ID> /F

# Linux/Mac
lsof -i :8000
kill -9 <进程ID>

2. 模块导入错误

确保在 server/ 目录下运行：

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	初始版本

---

📋 开发状态

✅ 已完成

• 目录结构规范化
• 用户目录管理 (user_manager.py)
• 路径安全检查 (security.py)
• 文件管理API (endpoints_upload.py)
• 图执行API骨架 (endpoints_graph.py)
• YAML配置系统 (system_config.yaml)
• 旧代码保留 (tests/web1.1_server.py)

⏳ 待实现

• 节点基类和类型系统 (node_base.py)
• 装饰器注册系统 (registry.py)
• DAG执行引擎 (executor.py)
• 内置节点库 (nodes/io.py, logic.py, vis.py)
• 缓存策略实现
• 多语言支持 (locales/)

---

📧 联系方式

• Issues: GitHub Issues
• 文档: 项目文档