如何 3 步部署 File Browser：免下载在线预览 PDF 和文档的完整上手指南

【免费下载链接】filebrowserFile Browser provides a file managing interface within a specified directory and it can be used to upload, delete, preview and edit your files.项目地址: https://gitcode.com/gh_mirrors/fi/filebrowser

还在为看一眼服务器上的 PDF 就得先下载、再找软件打开而犯愁吗？团队共享资料，发链接还不如直接开网页。File Browser 是一个自托管的 Web 文件管理器：把它指向服务器上的任意目录，就能免下载在线预览 PDF、图片、视频与文档，上传、编辑、权限管理全在浏览器里完成。

功能速览

先看全景：这一节用一张表讲清它能干什么，帮你判断值不值得上手。

最快上手路径

跟着走，两三分钟就能在浏览器里看到你的文件目录。

# 安装：macOS 用 Homebrew；Linux/Windows 从 Releases 下载单文件二进制 # 启动：-r 指向要管理的目录，-a / -p 指定监听地址与端口 filebrowser -r /path/to/your/files -a 0.0.0.0 -p 8080

首次启动会自动建一个单文件数据库，并在控制台打印访问地址和 admin 的随机密码（只显示一次）。生产环境更推荐 Docker 部署：Alpine 或 S6 镜像挂载 /srv、/config、/database 三个卷即可，细节见安装文档。

进阶技巧：把体验拉满

三条最常用的进阶配置，直接把预览速度、会话时长和登录体验拉满。

• 磁盘缓存：让图片预览"秒开"。图片缩放结果会写进缓存，重复浏览不再重算，逻辑在http/preview.go 与 diskcache/ 模块。单实例加--cacheDir，多实例用--redisCacheUrl共享：

  filebrowser -r /data --cacheDir /var/cache/filebrowser # 多实例共享缓存：--redisCacheUrl redis://host:port

• 会话时长：大文件上传不掉线。会话默认 2 小时超时，慢网传大文件容易被踢，调大即可：

  filebrowser -r /data --tokenExpirationTime 8h

• 登录对接：接入现有账号体系。不想重复建号，可让反向代理带头部直接登录，省去自建账号维护：

  filebrowser config set --auth.method=proxy --auth.header=X-Forwarded-User

真实场景实战

三种典型用法，每种都给出可直接照抄的操作要点。

团队协作：把项目文件收进一个受控的库

• 每人一个账号，用 scope 把可见目录分开
• 给只读角色关掉 delete/rename，改不了也删不了
• 顶部搜索按名称快速定位，大文件用断点续传传
• 用反向代理加 HTTPS 后，放心对外共享

个人自托管网盘：把服务器目录变成随身网盘

• 指向一个目录，手机、电脑浏览器直接看
• PDF、图片、视频免下载在线预览
• tus 断点续传，传大文件不怕掉线
• 挂上反向代理后，外网访问也稳定

开发运维：网页里改代码、跑命令

• 内置编辑器直接改脚本和配置文件
• 需要时开启 command runner 在页面里跑脚本（默认关闭，注意安全）
• 适合给小团队做一个轻量的变更入口

避坑问答

四个高频坑，答案都是能直接执行的操作，照着点就行。

1. 首次随机密码忘了 / 想换账号怎么办？
   • 快速启动时 admin 随机密码只在控制台打印一次
   • 忘了就删掉 filebrowser.db，再启动重新生成
   • 或进系统后用用户管理改密码
2. 传大文件传到一半掉线？
   • 会话默认 2 小时超时
   • 用--tokenExpirationTime调大到 8h
   • 慢网环境同时确认断点续传已生效
3. 公开部署怕被爆破？
   • 放反向代理后面，终结 TLS 并做二次认证
   • 用 fail2ban 盯/api/login的失败日志
   • 保持 command runner 关闭（默认就关）
4. 项目还维护吗，长期用要注意什么？
   • 已于 2026-09-01 归档，之后不再有安全修复
   • 当作只读工具用，别直接裸奔公网
   • 在容器内、低权限运行，只挂要服务的目录

带走清单

四步收尾，装完不白装。

1. 定目录：确认-r指向哪个根目录
2. 定身份：记好 admin 初始密码，或改成对接现有登录
3. 加防护：挂反向代理 + HTTPS，别裸奔公网
4. 提体验：开磁盘缓存加速图片预览，按需调大会话时长

【免费下载链接】filebrowserFile Browser provides a file managing interface within a specified directory and it can be used to upload, delete, preview and edit your files.项目地址: https://gitcode.com/gh_mirrors/fi/filebrowser