文件明明都在服务器上,为什么还要再装一个网盘?
先问一个很实际的问题:你的文件早就躺在某台服务器的硬盘里,或者在对象存储的桶里,甚至散落在好几台机器上——它们并不缺一个「存放的地方」。真正缺的,是一个能随时随地用浏览器打开、上传下载、在线预览、还能顺手分享的入口。为了这个入口,难道要把几个 TB 的文件再搬进一个新网盘系统里,重新上传、重新整理、重新做一遍备份?
Filestash 的回答是:不用搬。它的定位和本系列前面几篇都不一样——Cloudreve 是把文件存进自己的数据库和目录体系,Alist 是把各家网盘的接口聚合起来,而 Filestash 干脆自己一个字节都不存,只做一件事:给已经存在的存储,套上一个统一、好看、功能完整的网页门面。存储还是原来的存储,权限还是原来的权限,你只是多了一个随时能打开的网页入口。
项目地址:https://github.com/mickael-kerjean/filestash
这个项目从 2017 年维护至今,GitHub 上约 14.9k 星,采用 AGPL-3.0 协议。它的官方称呼是「通用文件管理平台」(Universal File Management Platform),下面就沿着这条主线展开:先讲清它和传统网盘的本质区别,再用 Docker 把它跑起来,接上一个 S3 和一个 SFTP 后端,最后聊聊它真正拉开差距的插件与网关能力。
先搞清楚:它是个「门面」,不是仓库
理解 Filestash 的关键,是分清两个概念:存储后端和访问界面。传统网盘把两件事捆在一起——文件必须先进它的系统,才能通过它的界面访问。Filestash 把这两件事彻底拆开:文件留在原地,它只负责「翻译」——把各种存储协议翻译成一套统一的网页操作。
它能对接的后端几乎覆盖了所有常见协议:
| 后端类型 | 典型场景 |
|---|---|
| SFTP / FTP | 任何一台开了 SSH 的 Linux 服务器、老式 FTP 空间 |
| S3 及兼容存储 | AWS S3、MinIO、Cloudflare R2、阿里云 OSS 等 |
| SMB / NFS | 局域网里的 NAS、Windows 共享目录 |
| WebDAV | 已有的 WebDAV 服务,比如 Nextcloud、Davflare |
| Git | 把代码仓库当文件库浏览 |
| IPFS | 分布式存储网络 |
| 本地目录 | Filestash 所在机器自己的文件夹 |
这意味着一种非常实用的组合:公司文件在 SMB 共享上,备份在 S3 桶里,个人文件在家里的服务器上——以前要开三个客户端、记三套地址,现在全部挂到同一个 Filestash 里,一个页面全部搞定。和 OpenList 这类聚合工具相比,Filestash 聚合的不是「网盘服务」,而是「存储协议」,所以它的覆盖面落在了更底层的位置。
和 Cloudreve、Alist 到底差在哪
| 维度 | Cloudreve | Alist / OpenList | Filestash |
|---|---|---|---|
| 文件存在哪 | 自己的目录/对象存储,由它管理 | 各家网盘里,它只做聚合 | 原有存储里,它完全不碰 |
| 核心动作 | 建仓库、存文件 | 挂载网盘账号 | 给存储套界面 |
| 用户体系 | 自带完整用户与权限 | 自带用户与访客控制 | 依赖后端账号或插件做认证 |
| 典型用户 | 想要一个自己的网盘 | 网盘账号太多想统一入口 | 存储早已就位,只缺好用的访问层 |
| 迁移成本 | 要把文件搬进去 | 授权账号即可 | 填后端地址即可,零搬运 |
一句话记住它:别的网盘是先建仓库再请你搬家,Filestash 是站在你家门口,给你换了一扇带可视门铃的新门。
部署:一条 Docker 命令先跑起来
Filestash 官方提供 Docker 镜像 machines/filestash,默认端口 8334。用 Docker Compose 部署如下:
services: filestash: image: machines/filestash container_name: filestash restart: unless-stopped ports: - "8334:8334" volumes: - ./data:/app/data/state environment: - APPLICATION_URL=https://files.example.comdocker compose up -ddocker compose logs -f filestash启动后浏览器打开 http://服务器IP:8334,就能看到登录界面。第一次使用时先访问管理后台设置管理员密码:
https://files.example.com/admin在后台里可以完成绝大多数配置:添加存储连接、设置认证方式、开关功能模块、调整界面主题等。配置会持久化到挂载出来的 data 目录里,所以上面 Compose 里的卷挂载别省——省掉的话容器一重建,所有连接配置都得重填。具体的卷路径与环境变量以官方文档(filestash.app 的安装指南)为准,不同版本可能略有差异。
如果打算长期用,建议再在前面套一层反向代理和 HTTPS,形态和给其他自建服务做入口没有区别:
server { listen 443 ssl; server_name files.example.com;
location / { proxy_pass http://127.0.0.1:8334; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; client_max_body_size 0; }}注意 client_max_body_size 0 这一行:文件管理服务经常要传大文件,反向代理默认的上传大小限制是最常见的「传一半失败」元凶,索性放开,把限制交给后端存储本身去管。
接第一个后端:S3 对象存储
假设你有一个 S3 兼容的桶(AWS S3、MinIO、R2 都算),想在网页里直接管理它。在 Filestash 管理后台的 Connections(连接)里新建一个连接,类型选 S3,核心参数就这几项:
| 参数 | 说明 |
|---|---|
| Endpoint | S3 服务地址,AWS 官方可留空或填区域地址,MinIO/R2 填自己的地址 |
| Region | 桶所在区域,如 ap-east-1;自建 MinIO 随便填一个即可 |
| Access Key / Secret Key | 访问密钥对,建议为 Filestash 单独建一个子账号密钥 |
| Bucket | 要挂载的桶名 |
| Path | 可选,限定只暴露桶内某个前缀目录 |
对应的连接配置结构大致长这样(后台界面里填的是同一批字段,写出来是为了让你有个整体概念,字段细节以官方文档为准):
{ "type": "s3", "label": "备份桶", "params": { "endpoint": "https://minio.example.com", "region": "us-east-1", "access_key_id": "filestash-ro", "secret_access_key": "********", "bucket": "archive", "path": "/shared" }}保存后回到首页,这个桶就会作为一个入口出现,点进去就能浏览、上传、下载、预览——而桶里的对象本身一动没动,原来用其他工具访问这个桶的方式也不受任何影响。
给 Filestash 用的 S3 密钥务必走最小权限:只给目标桶的读写权限,不要图省事直接填主账号的根密钥。门面再安全,也没必要把整栋楼的钥匙挂在门上。
接第二个后端:SFTP 指向家里那台服务器
再把一台开了 SSH 的 Linux 机器接进来。新建连接,类型选 SFTP:
{ "type": "sftp", "label": "家里的服务器", "params": { "host": "192.168.1.10", "port": "22", "username": "files", "password": "********", "path": "/srv/files" }}几个实操建议:
- 在被连接的服务器上单独建一个低权限账号(如上面的
files),只让它访问要共享的目录,别用 root 或自己的日常账号直连。 path参数把可见范围锁死在一个目录里,Filestash 里看到的就是这个目录的视图,跳不出去。- 条件允许时优先用密钥登录代替密码登录,并在服务器侧关掉该账号的密码登录。
接完这两个后端,你的 Filestash 首页上会并排出现「备份桶」和「家里的服务器」两个入口。在网页里把文件从 SFTP 拖到 S3,或者反过来——跨存储搬运就在浏览器里完成了,而这正是「门面」模式最顺手的时刻:存储各归其位,操作只有一个界面。
进阶一:Gateways——把文件再以别的协议递出去
Filestash 不只是个「读」的界面。它有一组叫 Gateways 的能力:挂进来的存储,可以再以 SFTP、S3、FTP、WebDAV、MCP 等协议反向暴露出去。
这个能力解决的是协议不匹配的尴尬。举例:你的备份软件只认 S3 接口,但文件实际躺在一台只有 SMB 共享的老 NAS 上。以前只能换软件或者加一层转换服务,现在让 Filestash 把 SMB 接进来、再以 S3 网关递出去,备份软件无感对接。再比如某个只支持 WebDAV 的移动端 App,可以直接连 Filestash 的 WebDAV 网关,访问它背后的 SFTP 服务器——协议转换这件脏活,门面顺手就干了。
WARNING网关是把双刃剑:每多开一个对外协议,就多一个需要做认证和审计的入口。只开启真正用到的网关协议,并为每个网关单独设置访问凭据;不要为了「以后可能用」把 SFTP、FTP、WebDAV 一股脑全打开暴露在公网上。
进阶二:插件驱动——它真正的护城河
Filestash 的架构理念是「除宇宙基本真理之外,一切皆插件」:存储后端是插件,认证方式是插件,授权规则是插件,连搜索、缩略图生成都是插件。除了传统的 Go 插件,它还支持运行时插件——一个 zip 包丢进插件目录即可生效,其中可以包含在沙箱里运行的 WebAssembly 代码,权限被严格收紧,不给声明之外的网络访问。
对普通使用者来说,插件体系最直接的收益是这些「大网盘才有」的功能它都能补齐:
- 工作流引擎:文件事件触发动作链。比如「某目录新增文件 → 自动发邮件通知」「上传完成 → 触发后续处理流水线」,这类自动化不用再自己写脚本盯目录。
- 认证与授权:可以对接现有的账号体系做登录,用基于角色的权限控制(RBAC)决定谁能看哪个后端、哪个目录。
- 版本、审计、配额、杀毒:文件版本管理、操作审计日志、按用户限额、上传自动杀毒扫描,都以插件形式提供,需要哪个开哪个。
- AI 能力:AI 搜索、智能文件夹、图片 OCR 识别,也在插件生态里。
这套设计的代价是:很多高级功能不是开箱全亮,而是要你去插件列表里按需启用。第一次用可能会觉得「怎么这个功能还要装插件」,但用久了会明白,核心保持轻量、能力按需生长,正是它能从 2017 年活到今天还没臃肿死的原因。
进阶三:文件应用——不止是传文件,还能看文件
普通网盘的预览能力一般停留在图片、视频、PDF 和 Office 文档。Filestash 的文件应用(File Apps)覆盖面要夸张得多,光是官方列出的就包括:相机 RAW 全家桶(NEF、CR2、ARW、RAF 等)、天文图像(FITS、XISF)、GIS 数据(GeoJSON、SHP、GPX)、数据工程格式(Parquet、Arrow、HDF5、NetCDF)、3D 模型(FBX、OBJ、STL、STEP)、Adobe 系列(PSD、AI、XD)、医学影像(DICOM)……再加上按需视频转码、Chromecast 投屏这类播放能力。
这意味着对特定职业用户,Filestash 的价值会陡增:摄影师把 NAS 里的 RAW 原片挂进来,出门在外用浏览器就能挑片;做数据的把结果文件丢进 S3,网页上直接预览 Parquet 而不用每次下载到本地开工具。如果你的工作流里有大量「格式特殊、在线看一眼就够了」的文件,这一节就是选它的核心理由。
排障小节
容器起来了,但 8334 端口打不开。 先看 docker compose logs filestash 有没有报错,再确认防火墙和云服务器安全组放行了 8334(或反向代理所在的 443)。本地 curl http://127.0.0.1:8334 能通、外部不通,基本就是安全组问题。
配置重启后全没了。 十有八九是数据卷没挂对。确认 Compose 里的 data 卷确实映射到了 Filestash 的状态目录(以官方文档为准),并且宿主机目录可写。
S3 连接报错,连不上或列表为空。 按顺序查:Endpoint 写对没有(MinIO 和 R2 必须填自己的地址,不能套 AWS 的)、Region 是否匹配、密钥子账号有没有目标桶的 ListBucket 和对象读写权限、路径前缀 path 是否写了一个不存在的目录。先用同一组密钥在命令行 aws s3 ls 验证一遍,能省很多时间。
SFTP 连接超时或认证失败。 先在 Filestash 所在机器上手动 ssh 用户名@主机 试一次:网络不通、端口不对、服务器禁用了密码登录,都会先在这里暴露。若服务器只允许密钥登录,就改用密钥方式配置连接,别硬试密码。
上传大文件到一半失败。 链条上每一层都可能有限制:反向代理的 client_max_body_size、Filestash 自身的上传设置、后端存储的单文件上限。逐层放开并复现一次小文件→大文件,就能定位是哪一层在拦。
网页能打开但预览是空白或乱码。 多数是 APPLICATION_URL 与实际访问地址不一致,或者反向代理没透传 X-Forwarded-Proto,导致页面生成的资源链接协议错误(HTTPS 页面里混入 HTTP 资源会被浏览器拦截)。把这两个对齐后强制刷新再看。
小结
Filestash 在本系列里是个异类:Cloudreve 是仓库,Alist 是聚合器,Davflare 是把仓库建在云上,而 Filestash 是纯粹的门面——文件在哪它就在哪开窗。如果你的存储早已成型(SFTP 服务器在跑、S3 桶在用、NAS 共享开着),缺的只是一个统一、能预览、能分享、还能跨协议递送的网页入口,那 Filestash 就是成本最低的那个答案:零迁移、零搬运,一个 Docker 容器,今晚就能上线。