388 lines
8.5 KiB
Markdown
388 lines
8.5 KiB
Markdown
# 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/)
|