FileRise 介绍与选型指南

目标：全面认识 FileRise——一款 MIT 协议、免数据库的自托管 Web 文件管理器与存储中枢，梳理其定位、架构、功能特性，并与同类主流组件（Directory Lister、FileGator、Tiny File Manager）做量化对比，为自建网盘/文件管理场景选型提供依据。本文为认知篇，全部信息来自官方仓库、官方文档站与官方发布件的联网溯源，查询日期 2026-10-30，未做本地部署实测；部署实操见《FileRise 3.38 Docker Compose 部署指南》。

一、环境信息

本文是联网溯源的认知篇，不依赖本地运行环境。溯源来源与当日查询结果如下（查询日期均为 2026-10-30）：

⚠️ 说明：GitHub 仓库页与 Releases 页当时直连抓取返回空内容，本文版本号、星数、协议均改经 shields.io 徽章 JSON 接口取证，该渠道当日实测可用；溯源检索共使用官方文档站、shields.io、awesome-selfhosted 三个来源，交叉印证仓库归属与版本。

二、软件概述

FileRise 的官方定位是「自托管的 Web 文件管理器与存储中枢（self-hosted web file manager and storage hub）」，一句话概括它的形态：一个用 PHP 编写、不需要数据库、把整个站点的状态落在三个数据目录里的 Web 网盘。它覆盖了个人/小团队自建网盘的全部高频需求：拖拽批量上传、断点续传（分块）、在线预览（图片/视频/PDF）、在线文本编辑、重命名/复制/移动/删除与回收站、分享链接（可带密码与有效期）、按文件夹的访问控制（ACL）、WebDAV 挂载，以及可选的文件夹级静态加密与 OnlyOffice 协同编辑集成。

从工程形态看，FileRise 属于「传统 PHP 应用 + 现代前端」的组合：服务端是标准的 PHP 8.3+ 应用（Composer 依赖、public/ 目录作为 Web 根），前端是单页应用；数据面则刻意做了「零数据库」设计——文件落在上传目录，用户与站点配置落在 users 目录（JSON/文本文件，敏感项加密存储），文件元数据与 ACL 落在 metadata 目录。这意味着备份 = 复制三个目录，迁移 = 拷走三个目录，对个人自托管用户非常友好。

FileRise 采用 MIT 协议，另有可选的 FileRise Pro 扩展包（审计日志、全局搜索、对象存储源、门户表单等增强能力），核心功能完全开源，不强制付费。

💡 技术拓展：「文件管理器」类自托管组件按交互模式可分为四类——

类型	代表	特点
只读列目录	Directory Lister	仅展示目录内容与下载，无上传/管理能力
轻量单文件管理	Tiny File Manager	单个 PHP 文件即部署，功能全面但工程化程度低
完整 Web 文件管理	FileGator / FileRise	多用户、上传下载、权限控制，工程化程度高
企业网盘	Nextcloud / Seafile	账号体系、同步客户端、应用生态，依赖数据库

FileRise 属于第三类中功能面最宽的一款（WebDAV、ACL、加密、OnlyOffice 均内置），本文第七章将给出量化对比。

三、核心架构

以下架构信息均实查自官方发布件 FileRise-v3.38.0.zip（来源标注：官方 Release v3.38.0，查询日期 2026-10-30）与官方文档站。

1. 技术栈分层

• 服务端：PHP 8.3+（官方文档明确要求 PHP 8.3 以上，扩展仅需 json、curl、zip 与标准默认扩展），Composer 管理依赖，发布 ZIP 内已带 vendor/ 全量依赖，免 composer install 即可运行；
• Web 服务器：Apache / Nginx / Caddy + PHP-FPM 均可（官方文档「Manual install」章节），DocumentRoot 指向应用内的 public/ 子目录；
• 前端：public/ 下的单页应用（index.html + js/css 资源），经 REST API 与服务端交互；
• WebDAV：内置 SabreDAV 库实现，入口为 public/webdav.php，使用独立的 HTTP Basic 认证（与浏览器会话无关）；
• 接口：REST API 集中在 public/api/（认证、文件、文件夹、上传、管理、分享、Totp、OnlyOffice 等域），并随发布件提供 OpenAPI 规范文件 openapi.json.dist（111 个端点定义）。

2. 「三目录」数据模型（零数据库设计）

官方默认的三个数据目录（可经 PHP 常量或环境变量重定向，见《FileRise 3.38 配置参数详解》）：

这套设计带来的直接好处：无 MySQL/PostgreSQL 依赖，备份与迁移等同于「复制三个目录」；代价是多实例共享存储时需要自行保证目录的一致性（官方单文件夹定位即是围绕单实例设计）。

3. 存储源抽象

v3.38 的源码中存在存储源配置层（SourcesConfig），除本地目录外还定义了 webdav、s3、sftp、ftp、smb、gdrive、onedrive、dropbox 等远端源类型；其中远端源挂载属 Pro 扩展能力，核心版默认提供 local 本地源。

四、功能特性

以下功能清单综合自官方文档站、官方仓库描述与 Release v3.38.0 发布件实查（查询日期 2026-10-30）：

• 上传与传输：拖拽批量上传、分块断点续传（可配置分块大小与 TTL）、上传去重检查（checkExisting）、单发与分块两种上传路径；
• 文件管理：重命名、复制、移动、删除（进回收站）、从回收站恢复与彻底清空、ZIP 打包下载、在线解压（含安全黑名单校验）、在线文本编辑保存、文件标签（tag）；
• 视图与预览：表格视图与画廊视图、图片/视频/PDF 在线预览、悬停预览（大小阈值可配）、PDF 缩略图（可接外部二进制）、视频缩略图（可接 ffmpeg）、媒体播放进度记忆；
• 分享：文件/文件夹分享链接、分享上传链接（他人可向指定目录投递）、分享有效期与访问控制、门户表单（Pro）；
• 权限：多用户与角色（管理员/普通用户）、逐文件夹 ACL（继承可配）、默认权限策略（仅看自己的文件、禁止分享/压缩等）、TOTP 两步验证、登录失败限速；
• WebDAV：全局开关由管理员控制（默认关闭），HTTP Basic 认证，可挂载为本地磁盘/网盘客户端远端；
• 安全：CSRF 令牌防护、请求名规范化（上传名安全策略）、ClamAV 病毒扫描接口（环境变量注入命令）、文件夹级静态加密（主密钥经环境变量注入）、审计日志（Pro）；
• 运维：站点健康探针、磁盘用量扫描（内置 worker）、OpenAPI 规范导出、站点配置/品牌定制（Logo、配色、页脚 HTML、登录页文案）；
• OIDC 单点登录：支持 OIDC 提供商配置（提供商 URL、客户端凭据、组声明映射管理员组、自动建号）。

五、快速开始（最小可用示例）

以下为官方文档「Installation & Setup」给出的 Docker Compose 最小部署形态（来源：filerise.net/docs，页面标注 Last updated Jan 18, 2026；查询日期 2026-10-30）。FileRise 官方推荐两种部署路径——官方 Docker 镜像（内置 Apache+PHP，开箱即用）与手动安装（自备 nginx/Apache/Caddy + PHP-FPM）；本节引用官方镜像形态，nginx+PHP-FPM 的完整实测部署见《FileRise 3.38 Docker Compose 部署指南》：

services:
  filerise:
    image: error311/filerise-docker:latest
    container_name: filerise
    ports:
      - "8080:80"
    environment:
      TIMEZONE: "America/New_York"
      TOTAL_UPLOAD_SIZE: "10G"
      SECURE: "false"
      PERSISTENT_TOKENS_KEY: "change_me"
      SCAN_ON_START: "true"     # 一次性扫描
      CHOWN_ON_START: "true"    # 首次启动归一化 uploads/metadata 权限
    volumes:
      - ./uploads:/var/www/uploads
      - ./users:/var/www/users
      - ./metadata:/var/www/metadata

首次访问 http://<服务器IP>:8080 即进入管理员创建页（无用户时的初始化引导），建号后进入文件管理界面。官方同时提示：权限就绪后建议将 CHOWN_ON_START 改为 false，避免每次启动递归 chown；PERSISTENT_TOKENS_KEY 应设置为强随机值；TLS 反代后应将 SECURE 置为 true。

若选择手动安装：将 Release ZIP 解压到 /var/www/filerise，DocumentRoot 指向 /var/www/filerise/public，并创建 /var/www/uploads、/var/www/users、/var/www/metadata 三个目录且授予 Web 进程用户（如 www-data）写权限，即完成部署的全部服务端准备。

六、适用场景与限制

适用场景（与官方定位及功能清单对应）：

• 个人/小团队的自建网盘：免数据库、三目录备份、分享链接与回收站齐备；
• 已有文件服务器「加一层 Web 管理」：把 FileRise 上传根指向既有目录（官方建议挂子目录而非海量盘根），立刻获得 Web 上传/管理/预览能力；
• 需要 WebDAV 挂载的文件区：开启内置 WebDAV 后，桌面/移动客户端可像网盘一样挂载读写；
• 内网文件中转与投递：分享上传链接 + 门户表单（Pro）适合向外部收集文件。

限制与注意：

• 官方定位为「单文件夹/单实例」管理器，非多节点集群存储；多实例部署需自行解决共享存储与并发一致性；
• 核心版存储源仅本地目录，S3/SMB/远端 WebDAV 等源属 Pro 扩展；
• 仅审计日志、全局搜索、门户、对象存储源等增强能力在 Pro 侧，核心版以 MIT 全量开源但不包含这些项；
• 运行要求 PHP 8.3+（官方明确最低版本），旧 PHP 环境需升级后部署。

七、同类选型对比

在 awesome-selfhosted 的「File Transfer - Web-based File Managers」分类下，与 FileRise 同类且最常被一起比较的三款 PHP 组件为 Directory Lister、FileGator 与 Tiny File Manager。下表数据均经 shields.io 徽章 JSON 取证（版本、星数、协议，查询日期 2026-10-30）与各官方资料交叉核对：

解读与选型建议：

• 若目标是「极简只读文件目录站」（如软件镜像站、静态资源列表），Directory Lister 最轻，但它没有上传与管理能力，不是同类替代；
• 若目标是「最省事的单文件管理器」（老服务器、临时用、二次改造起点），Tiny File Manager 星数最高、部署最简单，但 GPL-3.0 协议与单文件架构在工程化（API、测试、扩展）上偏弱；
• FileGator 是「多用户文件管理」的成熟均衡选项，社区热度（3.1k）高于 FileRise，但缺少 WebDAV、分享上传、静态加密与 OnlyOffice 集成；
• FileRise 的差异化在功能宽度：WebDAV + 分享（含上传投递）+ 逐文件夹 ACL + 文件夹级加密 + OnlyOffice + OpenAPI 一站内置，且同样免数据库。适合需要「一个应用覆盖网盘大多数高频能力」的自托管用户；其代价是社区热度尚在成长期（约 1k stars），遇到问题时可依赖的社区资料少于 Tiny File Manager/FileGator；
• 若需要企业级同步客户端、协同生态与应用市场，则应看 Nextcloud/Seafile 等数据库驱动的完整网盘方案（不在本文对比范围）。

八、参考链接

• FileRise 官方网站：https://filerise.net
• FileRise 官方文档（Installation & Setup，Last updated Jan 18, 2026）：https://filerise.net/docs/?page=installation-setup
• FileRise GitHub 仓库（error311/FileRise）：https://github.com/error311/FileRise
• shields.io 版本/星数/协议徽章（本文取证渠道）：https://img.shields.io/github/v/release/error311/FileRise.json
• awesome-selfhosted（File Transfer - Web-based File Managers 分类）：https://awesome-selfhosted.github.io/awesome-selfhosted-html/platforms/php.html
• FileGator 仓库：https://github.com/filegator/filegator
• Directory Lister 仓库：https://github.com/DirectoryLister/DirectoryLister
• Tiny File Manager 仓库：https://github.com/prasathmani/tinyfilemanager
• 站内延伸阅读：《FileRise 3.38 Docker Compose 部署指南》（部署与功能验证）、《FileRise 3.38 配置参数详解》（三层配置体系）、《FileRise 3.38 API 使用详解》（REST API 与 WebDAV 实测）