TraceStudio-dev/docs/server1.2/DIRECTORY_STRUCTURE.md

# 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"
```

---

**重要提示**: 修改目录结构后，必须重启服务器才能生效！