ouczbs/TraceStudio-dev

Fork 0

Boshuang Zhao 1c6906c955 Tracestudio web1.1 支持文件管理器

2026-01-07 21:31:22 +08:00

5.6 KiB

Raw Blame History

TraceStudio 文件管理系统使用指南

📦 功能概览

TraceStudio 现已集成完整的多用户文件管理系统，支持：

✅ 多用户隔离的文件空间
✅ 文件上传、下载、删除、重命名
✅ 拖拽 CSV 文件到画布自动创建节点
✅ 共享资源和私有数据分离
✅ 轻量级用户切换（无需复杂鉴权）

🗂️ 目录结构

服务启动时会在 cloud/ 目录下自动创建以下结构：

cloud/
├── shared/          # 共享资源区
│   └── examples/    # 示例数据
│       └── sample.csv
├── temp/            # 临时缓存区
└── users/           # 用户私有空间
    ├── guest/
    │   ├── workflows/   # 工作流文件
    │   ├── data/        # 数据文件
    │   └── results/     # 结果输出
    ├── admin/
    └── dev/

👤 用户切换

在 HeaderBar 右侧点击用户按钮

快速切换: 点击预设用户（guest、admin、dev）
自定义用户: 点击"+ 自定义用户名"输入任意用户名
自动创建: 切换到新用户时，系统自动创建对应目录

用户数据隔离

每个用户拥有独立的 /users/{username}/ 目录
切换用户后，文件浏览器自动定位到该用户空间
工作流保存时默认存储在 /users/{username}/workflows/

📁 文件管理器

位置

左侧面板有两个标签：

📦 节点: 原有的节点面板
📁 文件: 新增的文件浏览器

基本操作

1. 上传文件

点击"📤 上传"按钮 → 选择 .csv/.json/.utrace 文件

2. 新建文件夹

点击"📁 新建"按钮 → 输入文件夹名称

3. 右键菜单

文件: 下载、重命名、删除
文件夹: 重命名、删除

4. 面包屑导航

点击路径中的任意层级快速返回

🎯 拖拽集成

将 CSV 文件拖入画布

在文件浏览器中找到 .csv 文件
按住鼠标左键拖动文件
拖到画布中松开鼠标
自动创建: 系统自动生成 CSVLoader 节点
自动填充: file_path 参数自动填入文件的完整路径

示例流程

步骤1: 上传 data.csv 到 /users/guest/data/
步骤2: 拖拽 data.csv 到画布
步骤3: 自动生成节点:
   ┌─────────────────────┐
   │  CSV 数据加载器      │
   │  file_path:         │
   │  users/guest/data/  │
   │         data.csv    │
   └─────────────────────┘
步骤4: 点击"运行预览"查看数据

🔌 API 接口

后端路由（FastAPI）

GET  /api/files/list?path=...&username=...   # 列出目录
POST /api/files/upload                       # 上传文件
POST /api/files/action                       # 文件操作
GET  /api/files/download?path=...            # 下载文件
GET  /api/files/info?path=...                # 获取文件信息

文件操作

// 删除文件
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'
})

🛠️ 开发指南

前端集成

// 监听当前用户
const currentUser = useStore((s) => s.currentUser)

// 切换用户
const setCurrentUser = useStore((s) => s.setCurrentUser)
setCurrentUser('newuser')

// 获取当前路径
const currentPath = useStore((s) => s.currentPath)

后端扩展

# 在 server/file_manager.py 中
# 添加新的文件操作

@router.post("/custom-action")
async def custom_file_action(data: dict):
    # 自定义文件处理逻辑
    pass

🚀 快速开始

1. 启动服务

# 后端
cd server
python -m uvicorn main:app --reload

# 前端
cd web
npm run dev

2. 试用流程

打开浏览器访问 http://localhost:5173
点击右上角用户按钮，切换到 guest
点击左侧"📁 文件"标签
导航到 shared/examples/
拖拽 sample.csv 到画布
点击节点的"运行预览"按钮
查看数据预览结果

📝 注意事项

安全性

当前实现为轻量级用户切换，无密码验证
适用于单机或受信任环境
生产环境建议添加 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

5.6 KiB Raw Blame History Unescape Escape