File Browser · 挂在指定目录上的 Web 文件管理器 · 中文部署与使用全指南

项目仓库： https://github.com/filebrowser/filebrowser

开源协议：Apache License 2.0 · 实现语言：Go · 数据库：BoltDB（单文件 filebrowser.db） · 分发：单二进制 / Docker（Alpine、s6 两种镜像） · 默认容器端口：80 → 宿主 8080 · 仓库已于 2026-09-01 归档（archived），不再发布新版本、不修复安全问题

1 项目简介

File Browser（仓库名 filebrowser/filebrowser）是一个挂在指定目录上的 Web 文件管理界面：把它装在你的服务器上，指向某个目录，你就能用一个清爽的网页界面上传、删除、预览、编辑这些文件。官方定位是 "create-your-own-cloud"——自己搭私有云盘。

重要状态说明（务必先读）：官方 README 顶部明确标注——File Browser 已于 2026 年 9 月 1 日归档（archived），最后一个计划版本已发布，此后不再有新版本、Bug 修复或安全修复。现有 Release 与 Docker 镜像仍在线。如果你继续使用，应按官方建议把它当作"不再维护的软件"对待（详见第 11 节风险说明）。

1.1 核心信息一览

1.2 适用场景

• 想给某个服务器目录套一个网页上传 / 下载 / 预览 / 编辑界面，而不是自己搭一整套网盘。
• 轻量私有云：分享文件、手机传文件、远程改配置。
• 已有目录，临时需要一个 Web 界面做批量文件管理。

1.3 能力边界（官方口径）

• 提供：上传、删除、预览、编辑文件、用户管理、自定义命令（Command Runner，默认关闭）。
• 官方安全说明：命令执行 / runner / hooks 功能存在跨多个安全公告的漏洞，默认关闭；若用 --disable-exec=false 重新开启，应把它等同于宿主机 shell 权限。
• 会话为自包含 JWT，无法服务端吊销：登出、改密、刷新后旧 token 在过期前仍有效。

2 功能特性

• 简易登录系统：多用户、鉴权。
• 文件列表与编辑：网页内预览、在线编辑文件。
• 用户管理：多用户管理界面。
• 自定义命令（Command Runner，默认关闭）：在文件上下文执行自定义命令。
• 高度可定制：外观、行为可通过配置调整。
• 单二进制 / 容器：一条命令起服务。

3 官方界面预览

封面为项目官方横幅。官方文档还提供登录页、文件列表、用户管理、文件编辑器等截图（见仓库 docs/static/）。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Docker（容器方式）或可运行 Go 二进制的 Linux / macOS / Windows。
• 准备好要托管的目录；用 bind mount 时，宿主机目录必须对容器内运行用户（UID 1000）可读可写。

5.2 端口与目录

6 方式一：Docker 部署（官方推荐）

6.1 裸 Alpine 镜像

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

三个 Docker volume 分别存数据、数据库、配置，首次运行自动初始化默认配置与数据库。

6.2 s6-overlay 镜像（LinuxServer 风格，自定义更强）

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

/path/to/config 放 settings.json、/path/to/database 放 filebrowser.db，不存在会自动初始化。

注意：使用 bind mount 时，宿主机目录权限要手动 chown 到容器内用户（UID 1000），Docker 不会自动帮你改权限。

7 方式二：单二进制安装

# macOS（Homebrew）
brew tap filebrowser/tap
brew install filebrowser
filebrowser -r /path/to/your/files

# Linux
curl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash
filebrowser -r /path/to/your/files

# Windows
iwr -useb https://raw.githubusercontent.com/filebrowser/get/master/get.ps1 | iex
filebrowser -r /path/to/your/files

7.1 首次启动（First Boot）

首次启动会自动引导一个 BoltDB 数据库，配置与用户都存在里面；控制台日志会打印监听地址和 admin 用户的随机初始密码。

官方警告：自动生成的 admin 密码只显示一次，忘了就只能删掉数据库重新启动。生产部署建议改用 config init / config set 自定义初始化。

8 配置项说明

• 数据库路径：-d, --database（默认 ./filebrowser.db）。
• --disableExec：默认 true（命令执行功能默认关闭，保持关闭）。
• --disableImageResolutionCalc：关闭读取图片计算分辨率。
• --disablePreviewResize：关闭图片预览缩放。
• 快速初始化：--username（默认 admin）、--password 用于首次引导。
• CLI 子命令：filebrowser config（配置）、filebrowser users（用户）、filebrowser hash（密码哈希）、filebrowser rules（规则）。

9 常用运维命令

# 查看日志（找 admin 初始密码只在首次日志）
docker logs <容器名>

# 进入 CLI 管理用户 / 配置
filebrowser users --help
filebrowser config --help

# 更新镜像
docker pull filebrowser/filebrowser
docker compose up -d   # 或重建容器

10 常见故障排查

• 找不到 admin 密码：首次生成密码只打印一次，找不到就删除数据库 volume 重启重新初始化（会丢用户）。
• 文件目录读写失败：bind mount 路径权限不对，chown 到容器内 UID 1000（或 s6 镜像里的 PUID/PGID）。
• 容器起来但网页打不开：确认 8080:80 映射与防火墙。
• 误开了命令执行功能：保持 --disable-exec 默认 true，不要为图方便开 runner。
• 忘了数据库在哪：BoltDB 是单个 filebrowser.db 文件，随 volume 备份即可。

11 风险与合规说明

• 项目已归档：2026-09-01 后不再发布新版本、不做 Bug 修复与安全修复。
• 官方安全指引（必读）：
  • 已知两类问题不再修复：命令执行 / runner / hooks 漏洞（默认关闭，别开）；会话 JWT 无法吊销（旧 token 到期前一直有效，泄露即视为有效）。
  • 官方建议：不要直接暴露公网，放在终止 TLS 且自带鉴权的反向代理后面；保持命令 runner 关闭；用非特权容器、只把要服务的目录挂进容器。
• Apache-2.0 许可；继续使用即接受"不再维护"的风险，重要生产环境建议评估替代方案。
• 本文命令来自官方 README 与 docs 文档，随版本可能微调，以官方仓库（已归档版本）为准。