Skip to content
BranchesTags

Repository files navigation

Pan Drive - Hugging Face 在线网盘

基于 Cloudflare Pages + Hugging Face Datasets 的纯前端在线网盘系统。

核心特点：无需自建服务器，100GB 免费存储空间，纯静态前端，全部请求由浏览器直连 Hugging Face API。

Cloudflare D1 持久化存储（可选）

用于跨浏览器/设备保持文件状态一致，解决因 HF API 缓存延迟导致的文件显示异常。

配置步骤

1. 创建数据库

Cloudflare Dashboard → Workers & Pages → D1 → Create database

填写数据库名称 hf-pan-db，创建完成后复制 Database ID。

2. 创建表

进入 D1 数据库详情页 → Console 标签，粘贴以下 SQL 并执行：

CREATE TABLE IF NOT EXISTS pending_files (
  path TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  size INTEGER NOT NULL DEFAULT 0,
  type TEXT NOT NULL DEFAULT 'file',
  last_modified TEXT NOT NULL DEFAULT '',
  download_url TEXT NOT NULL DEFAULT '',
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

3. 绑定到 Pages

进入你的 Pages 项目 → Settings → Functions → D1 database bindings

点击 Add binding：

  • Binding name: DB
  • Database: 选择 hf-pan-db

4. 重新部署

Pages 项目 → Deployments → 找到上一次部署 → Deploy most recent commit，或重新推送代码触发自动部署。

项目简介

Pan Drive 是一个纯静态前端项目，利用 Hugging Face Dataset 仓库作为文件存储后端，通过 Cloudflare Pages 零成本部署。

  • 文件存储：Hugging Face 数据集仓库（最高 100GB 免费额度）
  • 部署平台：Cloudflare Pages（免费计划）
  • 运行方式：纯浏览器端，所有 API 请求从浏览器直连 Hugging Face
  • 配置方式：通过环境变量注入 API Key 和仓库 ID

功能列表

功能 说明
文件上传 单文件/多文件批量上传，实时进度条
文件管理 新建文件夹、重命名、删除、移动
文件预览 图片预览、文本文件在线查看（支持 Markdown、JSON 等）
文件下载 一键下载、获取文件直链分享链接
目录导航 面包屑导航，多级文件夹支持
文件搜索 在当前目录搜索文件名
存储统计 展示仓库已用空间和总容量
视图切换 网格视图/列表视图切换
主题切换 亮色/暗色主题自由切换

部署前置准备

1. 创建 Hugging Face 数据集仓库

  1. 注册/登录 Hugging Face
  2. 点击右上角头像 → New Dataset
  3. 填写仓库名称（如 my-pan）
  4. 选择 Public 或 Private
  5. 点击 Create dataset 完成创建
  6. 记下仓库 ID，格式为 用户名/仓库名（如 tud8951/my-pan）

2. 获取 HF API Key

  1. 访问 Hugging Face Settings - Tokens
  2. 点击 New token
  3. 填写名称（如 pan-drive）
  4. 权限选择 write（需要写入权限以支持文件上传和删除）
  5. 点击 Generate token
  6. 复制并保存生成的 Token（关闭页面后将无法再次查看）

3. 准备 Cloudflare 账号

  1. 注册/登录 Cloudflare Dashboard
  2. 进入 Workers & Pages 页面

Cloudflare Pages 部署步骤

方法一：通过 Git 仓库部署（推荐）

  1. 将本项目的代码推送到 GitHub/GitLab 仓库

  2. 在 Cloudflare Dashboard 中进入 Workers & Pages → Create → Pages → Connect to Git

  3. 选择包含本项目代码的仓库

  4. 在 Set up builds and deployments 页面配置：

    配置项 值
    框架预设 None
    构建命令 npm install && npm run build
    构建输出目录 dist
    根目录（可选） /

  5. 在 Environment variables (advanced) 中添加以下环境变量：

    变量名 值 说明
    HF_API_KEY hf_xxxxxxxxxxxx (代理模式) Hugging Face API Key，由 Pages Function 使用
    HF_REPO_ID your-username/your-repo (代理模式) 数据集仓库 ID，自动填充到前端
    VITE_USE_PROXY true (代理模式) 启用 Pages Function 代理
    VITE_HF_API_KEY hf_xxxxxxxxxxxx (直连模式) 前端直连 HF 时使用
    VITE_HF_REPO_ID your-username/your-repo (直连模式) 数据集仓库 ID

    推荐使用代理模式：API Key 存储在服务端，不暴露给浏览器，安全性更高。

  6. 点击 Save and Deploy 开始部署

  7. 部署完成后，Cloudflare 会提供一个 *.pages.dev 域名供访问

方法二：通过上传文件部署

  1. 在本地执行构建命令：

    npm install
npm run build

  2. 构建产物在 dist/ 目录下

  3. 在 Cloudflare Dashboard 进入 Workers & Pages → Create → Pages → Upload directly

  4. 上传 dist/ 目录中的所有文件

  5. 进入 Settings → Environment variables，添加上述环境变量

  6. 重新部署以使环境变量生效

本地开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview

开发时，可以通过在项目根目录创建 .env 文件来配置环境变量：

VITE_HF_API_KEY=hf_your_api_key_here
VITE_HF_REPO_ID=your-username/your-repo

注意：.env 文件包含敏感信息，已被 .gitignore 忽略，请勿提交到版本控制。

代理模式说明

项目支持两种运行模式：

代理模式（推荐用于生产部署）

通过 Cloudflare Pages Function (functions/api/[[catchall]].ts) 代理所有 API 请求：

  • API Key 存储在服务端（HF_API_KEY 环境变量），不暴露给浏览器
  • 解决 CORS 限制：请求通过同域转发
  • 自动配置：如果同时设置了 HF_REPO_ID，前端会自动检测并跳过配置步骤

代理模式下，前端设置 VITE_USE_PROXY=true，所有 /api/* 请求由 Pages Function 转发到 Hugging Face。

直连模式（本地开发）

浏览器直接请求 Hugging Face API：

  • 需要在 Cloudflare Pages 配置 VITE_HF_API_KEY 和 VITE_HF_REPO_ID，或者在前端配置页面手动输入
  • API Key 暴露给浏览器
  • 本地开发时无需 Pages Function

环境变量说明

所有配置均在 Cloudflare Pages 的环境变量中设置，无需修改源代码。

变量名 是否必填 说明
VITE_HF_API_KEY 直连模式 是 / 代理模式 否 Hugging Face 个人访问令牌（需要 write 权限），代理模式由 Pages Function 处理
VITE_HF_REPO_ID 直连模式 是 / 代理模式 可选 数据集仓库 ID，格式 username/repo-name
VITE_USE_PROXY 否 设置为 true 启用代理模式（通过 Pages Function 转发请求）

项目结构

hf-pan/
├── public/
│   ├── _redirects              # Cloudflare Pages 路由重定向
│   ├── _headers                # Cloudflare Pages 安全头
│   └── favicon.svg             # 网站图标
├── functions/
│   └── api/
│       ├── [[catchall]].ts     # Cloudflare Pages Function API 代理
│       └── d1.ts               # D1 持久化存储 API（可选）
├── src/
│   ├── api/
│   │   └── hf.ts               # Hugging Face Dataset REST API 封装
│   ├── components/
│   │   ├── Common/
│   │   │   ├── Breadcrumb.tsx   # 面包屑导航
│   │   │   ├── ConfigSetup.tsx  # 初始配置页面
│   │   │   ├── SearchBar.tsx    # 搜索输入框
│   │   │   ├── StorageBar.tsx   # 存储空间进度条
│   │   │   └── Toast.tsx        # 通知提示
│   │   ├── Layout/
│   │   │   ├── Sidebar.tsx      # 侧边栏（目录树、视图切换、主题切换）
│   │   │   └── TopBar.tsx       # 顶部操作栏
│   │   ├── FileList/
│   │   │   ├── FileTable.tsx    # 列表视图
│   │   │   └── FileGrid.tsx     # 网格视图
│   │   ├── Dialogs/
│   │   │   ├── UploadDialog.tsx  # 上传弹窗
│   │   │   ├── NewFolderDialog.tsx # 新建文件夹弹窗
│   │   │   ├── RenameDialog.tsx  # 重命名弹窗
│   │   │   ├── DeleteDialog.tsx  # 删除确认弹窗
│   │   │   └── ShareDialog.tsx   # 分享链接弹窗
│   │   └── Preview/
│   │       ├── ImagePreview.tsx  # 图片预览灯箱
│   │       └── TextPreview.tsx   # 文本文件预览
│   ├── hooks/
│   │   ├── useFileList.ts       # 文件列表管理 Hook
│   │   ├── useUpload.ts         # 文件上传管理 Hook
│   │   └── useTheme.ts          # 主题管理 Hook
│   ├── stores/
│   │   └── appStore.ts          # Zustand 全局状态
│   ├── types/
│   │   └── index.ts             # TypeScript 类型定义
│   ├── utils/
│   │   ├── env.ts               # 环境变量读取工具
│   │   └── format.ts            # 格式化工具
│   ├── App.tsx                  # 应用入口
│   ├── index.css                # 全局样式
│   └── main.tsx                 # 渲染入口
├── migrations/
│   └── 0001_create_pending_files.sql  # D1 数据库迁移
├── index.html                   # HTML 入口
├── package.json                 # 项目依赖
├── vite.config.ts               # Vite 构建配置
├── wrangler.toml                # Wrangler 配置（D1 绑定）
├── tailwind.config.js           # Tailwind CSS 配置
├── tsconfig.json                # TypeScript 配置
└── README.md                    # 本文件

已知限制

Hugging Face API 速率限制

Hugging Face 对 API 调用有速率限制：

限制类型 免费额度
请求频率 ~100 次/分钟
单文件上传大小 建议 < 50MB
总存储容量 每个仓库 100GB

对于大文件（>50MB），上传可能需要更长时间且更容易因网络问题中断。

功能限制

  • Hagging Face 的文件操作不提供原生的事务支持，重命名操作采用"下载-上传-删除"模式，在极端情况下可能导致文件丢失
  • 不支持文件夹的直接下载（仅支持单个文件下载）
  • 搜索功能为前端实现，仅搜索当前已加载的目录内容
  • 基于 Hugging Face Dataset 的 API 设计，不支持文件版本历史

浏览器兼容性

  • 需要较新版本的现代浏览器（Chrome 90+、Firefox 90+、Edge 90+、Safari 15+）
  • 需要启用 JavaScript

技术栈

技术 用途
React 18 前端框架
TypeScript 类型安全
Vite 构建工具
Tailwind CSS 样式框架
Zustand 状态管理
Lucide React 图标库
Cloudflare Pages 部署平台
Hugging Face Datasets API 文件存储后端

License

MIT

About

Pan Drive在线网盘 基于 Cloudflare Pages + Hugging Face Datasets 的纯前端在线网盘系统。

Topics

cloudflarecloudflarepagesgithubhuggingface

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages