feat: enhance README with detailed core features and usage instructions

2026-05-07 03:22:40 +08:00 · 2026-02-09 17:56:50 +08:00
parent f8f85bddfb
commit ad6b335169
4 changed files with 176 additions and 54 deletions
--- 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)
--- a/CONTRIBUTING_zh.md
+++ b/CONTRIBUTING_zh.md
@@ -58,7 +58,7 @@
 ### 依赖准备

 - **Git**: 用于版本控制。
- **Python**: >= 3.13
+- **Python**: >= 3.14
 - **Bun**: 用于前端包管理和脚本运行。

 ### 后端 (FastAPI)
--- 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.
 <img src="https://foxel.cc/image/wechat.png" alt="WeChat Group QR Code" width="180">

 > 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).
--- 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 @@
 <img src="https://foxel.cc/image/wechat.png" alt="微信群二维码" width="180">

 > 如果二维码失效，请添加微信号 **drizzle2001**，我们会邀请你加入群聊。
+
+## 📄 许可证
+
+Foxel 基于 [MIT 许可证](LICENSE) 开源。