【实用的开源工具】File Browser：给服务器目录套一个网页文件管理器（项目已归档）

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-31，具体版本以官方为准。命令和配置都摘自官方 README、docs 目录、Dockerfile 和命令行文档，本文没有做实机测试，请先在测试环境里走一遍。

先说结论：这个项目已经归档了。 官方 README 顶部写明它在 2026-09-01 归档，不会再有新版本、问题修复和安全修复。能不能用、怎么用，请先读完“项目信息卡”和“踩坑清单”再决定。

项目信息卡

作者在 2026-07-28 写了一篇文章解释为什么停止维护（见文末出处），并明确说如果要继续用，就当作已弃用的软件，风险自担，不要暴露在公网上。他也说没有对比过其他同类软件，所以没有给出具体的替代品推荐，只指了 r/selfhosted 的讨论和 Awesome Self-hosted 清单。

这意味着本文的定位和系列里其他文章不一样：我不推荐你把它直接放到公网上长期使用。它更适合内网、临时使用，或者前面有一层自己的认证。如果你要的是长期稳定的公网网盘，建议另选仍在维护的项目。

它能做什么

• 网页文件管理：上传、删除、预览、编辑文件，在浏览器里完成。
• 多用户：管理员可以创建用户，每个用户有自己的访问范围（scope）和一组权限。
• 分享链接：给某个文件或目录生成分享链接，可设置密码和有效期（见下文，这部分来自源码）。
• 多种登录方式：默认是用户名加密码，也支持由反向代理传入用户名的 proxy 方式、外部脚本的 hook 方式，以及不登录的 noauth 方式。
• 自定义外观：名称、样式、图标都可以改。
• 命令行管理：用户、权限、规则、配置都可以用命令行改。

适合的场景：内网里给家人或同事一个简单的网页文件入口，或者临时分享几个文件。不适合：要求持续获得安全修复的公网服务。

部署

官方文档给的是 docker run 命令，我没有在文档里找到官方的 Compose 文件，下面的 Compose 是按文档里的 docker run 改写的。

官方的 docker run 写法

镜像有两种：基于 Alpine 的“bare”镜像（filebrowser/filebrowser），以及基于 LinuxServer 的 S6 Overlay 镜像（filebrowser/filebrowser:s6）。官方给的 Alpine 版命令：

docker run \
    -v filebrowser_data:/srv \
    -v filebrowser_database:/database \
    -v filebrowser_config:/config \
    -p 8080:80 \
    filebrowser/filebrowser

三个卷分别放数据、数据库和配置，第一次启动时会自动初始化默认配置和数据库。容器内运行程序的用户 UID 和 GID 都是 1000。

S6 版的写法有些不同，用 PUID 和 PGID 环境变量指定用户：

docker run \
    -v /path/to/srv:/srv \
    -v /path/to/database:/database \
    -v /path/to/config:/config \
    -e PUID=$(id -u) \
    -e PGID=$(id -g) \
    -p 8080:80 \
    filebrowser/filebrowser:s6

Compose 版

先建目录。官方文档强调：用绑定挂载（宿主机目录）时，必须自己保证目录对容器内的用户可读写，Docker 不会替你处理。Alpine 镜像里的用户是 UID 1000、GID 1000，所以：

mkdir -p /opt/filebrowser/{srv,database,config} && cd /opt/filebrowser
chown -R 1000:1000 srv database config

/opt/filebrowser/compose.yaml：

services:
  filebrowser:
    image: filebrowser/filebrowser:v2.63.23
    container_name: filebrowser
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./srv:/srv
      - ./database:/database
      - ./config:/config

说明：

• 镜像标签：官方命令里没带标签（即 latest）。我写 v2.63.23，是因为在 Docker Hub 的标签列表里查到了它（还有 v2、latest、s6 等）；用之前请自己再确认一次这个标签存在。项目已经不会再发新版本，所以固定在这个版本不会错过更新。
• 三个目录：./srv 是你要管理的文件，./database 里会生成 filebrowser.db，./config 里会生成 settings.json。镜像默认配置里写的是 port: 80、database: /database/filebrowser.db、root: /srv。
• 端口：容器内是 80，我绑定到宿主机的 127.0.0.1:8080，只让本机的反向代理访问。官方示例是 -p 8080:80，会对所有网卡开放。
• 只挂需要的目录：官方 README 建议“只把打算提供出去的目录挂进容器”。不要把整个 / 或家目录挂进去。

启动并看日志：

docker compose up -d
docker compose logs filebrowser

第一次使用

默认账号和密码：以当前文档为准

这一点在不同版本之间变过，很多旧教程不再适用。当前官方文档（docs/installation.md 的 First Boot 一节）写的是：

• 第一次启动时，File Browser 会自动创建数据库，并随机生成用户 admin 的密码，显示在控制台日志里。
• 这个密码只显示一次。没记住的话，官方给的办法是：手动删除数据库文件，再重新启动，让它重新初始化。
• 官方 CHANGELOG 里，2.32.1 版本（2025-06-16）有一条“generate random admin password on quick setup”。所以如果你看到的教程说有固定的默认账号密码，那是在说更早的版本，请别照用。

所以第一次启动后，立刻执行 docker compose logs filebrowser，在输出里找到类似“User 'admin' initialized with randomly generated password”的那一行，把密码抄下来。日志这行的具体措辞来自源码，不同版本可能不同。

随机密码的长度来自“最小密码长度”设置，默认是 12（config set 文档里 --minimumPasswordLength 默认 12，源码里的默认常量也是 12）。所以以后新建或修改密码，也要至少 12 位。

另外，命令行文档说明：首个用户也可以通过 --username 和 --password 选项（环境变量写法是加 FB_ 前缀，比如 FB_USERNAME）在初始化时指定，其中 --password 要求填的是哈希后的密码，哈希可以用 filebrowser hash <password> 生成（bcrypt）。我没有验证在 Docker 里怎么调用这个命令最合适，需要的话请自己试，或者直接用随机密码。

登录之后：

1. 在界面里把 admin 的密码改成你自己的（改之前想好密码管理的办法）。
2. 在 Settings 里看一下 Global Settings 和 User Management，后面的用户、权限都在这里配。

用户和权限

官方命令行文档里，用户有这些权限开关，创建用户时除 admin 外默认都是开的：

每个用户还有一个范围（scope），默认是 .，即服务根目录。命令行例子（来自 users add 文档的参数，具体怎么在容器里跑我没有验证）：

filebrowser users add <username> <password> --scope <路径> --perm.delete=false

几点要记住：

• 想让一个用户只看到某个子目录，就给他设置对应的范围，而不是用默认的根。
• 管理员可以在界面里创建用户和修改默认值；config set 能设置新用户的默认权限和范围。
• 还有 rules（规则）功能，可以按路径或正则对某个用户或全局设置允许/禁止，命令是 filebrowser rules add <path|expression>，有 --allow 和 --regex 选项。官方文档对规则的匹配顺序没有展开说明，用之前请自己测。
• --lockPassword 可以锁住用户的密码，让用户自己改不了。

开放注册要小心

官方在部署文档里专门有一节：File Browser 可以开启用户自助注册（filebrowser config set --signup 或在 Settings → Global Settings 里开）。自助注册的用户继承“用户默认值”。官方警告：默认范围是服务根目录，自助注册的用户可能读取、修改、删除你提供的所有文件。要么开启 createUserDir，让每人有自己的目录，要么把默认范围改成别的目录。除非你清楚在做什么，否则不要开注册。

分享链接

分享功能在官方文档里没有单独的章节，下面是我看源码和界面文案得到的，可能和你的版本有出入：

• 需要用户有 share 权限（界面说明里要求同时有 download）。
• 创建分享时可以设置密码，也可以设置有效期，单位是秒、分钟、小时或天；不填有效期的话，代码里的过期时间是 0，也就是不过期。设置的密码在库里是 bcrypt 哈希。
• 界面文案里有 Settings 下的分享管理（Share Management）和删除分享的提示，说明可以查看并删除已有的分享；具体谁能管哪些分享，我没有核对。

给别人发链接前，务必想清楚：拿到链接的人能下载你分享的内容；没设密码也没设有效期的话，链接会一直有效，直到你自己删掉它。

反向代理

官方文档没有提供 Nginx 或 Caddy 的配置示例，README 只给了原则：不要让它直接暴露在互联网上，要放在一个终止 TLS 并且自己做认证的反向代理后面。

文档里和代理相关的几点：

• 命令行有 -b, --baseURL 选项，是“base url”，可以用于挂在子路径下；文档没写具体的代理配置，我没有验证。
• 如果你启用了交互式 Shell 功能，官方提醒代理要开启 WebSocket 支持（本文不建议启用该功能）。
• proxy 认证方式：代理传一个带用户名的 HTTP 头，File Browser 会无条件信任它。官方警告：如果代理可以被绕过，攻击者自己加这个头就能拿到管理员权限，所以必须保证 File Browser 只能通过代理访问，并让代理覆盖或删除客户端自带的这个头。

下面是一个通用的 Nginx 示例，不是官方文档里的，仅供参考（端口对应上面绑定的 8080，域名用 example.com）：

server {
    listen 443 ssl;
    server_name files.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # 上传大文件需要放宽请求体限制，按需调整
    client_max_body_size 1g;

    # 在 File Browser 前面再加一层认证，这是官方 README 的建议；
    # 这里用 Nginx 自带的 Basic 认证，htpasswd 文件需要自己生成
    auth_basic           "restricted";
    auth_basic_user_file /etc/nginx/filebrowser.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

补充两点我的推断，请自己验证：

• config set 文档里上传分片的默认大小是 10485760 字节（约 10 MiB，--tus.chunkSize），超过 Nginx 默认的 1m 请求体限制，所以反向代理后上传失败时，先查有没有 413 错误。
• 如果你在代理上给整个站点加了 Basic 认证，分享链接的访问者也会被要求认证，这样“分享给外人”就做不到了。要给外人用分享链接，就得把分享相关的路径从认证里排除，但哪些路径需要排除，官方没有说明，我没有核对。

备份

File Browser 的用户、权限、分享、设置都存在一个数据库文件里。命令行文档说明它用的是 Bolt DB，是单文件数据库，不需要另外装数据库服务。在上面的部署里，这个文件是 ./database/filebrowser.db；配置文件是 ./config/settings.json；真正的文件在 ./srv。

备份建议（通用做法，不是官方步骤）：

cd /opt/filebrowser
docker compose stop filebrowser          # 先停掉，避免复制到写到一半的文件
cp -a database database.bak-$(date +%F)
cp -a config   config.bak-$(date +%F)
docker compose start filebrowser

• ./srv 里是你的文件本身，按你平时备份文件的办法单独处理。
• 命令行文档里还有 filebrowser config export <path>，可以把配置导出为 JSON 或 YAML 文件，再用 config import 导入。它导出的是配置，是否包含全部用户和分享，文档没有写，我没有验证，所以不能当作完整备份。
• 忘记了 admin 密码、又没有别的管理员时，官方给的办法是删除数据库重新初始化，这会清空所有用户和分享。所以删之前一定先备份。

更新与卸载

项目已归档，所以没有更新可升。v2.63.23 就是最后的版本。官方说已发布的版本和 Docker 镜像会继续保留在线上。

卸载：

cd /opt/filebrowser
docker compose down

这只会删除容器。srv 是你的文件，database 和 config 是用户和设置，确认不再需要时才手动删除。

踩坑清单

1. 项目已归档，不会再有任何修复。 官方 README 和 SECURITY.md 写得很清楚：不会再有发布、问题修复和安全修复；SECURITY.md 的支持版本表里，2.x 和更早的版本都标记为不支持。之后发现的漏洞不会有补丁，请把它当作已弃用的软件看待。
2. 不要直接暴露到公网。 官方建议：放在会终止 TLS 并自己做认证的反向代理后面。更稳妥的是只放内网，或者通过 VPN 访问。
3. 命令执行/钩子功能不要打开。 README 说这个功能有大量漏洞、需要整体重写才能变安全，也不会修复。它默认是关闭的（--disableExec 默认 true），若用 --disable-exec=false 或 FB_DISABLE_EXEC=false 重新启用，官方的说法是：这等同于给了对方宿主机上的 shell 权限。保持关闭。
4. 登录会话无法撤销。 README 说会话是自包含的 JWT，不是服务端会话，退出登录、改密码、续期都不会让已发出的令牌失效，要等它过期。官方的建议是：假定泄露的令牌在过期前一直有效。默认过期时间是 2 小时（tokenExpirationTime，也可以用环境变量 FB_TOKEN_EXPIRATION_TIME 改）。
5. 首次启动的随机密码只显示一次。 一定要在第一次启动后马上查日志并记下来。丢了只能按官方说法删除数据库重来，用户和分享也会一起清空。
6. 绑定挂载的目录权限要自己处理。 Alpine 镜像里的程序用 UID/GID 1000 运行，宿主机目录要能被这个用户读写，否则启动或上传会失败。官方文档明确提醒了这一点。
7. 开放注册默认会暴露全部文件。 自助注册的用户默认范围是服务根目录，官方警告可以读写删除所有被提供的文件。要么别开，要么先设好 createUserDir 或默认范围。
8. noauth 模式只给私人环境。 官方说明：使用不认证方式时，id 为 1 的用户会作为默认用户，新增用户不会有任何作用。别在能被别人访问的地方用它。
9. proxy 认证方式信任请求头。 官方警告：代理被绕过就等于白送管理员权限，所以 File Browser 的端口必须只能被代理访问，这也是示例里绑定到 127.0.0.1 的原因之一。
10. 没有自带的防暴力破解。 官方文档说得很直接，不原生支持，建议配合 fail2ban，并提供了过滤器示例，匹配日志里的 /api/login: 403 这类行。用 Docker 时要处理日志怎么给到 fail2ban，官方没有展开。
11. 跟随符号链接要谨慎。 命令行文档里有 --followExternalSymlinks，描述是“跟随目标在用户范围之外的符号链接（不安全）”。不用的话保持默认，不要打开。
12. Docker 发布的端口会绕过 ufw 之类的防火墙。 这是 Docker 的通用行为，不是这个项目特有的，所以示例绑定到 127.0.0.1，不要照搬官方示例的 -p 8080:80，除非你就想让所有网卡都能访问。
13. 它不是备份工具。 通用提醒：在网页上误删的文件，和在服务器上直接删除一样回不来，重要数据请另做备份。

出处

• File Browser 官方仓库 README（归档公告、已知未修复问题、加固建议、许可证）
• 官方文档：安装（Docker 镜像、首次启动）
• 官方文档：认证方式
• 官方文档：部署（自助注册、fail2ban）
• 官方文档：命令执行
• 官方文档：故障排查（会话超时）
• 命令行文档：filebrowser、config set、users add、rules add
• 官方 Dockerfile 与 镜像默认配置 settings.json
• 官方 SECURITY.md
• 官方 CHANGELOG
• 最新发布 v2.63.23
• Docker Hub：filebrowser/filebrowser（标签列表）
• 作者说明停止维护的文章：Goodbye File Browser, for Real This Time
• 分享功能的细节来自仓库源码（http/share.go、share/share.go）和界面文案文件（frontend/src/i18n/en.json），不是官方文档，请以你实际用的版本为准。