WinSCP 风格的双栏文件管理器，支持本地/远程文件浏览、零拷贝下载、WebRTC P2P 传输和 WebDAV 协议访问。
FluxFile/
├── backend/ # FastAPI 后端服务
│ ├── app/
│ │ ├── api/ # API 路由
│ │ │ ├── auth.py # 认证 (JWT 登录/token)
│ │ │ ├── fs.py # 文件系统操作 (列表/下载/哈希/增删改)
│ │ │ ├── health.py # 健康检查
│ │ │ └── signaling.py # WebRTC 信令 (WebSocket)
│ │ ├── core/ # 核心配置
│ │ │ ├── config.py # pydantic-settings 配置
│ │ │ ├── security.py # JWT + bcrypt 密码
│ │ │ ├── dependencies.py # 依赖注入 (FastFSLoader 单例)
│ │ │ └── logging.py # 日志配置
│ │ ├── services/
│ │ │ └── filesystem.py # 文件系统服务 (路径校验/CRUD)
│ │ ├── integrations/
│ │ │ └── webdav.py # WebDAV 集成 (WsgiDAV)
│ │ ├── utils/
│ │ │ └── responses.py # 流式文件响应 / Range / ZIP 打包
│ │ └── main.py # FastAPI 应用入口
│ ├── tests/ # pytest 测试 (22 tests)
│ └── requirements.txt
├── frontend/ # React 18 + Vite 前端
│ ├── src/
│ │ ├── components/ # VirtualFileTable / FilePanel / P2PTransferPanel
│ │ ├── hooks/ # useLocalFileSystem / useWebRTC
│ │ ├── layouts/ # CommanderLayout (双栏布局)
│ │ ├── stores/ # Zustand 状态管理
│ │ ├── types/ # TypeScript 类型定义
│ │ └── utils/ # 工具函数
│ ├── package.json
│ └── vite.config.ts
├── cpp_src/ # C++ Pybind11 扩展
│ ├── fast_fs.cpp # 高性能文件操作 (GIL 释放 + BLAKE3)
│ ├── CMakeLists.txt
│ └── third_party/ # BLAKE3 (构建时自动下载)
├── scripts/
│ └── build.sh # C++ 扩展编译脚本
├── setup.py # Python 扩展构建 (CMakeExtension)
├── pyproject.toml # 项目配置 (ruff/mypy/pytest)
└── .env.example # 环境变量模板
| 层 | 技术 |
|---|---|
| 前端 | React 18 + TypeScript + Vite + Zustand + Tailwind CSS + @tanstack/react-virtual |
| 后端 | Python FastAPI (ASGI) + Pydantic v2 |
| 性能核心 | C++17 Pybind11 — fast_fs 扩展 (GIL 释放 + BLAKE3 并行哈希) |
| 文件传输 | aiofiles 异步流式 + HTTP Range 断点续传 |
| P2P | WebRTC (WebSocket 信令服务器) |
| WebDAV | WsgiDAV (挂载于 /webdav) |
| 认证 | JWT (python-jose) + bcrypt (passlib) |
| 数据库 | ClickHouse (审计日志, TODO) + Redis (缓存, TODO) |
# 复制环境变量模板并修改
cp .env.example .env
# 重要配置项:
# FLUX_SECRET_KEY=<生成密钥: python -c "import secrets; print(secrets.token_urlsafe(32))">
# FLUX_ADMIN_USERNAME=admin
# FLUX_ADMIN_PASSWORD=<你的密码>
# FLUX_DEBUG=true # 开发模式跳过认证# 方式一: pip 开发模式安装
pip install -e .
# 方式二: 使用构建脚本
./scripts/build.sh --installpip install -r backend/requirements.txt
cd backend && uvicorn app.main:app --reloadcd frontend
npm install
npm run dev系统使用 JWT 认证保护文件系统 API。
# 1. 获取 token
curl -X POST http://localhost:8000/api/auth/token \
-d "username=admin&password=your_password"
# 返回: {"access_token": "eyJ...", "token_type": "bearer"}
# 2. 携带 token 访问 API
curl http://localhost:8000/api/fs/list?path=/ \
-H "Authorization: Bearer eyJ..."| 模式 | 行为 |
|---|---|
FLUX_DEBUG=true |
跳过认证，所有 API 可匿名访问 |
FLUX_DEBUG=false |
/api/fs/* 需要 Bearer token，/api/health/* 和 /api/auth/* 公开 |
| 方法 | 路径 | 说明 | 认证 |
|---|---|---|---|
| POST | /api/auth/token |
登录获取 JWT | - |
| GET | /api/auth/me |
当前用户信息 | ✓ |
| GET | /api/fs/list |
列出目录内容 | ✓ |
| GET | /api/fs/info |
文件详细信息 | ✓ |
| GET | /api/fs/download |
下载文件 (支持 Range) | ✓ |
| GET | /api/fs/hash |
计算 BLAKE3 哈希 | ✓ |
| POST | /api/fs/hash/batch |
批量哈希 (多线程) | ✓ |
| POST | /api/fs/mkdir |
创建目录 | ✓ |
| DELETE | /api/fs/delete |
删除文件/目录 | ✓ |
| POST | /api/fs/move |
移动/重命名 | ✓ |
| POST | /api/fs/copy |
复制 | ✓ |
| GET | /api/health/* |
健康检查 | - |
完整文档: http://localhost:8000/api/docs (Swagger UI)
cd backend
python -m pytest tests/ -v覆盖路径安全验证、JWT 认证、密码哈希和 API 集成测试。
# 后端 (端口 8000)
lsof -ti :8000 | xargs kill -9
# 前端 (端口 5173)
lsof -ti :5173 | xargs kill -9