File Browser：为服务器目录提供 Web 文件管理

家用服务器、开发机或 NAS 上已经有一批文件，但并非每个使用者都适合拿到 SSH 账号。File Browser 可以把指定目录变成一个浏览器中的文件管理界面：登录后上传、下载、预览、编辑、重命名或分享文件，管理员还能把不同用户限制在各自的目录范围内。

选择 File Browser 前必须先接受项目现状：仓库在 2026-09-01 归档，v2.63.23 是最后一个计划发布的版本，今后不会再有错误或安全修复。官方还公开了两类不会修复的问题，分别涉及命令执行功能和无法主动撤销的 JWT 会话。下面的部署因此只面向受控内网或带额外身份认证的 HTTPS 代理，不把 File Browser 直接暴露到互联网。

GitHub 仓库信息

信息	内容
项目标题	File Browser
项目描述	为指定目录提供文件管理界面，可在浏览器中上传、删除、预览和编辑文件。
GitHub 仓库	filebrowser/filebrowser
官网地址	未知（已检索但未找到仍由归档项目维护的可靠官网）
主要开发语言	Go 50.43%、Vue 30.23%、TypeScript 11.43%
开源许可证	Apache-2.0
最近代码更新	2026-07-31（GitHub pushed_at，核对日期：2026-09-17）

浏览器里的受控文件目录

File Browser 的核心很直接：把容器内 /srv 指向需要管理的目录，Web 界面中的文件操作就落到这个范围内。File Browser 不会把原文件导入专有对象格式，因此已有目录可以直接使用，停止服务后文件也仍是普通文件。

这种直接性带来三个实用能力：

• 网页文件操作：适合偶尔需要上传素材、编辑小型文本或从移动设备取文件的场景，使用者不必接触 SSH、SFTP 客户端和宿主机路径。
• 用户 scope 与权限：管理员可以把用户限制到某个子目录，并分别控制创建、修改、删除、下载和分享。scope 是应用层边界，容器仍应只挂载 File Browser 真正需要看到的宿主机目录。
• 单个可执行服务：程序可以作为二进制运行，也有官方 Docker 镜像；数据库保存用户和设置，配置文件保存监听地址、根目录和数据库位置。三类数据可以分开备份。

File Browser 不是同步盘。File Browser 提供服务器目录的远程界面，但没有桌面同步客户端、冲突合并和协同编辑工作流。需要完整团队云盘时，应比较 Nextcloud；只需要协议级远程文件访问时，SFTP 或 WebDAV 可能更简单。

归档后的采用判断

官方最终 README 建议继续运行者做到三件事：不要直接暴露公网、保持命令执行关闭、在容器中以非特权用户运行且只挂载目标目录。这些要求来自已知风险，而非一般性的“最佳实践”。

命令 runner、hooks 和交互式 shell 曾多次出现漏洞，从 v2.33.8 起默认关闭。不要设置 FB_DISABLE_EXEC=false。如果重新启用，应把 File Browser 用户执行命令的能力视为获得容器内 shell，并进一步评估挂载目录和宿主机逃逸风险。

会话使用自包含 JWT。退出登录、修改密码或续期不能让已签发 token 立即失效，刷新 token 还可能被重复兑换。泄露的 token 在过期前都应视为有效。反向代理的额外身份认证、较短的会话时间和不直接开放源站，可以缩小风险，但无法修复应用本身的会话模型。

新生产系统、互联网文件服务或有持续合规要求的环境，应该优先选择仍在维护的替代品。File Browser 更适合已有存量环境、隔离网络内的轻量目录管理，或短期迁移过渡。

Docker Compose 部署

下面固定最终版本 filebrowser/filebrowser:v2.63.23，使用官方 bare Alpine 镜像约定的三个持久化路径：/srv、/database 和 /config。镜像内默认用户是 UID/GID 1000；命名卷可以避开宿主机绑定目录的初始权限问题。

前置条件与平台检查

主机需要可用的 Docker Engine 与 docker compose 插件，并为被管理文件、数据库、配置和备份预留足够磁盘空间。官方没有给出可信的 CPU 或内存最低值，应按实际目录规模、并发用户和预览任务在隔离环境压测，不用未经来源核对的数字代替容量规划。

本次研究没有成功核验 Docker Hub manifest，尤其不能默认所有 ARM NAS 都有匹配镜像。部署前在服务器上检查本机架构和镜像平台：

docker info --format '{{.OSType}}/{{.Architecture}}'
docker buildx imagetools inspect filebrowser/filebrowser:v2.63.23
docker compose version

镜像清单应包含服务器对应的 OS/CPU 平台，Compose 应正常输出版本。若本机没有 buildx，可用 docker manifest inspect filebrowser/filebrowser:v2.63.23 检查清单；tag 不存在、registry 不可达或没有匹配平台时应停止，不要用未知来源的镜像替代。

创建配置

在计划长期保留的目录中创建 compose.yaml：

mkdir filebrowser
cd filebrowser

services:
  filebrowser:
    image: filebrowser/filebrowser:v2.63.23
    restart: unless-stopped
    environment:
      FB_DISABLE_EXEC: "true"
      FB_TOKEN_EXPIRATION_TIME: "2h"
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - filebrowser-data:/srv
      - filebrowser-database:/database
      - filebrowser-config:/config

volumes:
  filebrowser-data:
  filebrowser-database:
  filebrowser-config:

127.0.0.1 限制只有宿主机本地和同机反向代理可以连接。若只在受控局域网使用，可改成宿主机的内网地址并配置防火墙；不要改成所有网卡监听后直接开放公网。

需要管理宿主机已有目录时，把数据卷替换为绑定挂载：

    volumes:
      - /srv/shared-files:/srv
      - filebrowser-database:/database
      - filebrowser-config:/config

/srv/shared-files 必须替换成真实目录，并确保 UID 1000 对所需文件具有恰当权限。只读浏览场景可以写成 /srv/shared-files:/srv:ro；此时上传、编辑、删除和重命名都会失败，这是预期的权限结果。

启动和取得初始密码

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs filebrowser
curl --fail --output /dev/null http://127.0.0.1:8080/

配置解析应以零状态退出，docker compose ps 应显示 filebrowser 为运行状态，HTTP 检查也应成功。首次启动会自动创建配置与数据库，并在日志中只显示一次 admin 用户的随机密码；日志中应能找到初始化后的监听信息和该随机密码，不能持续出现数据库或权限错误。立即把密码存入密码管理器，登录后更换为独立强密码；不要把包含初始密码的日志转发到工单、聊天或公共 CI。

如果 Docker 就运行在当前电脑，直接打开 http://127.0.0.1:8080。如果服务运行在远程服务器或 NAS，127.0.0.1 指向服务器自身，需要选择下面一种受控入口：

• 在客户端电脑执行 ssh -N -L 8080:127.0.0.1:8080 user@server，保持会话后打开 http://127.0.0.1:8080；成功信号是客户端 HTTP 请求返回登录页，而服务器 8080 仍不对局域网开放。
• 先在服务器配置带额外身份认证的 HTTPS 反向代理，再使用外部 https:// 域名；成功信号是域名证书有效、认证生效，并且从其他主机无法绕过代理直连 8080。

如果错过初始密码，官方文档给出的快速办法是删除数据库后重新初始化，但这会同时删除已有用户和应用配置。已有环境应优先从备份恢复数据库，而不是随意重置。

完成一次有意义的验收

登录后执行：

1. 在根目录创建 demo 文件夹；
2. 上传一个测试文本文件；
3. 在浏览器中预览并编辑内容；
4. 下载文件，确认修改已保存；
5. 新建一个非管理员用户，把 scope 限制为 /demo；
6. 使用该用户登录，确认看不到 scope 之外的目录。

这条路径验证了文件读写、数据库用户记录和权限范围。只验证登录页无法发现 /srv 不可写或用户 scope 配错的问题。

重建容器后再验证数据：

docker compose down
docker compose up -d

demo 文件、用户和设置都应保留。使用三命名卷配置时，docker compose down -v 会删除文件、数据库和配置卷，不能作为普通停止命令使用。若 /srv 已改为宿主机绑定挂载，down -v 不会删除该宿主机目录中的文件，但仍会删除 Compose 管理的数据库和配置卷，服务依然无法完整恢复。

文件操作背后的边界

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    User[浏览器用户] -->|HTTPS 与额外认证| Proxy[反向代理]
    Proxy -->|本机 :8080| Web[File Browser]
    Web --> Auth[用户、JWT 与 scope 检查]
    Auth --> Files[(srv 文件目录)]
    Web --> DB[(database 用户与设置)]
    Web --> Config[(config/settings.json)]

用户在界面中看到的根目录由 scope 决定，真正能被程序访问的最大范围则由 /srv 挂载决定。应用管理员权限不应该等于宿主机文件系统权限。即使 File Browser 管理员能看到应用根目录，只要容器只挂载了受控目录，其他宿主机路径仍不应进入 File Browser 的信任边界。

用户、注册与认证

默认 JSON 认证由 File Browser 自己校验用户名和密码。创建用户时先设 scope，再按职责授予下载、创建、修改、删除或分享权限。管理员权限会放大到全部操作，不应作为普通账号模板。

File Browser 支持自助注册，但默认用户 scope 是服务根目录。若开启注册，必须先启用每用户目录，或把默认 scope 改到受限目录；否则新注册用户可能读写 File Browser 提供的全部文件。

代理头认证会直接信任代理写入的用户名头。只有源站完全不能被绕过，且代理会删除客户端伪造头再写入可信值时才能采用。归档项目的会话缺陷仍然存在，外层认证不能使已泄露的内部 JWT 立即失效。

官方排障文档说明默认会话为 2 小时。大文件上传确实可能需要更长时间，但延长 FB_TOKEN_EXPIRATION_TIME 也会延长泄露 token 的有效期；应优先改善网络或改用适合大文件的传输路径，并保持尽可能短的会话。

反向代理与安全基线

继续运行 File Browser 时，HTTPS 代理应同时承担外部身份认证，并确保客户端不能直连 8080 源站。配置完成后至少检查：

• 外部 URL 使用有效 TLS，HTTP 自动跳转到 HTTPS；
• 8080 仍只绑定回环地址，防火墙没有额外放行；
• 命令执行环境变量保持 true，界面中没有 shell 或 hook 能力；
• 容器没有特权模式、Docker Socket 或多余宿主机挂载；
• 管理员和普通用户的 scope、删除与分享权限已经逐个验收；
• 代理具备登录限速或额外 MFA，因为应用本身没有原生暴力破解防护。

通用代理配置见 Docker 服务反向代理与 HTTPS，容器权限与供应链基线见 Docker Compose 生产安全加固。这些措施降低暴露面，但不会让归档软件重新获得安全维护。

备份与恢复

完整恢复需要三部分：

数据	容器路径	恢复后验收
被管理文件	/srv	文件列表、下载内容和写权限
用户与应用设置	/database/filebrowser.db	管理员与受限用户登录、scope 和权限
运行配置	/config/settings.json	端口、根目录、数据库路径和日志设置

备份前停止 File Browser，避免数据库和正在修改的文件处于不同时间点。三个命名卷或绑定目录应作为同一恢复批次保存；恢复后不能只看首页，还要分别测试管理员登录、受限用户 scope、文件下载和一次可回滚的写操作。通用命名卷与绑定目录方法见 Docker 备份与恢复数据。

如果 /srv 指向 NAS 或外部文件系统，File Browser 数据库备份不会包含原文件；NAS 快照和数据库备份需要记录相同恢复时间点。反过来，只有文件快照也会丢失用户、scope 和设置。

最终版本的更新策略

v2.63.23 之后没有官方升级路线。继续运行时应固定 tag，记录镜像 digest，并监控项目安全公告和依赖漏洞；发现新漏洞时，现实选择通常是隔离、禁用受影响功能、迁移到维护中的替代品，或承担自行维护分支的成本。

修改 Compose 中的环境变量、端口或挂载后，需要执行 docker compose up -d 重新创建受影响容器，再重复 HTTP、登录和文件权限验收。docker compose stop 或 down 会停止服务但默认保留命名卷；只有显式 down -v 才删除 Compose 管理的卷。

从旧版本升级到最终版之前，先备份三个恢复单元并阅读跨版本 Release notes。升级后重复用户 scope、文件读写、分享和代理认证验收。失败回滚需要同时恢复旧镜像和升级前数据库；只把 tag 改回去不能保证数据库兼容。

docker compose pull
docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 filebrowser

Compose 的通用升级与回退流程见 Docker Compose 服务生命周期。

常见问题

症状	定位	修复与再验证
初始密码找不到	检查首次启动日志是否已被轮转	从备份恢复数据库；全新空实例才考虑删除数据库重新初始化
上传或编辑返回权限错误	检查 /srv 挂载模式和 UID/GID 1000 的权限	调整最小必要权限，再完成上传、编辑和下载验收
普通用户看到了不应访问的目录	检查用户 scope 和默认用户配置	收紧 scope，并立即阻断源站或停服，直到旧 token 的现有有效期结束；退出或改密码不能撤销已签发 token
代理认证可被绕过	从非代理网络测试源站 8080 是否可达	保持回环绑定、清洗认证头、阻断直连后重新测试
大文件上传中途登录失效	核对 2 小时会话和网络耗时	在风险可接受范围内调整会话，并验证旧 token 的过期边界
界面出现 shell 或命令 hooks	检查 FB_DISABLE_EXEC 与全局设置	立即关闭执行功能、重建容器，并审计挂载目录中的异常改动

版本与验证说明

这份指南以最终 Release v2.63.23 和 2026-09-17 的归档仓库快照为依据。镜像路径、端口、三个持久化目录、首次密码、UID/GID、认证和安全限制均来自官方 README 与固定提交文档。

本次没有拉取镜像、启动容器、验证 Docker Hub manifest 或演练恢复。部署验证等级为官方资料核对；目标环境仍需执行文中的登录、文件读写、scope、重建和代理隔离验收。

参考资料

• File Browser README 与归档安全说明
• File Browser 安装文档
• File Browser 认证文档
• File Browser 命令执行安全说明
• File Browser v2.63.23 Release
• File Browser 安全公告
• Apache-2.0 许可证