6.1 KiB
6.1 KiB
TraceStudio 目录结构说明
📁 项目根目录结构
TraceStudio/ # 项目根目录
├── cloud/ # ✅ 云存储根目录（所有用户共享）
│ ├── shared/ # 共享文件目录
│ ├── temp/ # 临时文件目录
│ └── users/ # 用户私有目录
│ ├── guest/ # guest用户目录
│ │ ├── data/ # 数据文件
│ │ ├── workflows/ # 工作流文件
│ │ ├── results/ # 结果文件
│ │ └── cache/ # 缓存文件
│ └── ouczbs/ # ouczbs用户目录
│ └── ...
│
├── custom_nodes/ # ✅ 自定义节点目录（所有用户共享）
│ ├── __init__.py # Python包标识
│ └── example_nodes.py # 示例节点（如有）
│
├── server/ # 后端服务器代码
│ ├── app/ # 应用代码
│ ├── main.py # 启动入口
│ ├── system_config.yaml # ✅ 系统配置文件
│ └── users.json # 用户数据库
│
├── web/ # 前端代码
│ ├── src/
│ └── ...
│
└── docs/ # 文档目录
└── ...
⚙️ 配置文件说明
system_config.yaml
storage:
# 云存储根目录（相对于项目根目录 TraceStudio/）
cloud_root: "./cloud"
# 自定义节点目录（相对于项目根目录 TraceStudio/）
custom_nodes_dir: "./custom_nodes"
# 用户目录结构
user_dirs:
- "data" # 数据文件
- "workflows" # 工作流文件
- "results" # 结果文件
- "cache" # 缓存文件
🔍 路径解析逻辑
1. 项目根目录识别
# server/app/core/user_manager.py
# 项目根目录 = server/ 的上一级目录
project_root = Path(__file__).parent.parent.parent.parent
# 示例: D:\XGame\TraceStudio
2. cloud_root 路径
# 从配置文件读取相对路径
cloud_root_rel = config['storage']['cloud_root'] # "./cloud"
# 解析为绝对路径
CLOUD_ROOT = (project_root / cloud_root_rel).resolve()
# 结果: D:\XGame\TraceStudio\cloud
3. custom_nodes 路径
# 从配置文件读取相对路径
custom_nodes_rel = config['storage']['custom_nodes_dir'] # "./custom_nodes"
# 解析为绝对路径
custom_nodes_dir = (project_root / custom_nodes_rel).resolve()
# 结果: D:\XGame\TraceStudio\custom_nodes
🚫 注意事项
❌ 不要创建以下目录
- ❌
server/cloud/- 错误位置 - ❌
server/custom_nodes/- 错误位置 - ❌
web/cloud/- 错误位置
✅ 正确的目录位置
- ✅
TraceStudio/cloud/- 正确 - ✅
TraceStudio/custom_nodes/- 正确
📝 目录用途说明
cloud/ 目录
用途: 云存储文件系统根目录
访问权限:
shared/- 所有用户可读写temp/- 所有用户可读写（临时文件）users/{username}/- 仅对应用户可访问
特点:
- 文件管理器展示的根目录
- 所有上传的数据文件存储在此
- 支持多级子目录
示例路径:
cloud/shared/datasets/data.csv # 共享数据集
cloud/users/guest/workflows/flow.json # 用户工作流
cloud/temp/upload_12345.tmp # 临时文件
custom_nodes/ 目录
用途: 自定义节点代码存储
访问权限:
- 所有用户共享（读取）
- 需要验证+确认（修改/删除）
特点:
- 仅存储
.py文件 - 代码会被动态加载到系统
- 必须通过安全验证
示例文件:
custom_nodes/__init__.py # Python包标识
custom_nodes/data_filter.py # 数据过滤节点
custom_nodes/text_processor.py # 文本处理节点
🔄 迁移指南
如果之前在错误位置创建了目录，请按以下步骤迁移：
1. 备份数据
# 如果 server/cloud 存在
Copy-Item -Recurse server\cloud TraceStudio_cloud_backup
# 如果 server/custom_nodes 存在
Copy-Item -Recurse server\custom_nodes TraceStudio_nodes_backup
2. 移动到正确位置
# 移动 cloud 内容
if (Test-Path server\cloud\users) {
Copy-Item -Recurse server\cloud\* cloud\
}
# 移动 custom_nodes 内容
if (Test-Path server\custom_nodes\*.py) {
Copy-Item server\custom_nodes\*.py custom_nodes\
}
3. 删除错误目录
Remove-Item -Recurse -Force server\cloud
Remove-Item -Recurse -Force server\custom_nodes
4. 重启服务器验证
cd server
python -m uvicorn server.main:app --reload
查看启动日志：
✅ 文件系统初始化完成: D:\XGame\TraceStudio\cloud
🔌 自定义节点: 2/2 个已加载
🐛 故障排查
问题1: 找不到 cloud 目录
症状: FileNotFoundError: cloud/
解决:
# 检查是否在正确位置
cd D:\XGame\TraceStudio
if (!(Test-Path cloud)) { mkdir cloud }
问题2: 路径显示 server/cloud
症状: 日志显示 D:\XGame\TraceStudio\server\cloud
解决: 检查 system_config.yaml 配置是否正确：
storage:
cloud_root: "./cloud" # ✅ 正确
# cloud_root: "../cloud" # ❌ 错误（会指向 server/../cloud = 根目录/cloud）
问题3: custom_nodes 未加载
症状: 🔌 自定义节点: 0/0 个已加载
检查清单:
- 确认
custom_nodes/在根目录 - 确认有
__init__.py文件 - 确认
.py文件语法正确 - 查看详细错误日志
📊 验证命令
# 验证目录结构
cd D:\XGame\TraceStudio
Get-ChildItem -Directory | Where-Object { $_.Name -in 'cloud', 'custom_nodes', 'server', 'web' }
# 预期输出:
# cloud
# custom_nodes
# server
# web
# 验证配置文件
Get-Content server\system_config.yaml | Select-String "cloud_root|custom_nodes_dir"
# 预期输出:
# cloud_root: "./cloud"
# custom_nodes_dir: "./custom_nodes"
重要提示: 修改目录结构后，必须重启服务器才能生效！