---
title: FastViewer
emoji: 📁
colorFrom: gray
colorTo: blue
sdk: docker
pinned: false
---

# FastFileViewer

`FastFileViewer` 是一个基于 `Golang + Gin + React` 的 Web 文件浏览器，支持服务端异步任务：

- 在沙箱根目录内浏览、上传、删除、移动、重命名文件
- 发起服务端 URL 下载任务
- URL 下载支持 Range 分片并发加速（服务器不支持时自动回退单线程）
- 发起压缩包解压任务（支持 `.zip`、`.tar.gz`、`.tgz`）
- 使用 SQLite 持久化任务状态并展示进度

## 项目结构

- `backend/`：Gin API、鉴权、文件操作、任务执行器
- `frontend/`：React + Vite + Ant Design 前端界面
- `Dockerfile`：单容器生产镜像

## 本地运行（Windows PowerShell）

1. 确保 Go SDK 可用。你当前机器上可用路径是：
   - `C:\Users\liu_q\sdk\go1.25.0\bin\go.exe`
2. 直接启动后端（默认零配置）：

```powershell
cd backend
C:\Users\liu_q\sdk\go1.25.0\bin\go.exe mod tidy
C:\Users\liu_q\sdk\go1.25.0\bin\go.exe run ./cmd/server
```

3. 启动前端（新开一个终端）：

```powershell
cd frontend
npm install
npm run dev
```

浏览器访问：`http://localhost:5173`

说明：
- 如果没有设置 `ADMIN_PASSWORD`，服务启动时会自动生成一个临时管理员密码，并打印在后端日志中。
- `JWT_SECRET`、`ROOT_DIR`、`DB_PATH`、`MAX_WORKERS` 都由程序自动生成或自动创建，无需手动配置。

## API 一览

- `POST /api/login`
- `GET /api/fs/list?path=.`
- `POST /api/fs/upload`（form-data：`dir`、`file`）
- `POST /api/fs/move`
- `POST /api/fs/rename`
- `POST /api/fs/delete`
- `GET /api/fs/download?path=...`
- `POST /api/tasks/download`
- `POST /api/tasks/extract`
- `GET /api/tasks`
- `GET /api/tasks/:id`
- `GET /api/tasks/:id/stream`（SSE）

## 部署到 Hugging Face Space

项目已经按单容器部署方式配置：

1. 使用 `Dockerfile` 构建镜像
2. 环境变量只建议配置两个：
   - `PORT`（默认 `7860`）
   - `ADMIN_PASSWORD`（可选，不配则启动时自动生成）
3. 暴露端口：`PORT=7860`（或你自定义的端口）

## 安全说明

- 所有文件操作都限制在 `ROOT_DIR` 目录内
- 除登录与健康检查外，`/api/*` 都需要 JWT 鉴权
- 解压逻辑包含路径穿越防护