diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5aa29bb..3101ad6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ Follow the development setup below before opening a pull request. Keep changes f Install the following tooling first: - **Git** for version control -- **Python** 3.13 or newer +- **Python** 3.14 or newer - **Bun** for frontend package management and scripts ### Backend (FastAPI) diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md index 10ba8e5..c739a14 100644 --- a/CONTRIBUTING_zh.md +++ b/CONTRIBUTING_zh.md @@ -58,7 +58,7 @@ ### 依赖准备 - **Git**: 用于版本控制。 -- **Python**: >= 3.13 +- **Python**: >= 3.14 - **Bun**: 用于前端包管理和脚本运行。 ### 后端 (FastAPI) diff --git a/README.md b/README.md index 9d500d6..2aecba0 100644 --- a/README.md +++ b/README.md @@ -29,48 +29,105 @@ ## ✨ Core Features -- **Unified File Management**: Centralize management of files distributed across different storage backends. -- **Pluggable Storage Backends**: Utilizes an extensible adapter pattern to easily integrate various storage types. -- **Semantic Search**: Supports natural language search for content within unstructured data like images and documents. -- **Built-in File Preview**: Preview images, videos, PDFs, Office documents, text, and code files directly without downloading. -- **Permissions and Sharing**: Supports public or private sharing links for easy file distribution. -- **Task Processing Center**: Supports asynchronous task processing, such as file indexing and data backups, without impacting the main application. +### 📁 Unified File Management + +Centralize management of files distributed across different storage backends. Browse, upload, download, move, copy, and delete — all through a single, unified interface. + +### 🔌 Pluggable Storage Backends + +Utilizes an extensible adapter pattern to easily integrate various storage types: + +| Category | Adapters | +|---|---| +| **Standard Protocols** | Local, S3-compatible, WebDAV, SFTP, FTP | +| **Cloud Drives** | Google Drive, OneDrive, Dropbox, Quark | +| **Special** | Telegram, AList, Foxel-to-Foxel | + +### 🔍 AI-Powered Semantic Search + +Go beyond filename matching — search by natural language descriptions to find content within images, documents, and other unstructured data. Powered by configurable embedding providers and vector databases (Milvus, Qdrant). + +### 👁️ Built-in File Preview + +Preview images, videos, PDFs, Office documents, text, and code files directly in the browser — no downloads required. + +### 🔐 Permissions & Access Control + +A full-featured **Role-Based Access Control (RBAC)** system to secure your data: + +- **Built-in Roles**: Three system roles — **Admin** (full access), **User** (configurable access), and **Viewer** (read-only). +- **Custom Roles**: Create tailored roles with fine-grained system and adapter permissions. +- **Path-based Rules**: Define read / write / delete / share permissions per path, with support for **wildcards**, **regex patterns**, and **priority-based rule ordering**. +- **Audit Logging**: Every user action is recorded with full traceability (user, IP, method, status, duration). +### 🔗 Sharing + +Generate public or password-protected share links with configurable expiration dates. Recipients can browse shared files and folders without logging in. + +### 🧩 Plugin System + +Extend Foxel's capabilities through a manifest-based plugin architecture. Load React frontend components and custom backend routes at runtime, without modifying the core codebase. + +### ⚙️ Task Processing Center + +Run asynchronous background tasks — file indexing, data backups, scheduled jobs — without impacting the main application. + +### 🤖 AI Agent + +An integrated AI agent with built-in tools for VFS operations, web fetching, and file processing — bringing intelligent automation directly into your cloud storage. + +### 🌐 Protocol Mappings + +Access your files through familiar protocols: + +- **S3 API** — S3-compatible endpoint for programmatic access +- **WebDAV** — Mount as a network drive in your OS file manager +- **Direct Links** — Temporary signed URLs for direct file access + +## 🛠️ Tech Stack + +| Layer | Technologies | +|---|---| +| **Backend** | Python 3.14+, FastAPI, Tortoise ORM, SQLite | +| **Frontend** | React 19, TypeScript, Vite, Ant Design | +| **Auth** | JWT (OAuth2), bcrypt | +| **Vector DB** | Milvus Lite / Server, Qdrant | +| **Deployment** | Docker, Gunicorn + Uvicorn | +| **Package Managers** | uv (Python), Bun (JS) | ## 🚀 Quick Start Using Docker Compose is the most recommended way to start Foxel. -1. **Create Data Directories** +### 1. Create Data Directories - Create a `data` folder for persistent data: +Create a `data` folder for persistent data: - ```bash - mkdir -p data/db - mkdir -p data/mount - chmod 777 data/db data/mount - ``` +```bash +mkdir -p data/db data/mount +chmod 777 data/db data/mount +``` -2. **Download Docker Compose File** +### 2. Download Docker Compose File - ```bash - curl -L -O https://github.com/DrizzleTime/Foxel/raw/main/compose.yaml - ``` +```bash +curl -L -O https://github.com/DrizzleTime/Foxel/raw/main/compose.yaml +``` - After downloading, it is **strongly recommended** to modify the environment variables in the `compose.yaml` file to ensure security: +After downloading, it is **strongly recommended** to modify the environment variables in the `compose.yaml` file to ensure security: - - Modify `SECRET_KEY` and `TEMP_LINK_SECRET_KEY`: Replace the default keys with randomly generated strong keys. +- Modify `SECRET_KEY` and `TEMP_LINK_SECRET_KEY`: Replace the default keys with randomly generated strong keys. -3. **Start the Services** +### 3. Start the Services - ```bash - docker-compose up -d - ``` +```bash +docker-compose up -d +``` -4. **Access the Application** +### 4. Access the Application - Once the services are running, open the page in your browser. +Once the services are running, open the page in your browser. - > On the first launch, please follow the setup guide to initialize the administrator account. +> On the first launch, please follow the setup guide to initialize the administrator account. ## 🤝 How to Contribute @@ -87,3 +144,7 @@ You can also join our WeChat group for more real-time communication and support. WeChat Group QR Code > If the QR code is invalid, please add WeChat ID **drizzle2001**, and we will invite you to the group. + +## 📄 License + +Foxel is open-sourced under the [MIT License](LICENSE). diff --git a/README_zh.md b/README_zh.md index f299ad0..61f946d 100644 --- a/README_zh.md +++ b/README_zh.md @@ -29,48 +29,105 @@ ## ✨ 核心功能 -- **统一文件管理**：集中管理分布于不同存储后端的文件。 -- **插件化存储后端**：采用可扩展的适配器模式，方便集成多种存储类型。 -- **语义搜索**：支持自然语言描述搜索图片、文档等非结构化数据内容。 -- **内置文件预览**：可直接预览图片、视频、PDF、Office 文档及文本、代码文件，无需下载。 -- **权限与分享**：支持公开或私密分享链接，便于文件共享。 -- **任务处理中心**：支持异步任务处理，如文件索引和数据备份，不影响主应用运行。 +### 📁 统一文件管理 + +集中管理分布于不同存储后端的文件。浏览、上传、下载、移动、复制和删除——全部通过统一的界面完成。 + +### 🔌 插件化存储后端 + +采用可扩展的适配器模式，方便集成多种存储类型： + +| 分类 | 适配器 | +|---|---| +| **标准协议** | 本地存储、S3 兼容存储、WebDAV、SFTP、FTP | +| **网盘服务** | Google Drive、OneDrive、Dropbox、夸克网盘 | +| **特殊类型** | Telegram、AList、Foxel 互联 | + +### 🔍 AI 语义搜索 + +突破文件名匹配的局限——通过自然语言描述搜索图片、文档等非结构化数据的内容。由可配置的 Embedding 服务和向量数据库（Milvus、Qdrant）驱动。 + +### 👁️ 内置文件预览 + +可直接在浏览器中预览图片、视频、PDF、Office 文档及文本、代码文件，无需下载。 + +### 🔐 权限与访问控制 + +完善的 **基于角色的访问控制（RBAC）** 系统，全方位保障数据安全： + +- **内置角色**：三个系统角色 — **管理员**（完全访问）、**用户**（可配置访问权限）、**观察者**（只读访问）。 +- **自定义角色**：可创建自定义角色，灵活分配系统权限和适配器权限。 +- **路径级权限规则**：为每个路径定义 读取 / 写入 / 删除 / 分享 权限，支持 **通配符**、**正则表达式** 匹配和 **优先级排序**。 +- **审计日志**：记录所有用户操作，包含完整的追溯信息（用户、IP、请求方法、状态码、耗时）。 +### 🔗 文件分享 + +生成公开或加密的分享链接，支持设置过期时间。接收方无需登录即可浏览分享的文件和文件夹。 + +### 🧩 插件系统 + +通过基于清单（Manifest）的插件架构扩展 Foxel 的功能。支持在运行时加载 React 前端组件和自定义后端路由，无需修改核心代码。 + +### ⚙️ 任务处理中心 + +支持异步后台任务——文件索引、数据备份、定时作业——不影响主应用运行。 + +### 🤖 AI 智能助手 + +内置 AI Agent，提供 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. **创建数据目录** +### 1. 创建数据目录 - 新建 `data` 文件夹用于持久化数据： +新建 `data` 文件夹用于持久化数据： - ```bash - mkdir -p data/db - mkdir -p data/mount - chmod 777 data/db data/mount - ``` +```bash +mkdir -p data/db data/mount +chmod 777 data/db data/mount +``` -2. **下载 Docker Compose 文件** +### 2. 下载 Docker Compose 文件 - ```bash - curl -L -O https://github.com/DrizzleTime/Foxel/raw/main/compose.yaml - ``` +```bash +curl -L -O https://github.com/DrizzleTime/Foxel/raw/main/compose.yaml +``` - 下载完成后，**强烈建议**修改 `compose.yaml` 文件中的环境变量以确保安全： +下载完成后，**强烈建议**修改 `compose.yaml` 文件中的环境变量以确保安全： - - 修改 `SECRET_KEY` 和 `TEMP_LINK_SECRET_KEY`：将默认的密钥替换为随机生成的强密钥 +- 修改 `SECRET_KEY` 和 `TEMP_LINK_SECRET_KEY`：将默认的密钥替换为随机生成的强密钥。 -3. **启动服务** +### 3. 启动服务 - ```bash - docker-compose up -d - ``` +```bash +docker-compose up -d +``` -4. **访问应用** +### 4. 访问应用 - 服务启动后，在浏览器中打开页面。 +服务启动后，在浏览器中打开页面。 - > 首次启动，请根据引导页面完成管理员账号的初始化设置。 +> 首次启动，请根据引导页面完成管理员账号的初始化设置。 ## 🤝 如何贡献 @@ -87,3 +144,7 @@ 微信群二维码 > 如果二维码失效，请添加微信号 **drizzle2001**，我们会邀请你加入群聊。 + +## 📄 许可证 + +Foxel 基于 [MIT 许可证](LICENSE) 开源。