👀 在线演示

https://demo.foxel.cc

账号/密码: admin / admin

✨ 核心功能

📁 统一文件管理

集中管理分布在不同存储后端的文件。通过单一、统一的界面即可浏览、上传、下载、移动、复制和删除文件。

🔌 可插拔存储后端

采用可扩展的适配器模式，轻松集成多种存储类型：

类别	适配器
标准协议	本地、S3兼容、WebDAV、SFTP、FTP
云盘	Google Drive、OneDrive、Dropbox、Quark
特殊	Telegram、AList、Foxel-to-Foxel

🔍 AI驱动的语义搜索

超越文件名匹配——通过自然语言描述搜索图像、文档及其他非结构化数据中的内容。由可配置的嵌入提供商和向量数据库（Milvus、Qdrant）提供支持。

👁️ 内置文件预览

直接在浏览器中预览图片、视频、PDF、Office文档、文本和代码文件——无需下载。

🔐 权限与访问控制

功能完善的**基于角色的访问控制（RBAC）**系统，确保您的数据安全：

• 内置角色：三种系统角色——管理员（完全访问权限）、用户（可配置访问权限）和查看者（只读）。
• 自定义角色：创建具有细粒度系统和适配器权限的定制角色。
• 路径级规则：按路径定义读/写/删除/共享权限，支持通配符、正则表达式模式以及优先级规则排序。
• 审计日志：记录每个用户操作，具备完整追溯能力（用户、IP、方法、状态、耗时）。

🔗 共享

生成可配置过期时间的公开或受密码保护的共享链接。接收者无需登录即可浏览共享文件和文件夹。

🧩 插件系统

通过基于清单的插件架构扩展Foxel的功能。可在运行时加载React前端组件和自定义后端路由，无需修改核心代码库。

⚙️ 任务处理中心

运行异步后台任务——文件索引、数据备份、定时任务——而不会影响主应用程序。

🤖 AI智能体

集成AI智能体，内置用于VFS操作、网页抓取和文件处理的工具——将智能自动化直接引入您的云存储。

🌐 协议映射

通过熟悉的协议访问您的文件：

• S3 API — S3兼容端点，用于程序化访问
• WebDAV — 可作为网络驱动挂载到您的操作系统文件管理器中
• 直链 — 临时签名URL，用于直接访问文件

🛠️ 技术栈

层	技术
后端	Python 3.14+、FastAPI、Tortoise ORM、SQLite
前端	React 19、TypeScript、Vite、Ant Design
认证	JWT（OAuth2）、bcrypt
向量数据库	Milvus Lite / Server、Qdrant
部署	Docker、Gunicorn + Uvicorn
包管理器	uv（Python）、Bun（JS）

🚀 快速开始

使用Docker Compose是启动Foxel最推荐的方式。

1. 创建数据目录

创建一个用于持久化数据的data文件夹：

mkdir -p data/db data/mount
chmod 777 data/db data/mount

2. 下载Docker Compose文件

curl -L -O https://github.com/DrizzleTime/Foxel/raw/main/compose.yaml

下载后，强烈建议修改compose.yaml文件中的环境变量以确保安全性：

• 修改SECRET_KEY和TEMP_LINK_SECRET_KEY：将默认密钥替换为随机生成的强密钥。

3. 启动服务

docker-compose up -d

4. 访问应用

服务启动后，在浏览器中打开页面。

首次启动时，请按照设置指南初始化管理员账号。

🤝 如何贡献

我们欢迎社区的贡献！无论是提交Bug、提出新功能建议，还是直接贡献代码。

在开始之前，请阅读我们的CONTRIBUTING.md文件，其中介绍了开发环境和提交流程。简体中文翻译版本可在CONTRIBUTING_zh.md中找到。

🌐 社区

加入我们的Telegram社区（https://t.me/+thDsBfyqJxZkNTU1），与开发者和其他用户交流讨论！

您也可以加入我们的微信交流群，获取更实时的沟通和支持。请扫描下方二维码加入：

如果二维码无效，请添加微信号drizzle2001，我们将邀请您入群。

📄 许可证

Foxel根据MIT许可证开源。

Foxel 快速上手指南

Foxel 是一款高度可扩展的私有云存储解决方案，专为个人和团队设计，核心特色是支持 AI 驱动的语义搜索。它允许你统一管理分散在不同后端（如本地、S3、网盘等）的文件，并通过自然语言检索内容。

环境准备

在开始之前，请确保你的服务器或开发环境满足以下要求：

• 操作系统：Linux / macOS / Windows (需安装 Docker)
• 核心依赖：
  • Docker (推荐 v20.10+)
  • Docker Compose (推荐 v2.0+)
• 硬件建议：
  • 内存：至少 2GB RAM（若启用 AI 向量数据库如 Milvus/Qdrant，建议 4GB+）
  • 磁盘：根据存储需求配置，需预留空间给 data 目录

注意：本项目后端基于 Python 3.14+，前端基于 React 19，但通过 Docker 部署时无需在宿主机单独安装这些运行时环境。

安装步骤

使用 Docker Compose 是最推荐的部署方式，只需三步即可完成。

1. 创建数据持久化目录

在终端执行以下命令，创建用于存储数据库和挂载文件的目录，并设置权限：

mkdir -p data/db data/mount
chmod 777 data/db data/mount

2. 下载配置文件

获取官方的 compose.yaml 文件：

curl -L -O https://github.com/DrizzleTime/Foxel/raw/main/compose.yaml

国内加速提示：如果 curl 下载缓慢，可尝试使用镜像源：

curl -L -O https://ghproxy.net/https://github.com/DrizzleTime/Foxel/raw/main/compose.yaml

3. 配置安全密钥（重要）

在启动前，必须修改 compose.yaml 中的默认密钥以确保安全。使用编辑器打开文件：

nano compose.yaml
# 或使用 vim, code 等其他编辑器

找到并修改以下环境变量，将其替换为你生成的随机强字符串：

• SECRET_KEY
• TEMP_LINK_SECRET_KEY

4. 启动服务

执行以下命令后台启动所有服务：

docker-compose up -d

等待容器启动完成后，可通过 docker-compose ps 检查状态，确保所有服务均为 Up。

基本使用

1. 访问管理界面

在浏览器中打开部署地址（默认为本机 8080 端口，具体视 compose.yaml 配置而定）：

http://localhost:8080

2. 初始化管理员账户

首次访问时，系统将引导你完成初始化设置：

1. 按照页面提示创建 管理员账户（设置用户名和密码）。
2. 登录系统。

3. 添加存储后端

登录后，进入 设置 (Settings) -> 存储适配器 (Storage Adapters)：

• 点击“添加适配器”。
• 选择类型（如 Local 本地存储、S3、WebDAV 或 Google Drive 等）。
• 填写相应配置信息（例如本地路径或云厂商的 Access Key）。
• 保存后，即可在文件管理界面看到并操作该存储源的文件。

4. 体验 AI 语义搜索

上传一些文档或图片后，直接在顶部搜索框输入自然语言描述（例如：“查找去年的财务报表”或“包含猫的图片”），Foxel 将利用嵌入模型进行语义匹配，而不仅仅是文件名匹配。

---

更多高级功能（如权限控制、插件系统、AI Agent）请参考官方完整文档。