内容
<div align="center">
# 文件管理器 — 可嵌入任意位置的自托管文件管理器
[](https://github.com/BRF-Tech/filex/releases)
[](https://github.com/BRF-Tech/filex/actions)
[](LICENSE)
[](https://github.com/BRF-Tech/filex/pkgs/container/filex)
[](https://demo.filex.sh)
一个单一的Go二进制文件，包含一个功能齐全的Web UI，可插拔的存储/身份验证/数据库驱动程序，**实时协作**，**可嵌入的Web组件**，以及一个**内置的MCP服务器**，使AI代理可以原生驱动它。
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/explorer-grid-dark.png">
<img src="docs/screenshots/explorer-grid-light.png" alt="文件管理器 —缩略图网格" width="900">
</picture>
</div>
## 立即试用
**在线演示：** [demo.filex.sh](https://demo.filex.sh) — 使用 `demo@demo.com` / `demo` 登录（管理员角色，沙盒每晚重置）。或者，在一行命令中运行自己的实例：
```bash
docker run -p 5212:5212 -v $(pwd)/data:/data ghcr.io/brf-tech/filex:latest
```
打开 http://localhost:5212/admin — 首次运行时，打印管理员凭证和嵌入说明到控制台。
## 为什么选择文件管理器
大多数自托管文件管理器要么 **太小** （一个带有上传功能的目录列表），要么 **太大** （一个您为文件选项卡部署的群件套件）。文件管理器旨在填补这一空白：
- **可嵌入任意位置** — 相同的UI作为Vue 3组件、React组件和框架无关的`<filex-explorer>` Web组件。 在您的产品中放置一个真正的文件管理器，由您自己的文件管理器服务器支持，并锁定到每个租户的文件夹。
- **AI代理原生** — 一个令牌范围的REST接口（`/api/ai`）和一个原生的 **MCP服务器** （`/api/ai/mcp`）。 给代理一个令牌，限定在一个文件夹中，它可以列出、读取、写入、共享和压缩 — 没有其他操作。
- **实时** — 存在头像和实时文件更新通过WebSocket，在原生UI和嵌入式上下文中（短时令牌身份验证，API轮询回退）。
- **多租户设计** — 存储每个租户，具有原生租户模式，RBAC角色 +每个项目授予权限，限定API令牌，每个令牌身份用于审计跟踪。
- **可部署** — 一个二进制文件或一个容器； 默认使用SQLite，Postgres/MySQL需要时使用； 每个驱动程序通过环境变量切换。
```
┌─────────────────────────────────────────────────────────────┐
│ 文件管理器 （Go二进制文件，~40 MB精简 / 250 MB带缩略图） │
├─────────────────────────────────────────────────────────────┤
│ HTTP API (chi) │ 管理员UI（Vue 3，嵌入式） │
│ 身份验证驱动： │ 本地 · oidc · ldap · 代理头 │
│ 存储驱动： │ 本地 · s3 · ftp · sftp · webdav │
│ 数据库驱动： │ sqlite（默认）· mysql · postgres │
│ 队列驱动： │ sqlite（默认）· redis · postgres │
│ 实时： │ WebSocket存在 + 实时更新 │
│ RBAC： │ 角色 + 项目授予权限 + 共享邀请 │
│ AI / MCP： │ /api/ai REST + 原生MCP服务器 │
│ 同步工作线程： │ ETag差异 +墓碑守护 │
│ 副本层： │ 主→副本 + 规则 + 调节 │
│ 通知： │ webhook + 应用内铃声 + 已读/未读 │
│ 搜索： │ Bleve（全文，嵌入式） │
│ 缩略图： │ 图片 · 视频 · pdf · 办公软件 │
│ 即插即用： │ OnlyOffice · Drawio · Mermaid │
└─────────────────────────────────────────────────────────────┘
▲
│ HTTP API
┌──────────────────┼──────────────────┐
│ │ │
@brftech/ @brftech/ @brftech/
filex-core filex filex-react
(Vue 3 SFC) (Web组件) (React适配器)
│ │ │
▼ ▼ ▼
Vue 3应用 任意框架 React应用
（原生，Angular，
Svelte，Solid，…）
```
## 截图
| 共享（PIN + 过期链接） | Markdown编辑器 + 预览 |
|---|---|
|  |  |
| 管理面板 | 演示登录 |
|---|---|
|  |  |
## 快速开始 — 二进制文件
```bash
# 从 https://github.com/BRF-Tech/filex/releases 下载
./filex serve
```
```
═══════════════════════════════════════════════════════════════
文件管理器 · 自托管文件管理器
═══════════════════════════════════════════════════════════════
监听地址： http://0.0.0.0:5212
管理员UI： http://0.0.0.0:5212/admin
嵌入JS： http://0.0.0.0:5212/embed.js
首次运行检测到。 创建了初始管理员用户：
电子邮件： admin@local
密码： kT9_x4Pq2Nm-BvLs
保存到： ~/.filex/.first-run.txt （模式 0600，仅显示一次）
更改位置： /admin/profile
═══════════════════════════════════════════════════════════════
```
## 使用Compose或Helm自托管
上述裸露的 `docker run` 命令足以试用文件管理器。对于真正的部署，准备好的堆栈位于 [`deploy/`](deploy/)：
- **[`deploy/compose/`](deploy/compose/)** — Docker Compose：
- **最小** — 文件管理器 + SQLite + 本地磁盘（一个服务，零依赖项）。
- **完整** — 文件管理器 + PostgreSQL + Redis + Caddy（自动HTTPS），以及可切换的附加组件：**OnlyOffice**，**Drawio**，通用**转换器**，**MinIO**（S3）。在 `.env` 中使用Compose配置文件打开/关闭每个功能。
- **[`deploy/helm/filex/`](deploy/helm/filex/)** — Kubernetes的Helm图表（部署 + PVC +可选Ingress）。上述每个附加组件都是`values.yaml`中的`enabled`切换选项 — 捆绑PostgreSQL / Redis / MinIO，或连接外部OnlyOffice / Drawio /转换器。
每个层的逐步说明在
[docs/INSTALLATION.md](docs/INSTALLATION.md)。
## 嵌入到您的应用中
### Vue 3
```bash
pnpm add @brftech/filex-core
```
```vue
<script setup>
import { FileExplorer } from '@brftech/filex-core';
import '@brftech/filex-core/style.css';
</script>
<template>
<FileExplorer :config="{ apiBase: 'http://localhost:5212', auth: { kind: 'bearer', token: '…' } }" />
</template>
```
### React
```bash
pnpm add @brftech/filex-react
```
```jsx
import { FileManager } from '@brftech/filex-react';
<FileManager config={{ apiBase: 'http://localhost:5212' }} onError={(e) => console.error(e)} />
```
### 原生JS / 任意框架
```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@brftech/filex/dist/filex.js"></script>
<filex-explorer api-base="http://localhost:5212"></filex-explorer>
```
多租户主机通常在服务器端代理API，注入一个**限定令牌**（`root: 租户文件夹`）到每个请求中，并剥离客户端标头 — 沙盒由后端而非小部件强制执行。参见 [docs/INTEGRATION.md](docs/INTEGRATION.md)。
## AI代理 / MCP
文件管理器在 `/api/ai` 处提供一个令牌身份验证的自动化接口（列出、读取、写入、移动、删除、搜索、共享、压缩），并在 `/api/ai/mcp` 处使用 **模型上下文协议**：
```bash
claude mcp add filex --transport http https://files.example.com/api/ai/mcp \
--header "Authorization: Bearer <api-token>"
```
令牌按动词范围（`read,write,delete,share`），可选 **限定到单个文件夹**，由与UI相同的RBAC授予权限控制，并带有每个令牌的身份标识，以便审计日志、共享和存在显示 **谁**（哪个集成）做了什么。
详情： [docs/MCP.md](docs/MCP.md)。
## 功能
- **多存储** — 同时挂载多个存储（本地，S3，FTP，SFTP，WebDAV）；每个存储作为顶级文件夹显示。
- **实时协作** — 存在栏带有实时头像 + 焦点，文件变更实时更新通过WebSocket，轮询回退。
- **RBAC + 项目权限** — 角色，每个文件/文件夹的权限，具有继承性，通过电子邮件（SMTP）邀请共享，授予感知搜索和列表。
- **共享** — 公共链接带有PIN，过期时间和最大下载次数；文件夹链接以ZIP流式传输（缓存 + 预热）； **文件请求**上传链接用于接收文件； ShareX兼容的上传端点。
- **原生多租户** — 提供商/租户模式，具有单个实例上的租户隔离（[docs/MULTI-TENANCY.md](docs/MULTI-TENANCY.md)）。
- **驱动程序可插拔** — 存储 / 身份验证 / 数据库 / 队列驱动程序通过环境变量（`FILEX_AUTH_DRIVERS=local,oidc`，`FILEX_QUEUE_DRIVER=postgres`，…）可选。
- **OIDC SSO优先** — 可选自动重定向到您的IdP，具有突破玻璃的本地登录（`?local=1`）。
- **副本 + 调节** — 主→副本分发（镜像 / 追加-仅 / 跳过按路径-全局规则），读取回退，计划状态报告，一键“修复所有”。
- **持久操作队列** — 重启安全队列（SQLite / Redis / Postgres），带有重试 + 取消 + 管理员仪表盘的工作线程池。
- **数据库支持的文件树** — 列表来自数据库缓存（1-5毫秒），而不是存储后端（〜100毫秒）；周期性ETag差异同步捕获带外更改。
- **查看器和编辑器** — 图片/视频/音频，PDF，Markdown（分割编辑器 + 预览），CSV，代码（Monaco），Office通过OnlyOffice，Drawio + Mermaid图表，3D模型。
- **通用转换器** — 可选的边车转换文档/图像格式从UI。
- **通知** — 通用JSON webhook（Slack/Discord-agnostic）+ 应用内铃声，带有已读/未读 + 每用户静音矩阵。
- **搜索** — 嵌入式Bleve，全文 + 元数据，权限感知。
- **缩略图** — 图片，视频（ffmpeg），PDF（ghostscript），Office（libreoffice）；功能感知。
- **深链接** — 地址栏跟踪打开的文件夹；粘贴链接，跳转到该文件夹。
- **审计日志** — 每个变更记录带有执行者，集成身份和元数据。
- **单个二进制文件** — goreleaser矩阵：linux/macOS/Windows × amd64/arm64。 CGO=0，modernc.org/sqlite。
- **i18n** — 英文 + 土耳其语开箱即用。
## 架构
参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 文档
- [安装](docs/INSTALLATION.md)
- [配置](docs/CONFIGURATION.md)
- [集成 / 嵌入](docs/INTEGRATION.md)
- [AI & MCP](docs/MCP.md)
- [RBAC & 权限](docs/RBAC.md)
- [多租户](docs/MULTI-TENANCY.md)
- [复制](docs/REPLICATION.md)
- [后端API规范](docs/BACKEND.md)
- [组件API](docs/API.md)
- [Docker](docs/DOCKER.md)
- [完整文档索引](docs/README.md)
## 开发
```bash
git clone https://github.com/BRF-Tech/filex.git
cd filex
pnpm install
pnpm run build:all # 构建软件包，网页，然后是Go二进制文件
./bin/filex serve
```
子目录：
- `backend/` — Go HTTP服务（cmd/filex，internal/*，db/queries，db/migrations）
- `packages/core` — `@brftech/filex-core`（Vue 3 SFC，真实来源）
- `packages/webcomponent` — `@brftech/filex`（Web组件包装器）
- `packages/react` — `@brftech/filex-react`（React适配器通过@lit/react）
- `web/` — Vue 3管理员UI（嵌入到Go二进制文件中通过`go:embed`）
- `demo/` — 每个框架的独立HTML演示
- `docker/` — Dockerfiles + compose
- `deploy/` — 准备好的Compose堆栈 + Helm图表（参见 [`deploy/`](deploy/））
- `docs/` — Markdown文档
欢迎贡献 — 参见 [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
