266 lines
5.6 KiB
Markdown
266 lines
5.6 KiB
Markdown
# TraceStudio 文件管理系统使用指南
|
||
|
||
## 📦 功能概览
|
||
|
||
TraceStudio 现已集成完整的多用户文件管理系统，支持：
|
||
|
||
- ✅ 多用户隔离的文件空间
|
||
- ✅ 文件上传、下载、删除、重命名
|
||
- ✅ 拖拽 CSV 文件到画布自动创建节点
|
||
- ✅ 共享资源和私有数据分离
|
||
- ✅ 轻量级用户切换（无需复杂鉴权）
|
||
|
||
---
|
||
|
||
## 🗂️ 目录结构
|
||
|
||
服务启动时会在 `cloud/` 目录下自动创建以下结构：
|
||
|
||
```
|
||
cloud/
|
||
├── shared/ # 共享资源区
|
||
│ └── examples/ # 示例数据
|
||
│ └── sample.csv
|
||
├── temp/ # 临时缓存区
|
||
└── users/ # 用户私有空间
|
||
├── guest/
|
||
│ ├── workflows/ # 工作流文件
|
||
│ ├── data/ # 数据文件
|
||
│ └── results/ # 结果输出
|
||
├── admin/
|
||
└── dev/
|
||
```
|
||
|
||
---
|
||
|
||
## 👤 用户切换
|
||
|
||
### 在 HeaderBar 右侧点击用户按钮
|
||
|
||
1. **快速切换**: 点击预设用户（guest、admin、dev）
|
||
2. **自定义用户**: 点击"+ 自定义用户名"输入任意用户名
|
||
3. **自动创建**: 切换到新用户时，系统自动创建对应目录
|
||
|
||
### 用户数据隔离
|
||
|
||
- 每个用户拥有独立的 `/users/{username}/` 目录
|
||
- 切换用户后，文件浏览器自动定位到该用户空间
|
||
- 工作流保存时默认存储在 `/users/{username}/workflows/`
|
||
|
||
---
|
||
|
||
## 📁 文件管理器
|
||
|
||
### 位置
|
||
左侧面板有两个标签：
|
||
- **📦 节点**: 原有的节点面板
|
||
- **📁 文件**: 新增的文件浏览器
|
||
|
||
### 基本操作
|
||
|
||
#### 1. 上传文件
|
||
```
|
||
点击"📤 上传"按钮 → 选择 .csv/.json/.utrace 文件
|
||
```
|
||
|
||
#### 2. 新建文件夹
|
||
```
|
||
点击"📁 新建"按钮 → 输入文件夹名称
|
||
```
|
||
|
||
#### 3. 右键菜单
|
||
- 文件: 下载、重命名、删除
|
||
- 文件夹: 重命名、删除
|
||
|
||
#### 4. 面包屑导航
|
||
点击路径中的任意层级快速返回
|
||
|
||
---
|
||
|
||
## 🎯 拖拽集成
|
||
|
||
### 将 CSV 文件拖入画布
|
||
|
||
1. 在文件浏览器中找到 `.csv` 文件
|
||
2. 按住鼠标左键拖动文件
|
||
3. 拖到画布中松开鼠标
|
||
4. **自动创建**: 系统自动生成 `CSVLoader` 节点
|
||
5. **自动填充**: `file_path` 参数自动填入文件的完整路径
|
||
|
||
### 示例流程
|
||
|
||
```
|
||
步骤1: 上传 data.csv 到 /users/guest/data/
|
||
步骤2: 拖拽 data.csv 到画布
|
||
步骤3: 自动生成节点:
|
||
┌─────────────────────┐
|
||
│ CSV 数据加载器 │
|
||
│ file_path: │
|
||
│ users/guest/data/ │
|
||
│ data.csv │
|
||
└─────────────────────┘
|
||
步骤4: 点击"运行预览"查看数据
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 API 接口
|
||
|
||
### 后端路由（FastAPI）
|
||
|
||
```python
|
||
GET /api/files/list?path=...&username=... # 列出目录
|
||
POST /api/files/upload # 上传文件
|
||
POST /api/files/action # 文件操作
|
||
GET /api/files/download?path=... # 下载文件
|
||
GET /api/files/info?path=... # 获取文件信息
|
||
```
|
||
|
||
### 文件操作
|
||
|
||
```typescript
|
||
// 删除文件
|
||
await fileAction({
|
||
action: 'delete',
|
||
path: 'users/guest/data/old.csv'
|
||
})
|
||
|
||
// 重命名
|
||
await fileAction({
|
||
action: 'rename',
|
||
path: 'users/guest/data/old.csv',
|
||
new_name: 'new.csv'
|
||
})
|
||
|
||
// 创建文件夹
|
||
await fileAction({
|
||
action: 'mkdir',
|
||
path: 'users/guest/data',
|
||
new_name: 'subfolder'
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 前端集成
|
||
|
||
```typescript
|
||
// 监听当前用户
|
||
const currentUser = useStore((s) => s.currentUser)
|
||
|
||
// 切换用户
|
||
const setCurrentUser = useStore((s) => s.setCurrentUser)
|
||
setCurrentUser('newuser')
|
||
|
||
// 获取当前路径
|
||
const currentPath = useStore((s) => s.currentPath)
|
||
```
|
||
|
||
### 后端扩展
|
||
|
||
```python
|
||
# 在 server/file_manager.py 中
|
||
# 添加新的文件操作
|
||
|
||
@router.post("/custom-action")
|
||
async def custom_file_action(data: dict):
|
||
# 自定义文件处理逻辑
|
||
pass
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 启动服务
|
||
|
||
```powershell
|
||
# 后端
|
||
cd server
|
||
python -m uvicorn main:app --reload
|
||
|
||
# 前端
|
||
cd web
|
||
npm run dev
|
||
```
|
||
|
||
### 2. 试用流程
|
||
|
||
1. 打开浏览器访问 `http://localhost:5173`
|
||
2. 点击右上角用户按钮，切换到 `guest`
|
||
3. 点击左侧"📁 文件"标签
|
||
4. 导航到 `shared/examples/`
|
||
5. 拖拽 `sample.csv` 到画布
|
||
6. 点击节点的"运行预览"按钮
|
||
7. 查看数据预览结果
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
### 安全性
|
||
- 当前实现为**轻量级用户切换**，无密码验证
|
||
- 适用于单机或受信任环境
|
||
- 生产环境建议添加 JWT/OAuth 鉴权
|
||
|
||
### 路径安全
|
||
- 所有路径经过 `sanitize_path()` 清理
|
||
- 防止目录遍历攻击（../ 等）
|
||
- 仅允许访问 `cloud/` 目录内的文件
|
||
|
||
### 文件大小
|
||
- 默认无上传限制
|
||
- 建议在生产环境配置 `client_max_body_size`
|
||
|
||
---
|
||
|
||
## 🎨 UI 提示
|
||
|
||
### 文件图标
|
||
|
||
- 📁 文件夹
|
||
- 📊 CSV 文件
|
||
- 📋 JSON 文件
|
||
- 🔍 UTrace 文件
|
||
- 🖼️ 图片文件
|
||
- 📄 其他文件
|
||
|
||
### 状态指示
|
||
|
||
- 加载中：显示"加载中..."
|
||
- 空文件夹：显示"此文件夹为空"
|
||
- 错误：显示红色错误消息
|
||
|
||
---
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q1: 拖拽没有反应？
|
||
A: 确保文件是 `.csv` 格式，其他格式目前不支持直接拖拽
|
||
|
||
### Q2: 文件上传失败？
|
||
A: 检查后端是否正常运行，查看浏览器控制台错误
|
||
|
||
### Q3: 切换用户后文件不见了？
|
||
A: 正常现象，不同用户有独立的文件空间
|
||
|
||
### Q4: 文件路径显示错误？
|
||
A: 路径使用 `/` 分隔，相对于 `cloud/` 目录
|
||
|
||
---
|
||
|
||
## 📞 支持
|
||
|
||
遇到问题或有建议？
|
||
- 查看浏览器控制台日志
|
||
- 查看后端终端输出
|
||
- 检查 `cloud/` 目录权限
|
||
|
||
---
|
||
|
||
**版本**: v0.2.0
|
||
**更新日期**: 2026-01-07
|
||
**作者**: TraceStudio Team
|