252 lines
6.1 KiB
Markdown
252 lines
6.1 KiB
Markdown
# 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
|
||
|
||
```yaml
|
||
storage:
|
||
# 云存储根目录（相对于项目根目录 TraceStudio/）
|
||
cloud_root: "./cloud"
|
||
|
||
# 自定义节点目录（相对于项目根目录 TraceStudio/）
|
||
custom_nodes_dir: "./custom_nodes"
|
||
|
||
# 用户目录结构
|
||
user_dirs:
|
||
- "data" # 数据文件
|
||
- "workflows" # 工作流文件
|
||
- "results" # 结果文件
|
||
- "cache" # 缓存文件
|
||
```
|
||
|
||
## 🔍 路径解析逻辑
|
||
|
||
### 1. 项目根目录识别
|
||
|
||
```python
|
||
# server/app/core/user_manager.py
|
||
# 项目根目录 = server/ 的上一级目录
|
||
project_root = Path(__file__).parent.parent.parent.parent
|
||
# 示例: D:\XGame\TraceStudio
|
||
```
|
||
|
||
### 2. cloud_root 路径
|
||
|
||
```python
|
||
# 从配置文件读取相对路径
|
||
cloud_root_rel = config['storage']['cloud_root'] # "./cloud"
|
||
|
||
# 解析为绝对路径
|
||
CLOUD_ROOT = (project_root / cloud_root_rel).resolve()
|
||
# 结果: D:\XGame\TraceStudio\cloud
|
||
```
|
||
|
||
### 3. custom_nodes 路径
|
||
|
||
```python
|
||
# 从配置文件读取相对路径
|
||
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. 备份数据
|
||
|
||
```powershell
|
||
# 如果 server/cloud 存在
|
||
Copy-Item -Recurse server\cloud TraceStudio_cloud_backup
|
||
|
||
# 如果 server/custom_nodes 存在
|
||
Copy-Item -Recurse server\custom_nodes TraceStudio_nodes_backup
|
||
```
|
||
|
||
### 2. 移动到正确位置
|
||
|
||
```powershell
|
||
# 移动 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. 删除错误目录
|
||
|
||
```powershell
|
||
Remove-Item -Recurse -Force server\cloud
|
||
Remove-Item -Recurse -Force server\custom_nodes
|
||
```
|
||
|
||
### 4. 重启服务器验证
|
||
|
||
```powershell
|
||
cd server
|
||
python -m uvicorn server.main:app --reload
|
||
```
|
||
|
||
查看启动日志：
|
||
```
|
||
✅ 文件系统初始化完成: D:\XGame\TraceStudio\cloud
|
||
🔌 自定义节点: 2/2 个已加载
|
||
```
|
||
|
||
## 🐛 故障排查
|
||
|
||
### 问题1: 找不到 cloud 目录
|
||
|
||
**症状**: `FileNotFoundError: cloud/`
|
||
|
||
**解决**:
|
||
```powershell
|
||
# 检查是否在正确位置
|
||
cd D:\XGame\TraceStudio
|
||
if (!(Test-Path cloud)) { mkdir cloud }
|
||
```
|
||
|
||
### 问题2: 路径显示 server/cloud
|
||
|
||
**症状**: 日志显示 `D:\XGame\TraceStudio\server\cloud`
|
||
|
||
**解决**: 检查 `system_config.yaml` 配置是否正确：
|
||
```yaml
|
||
storage:
|
||
cloud_root: "./cloud" # ✅ 正确
|
||
# cloud_root: "../cloud" # ❌ 错误（会指向 server/../cloud = 根目录/cloud）
|
||
```
|
||
|
||
### 问题3: custom_nodes 未加载
|
||
|
||
**症状**: `🔌 自定义节点: 0/0 个已加载`
|
||
|
||
**检查清单**:
|
||
1. 确认 `custom_nodes/` 在根目录
|
||
2. 确认有 `__init__.py` 文件
|
||
3. 确认 `.py` 文件语法正确
|
||
4. 查看详细错误日志
|
||
|
||
## 📊 验证命令
|
||
|
||
```powershell
|
||
# 验证目录结构
|
||
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"
|
||
```
|
||
|
||
---
|
||
|
||
**重要提示**: 修改目录结构后，必须重启服务器才能生效！
|