Docker 部署 Filestash：轻松搭建浏览器文件管理平台

本文基于 machines/filestash:latest。上游没有带版本号的标签，本文使用 latest。

Filestash 是什么

Filestash 是一套在浏览器里使用的开源文件管理器。它不去替代你原来的磁盘或对象存储，而是连上已经存在的 SFTP、FTP、WebDAV、S3、Git 等入口，在网页里浏览和上传。

和 FileZilla、WinSCP 这类桌面客户端相比，Filestash 不要求每人再装一个软件。多种存储出现在同一个登录页上，点开一种协议，填上连接信息就能进目录。

Filestash 能做什么

• 连接远程存储：登录页可以选择 WebDav、FTP、SFTP、GIT、S3。
• 浏览目录：连上之后可以打开文件夹，也能新建文件和目录。
• 上传文件：文件列表页右下角有上传按钮。
• 设置管理员：第一次打开时设置管理员密码，以后用这个密码进后台。
• 在后台查看存储驱动：管理员可以打开后台，查看当前镜像里已经带上的存储后端。

为什么要使用 Filestash

服务器文件走 SFTP 客户端，网盘再换一个网页，对象存储又是另一套控制台。人一多、机器一多，光切换工具就要花时间。

Filestash 把这些入口收进一个浏览器页面。文件仍留在原来的服务器、WebDAV 或对象存储上。适合要同时查看几类已有存储的运维和开发，也适合给同事一个不用安装客户端的查看入口。

使用 Docker 部署 Filestash

Filestash 可以用 Docker 跑起来，宿主机不必安装它的运行环境。开始之前准备好 Docker，并想好浏览器要打开的地址。管理员密码会写进数据目录，这个目录需要留下来。

下面用 Docker Compose 启动服务，在浏览器里设置密码，再连上一台 SFTP 服务器。

环境要求

本文命令使用 machines/filestash:latest。上游没有 1.2.3 这种版本标签，原因见「标签怎么选」。

登录页会提交存储账号和密码。只在本机打开时可以用 http://127.0.0.1:8334。给别人用、或放到公网时，在前面加 HTTPS，见「使用域名访问」。

bash
docker --version
docker compose version

Linux 未装 Docker 可使用轩辕镜像一键安装脚本：

bash
bash <(wget -qO- https://get.xuanyuan.cloud/docker.sh)

备用地址：

bash
bash <(wget -qO- https://get.xuanyuan.me/docker.sh)

更多见 轩辕镜像使用手册。

Windows 和 Mac 从 Docker Desktop 安装，安装后启动 Docker Desktop。下文的 cat > compose.yaml <<'EOF' 是 bash 写法。PowerShell 不能直接粘贴这一段，请改用 Git Bash、WSL，或在 Linux 上执行。

标签怎么选

GitHub 仓库 mickael-kerjean/filestash 没有 Release。Docker Hub 上当前这份镜像的标签是 latest，2026-10-09 有更新。轩辕镜像标签页上，latest 同时提供 linux/amd64 与 linux/arm64。

仓库里还能看到 lowa、trial、latest-amd64、latest-arm64v8，以及一串提交哈希。这些都不是 x.y.z 版本号。提交哈希停在更早的构建上，不是 2026-10-09 这份 latest。下面的命令使用 latest。

官方安装文档里的 Compose 还包含 Collabora，用来做在线文档。本文只部署 Filestash 本身，不加入那一个服务。

完整标签见标签列表。

拉取镜像

用 轩辕镜像 加速拉取：

bash
docker pull docker.xuanyuan.run/machines/filestash:latest

完成后，再写下面的 Compose。

Docker Compose 部署

管理员密码和站点配置在宿主机目录 state/，对应容器内 /app/data/state。删掉 state/ 之后，下次打开会再次要求设置密码。docker compose down 不加额外参数时，不会删除 state/。

state/ 里已经有配置时，不要清空这个目录，直接执行启动命令。

以前用 docker run 创建过同名容器时，先删掉容器再启动 Compose。这一步不删除命名卷。旧命令如果没有挂载 /app/data/state，管理员密码在容器里，不在 state/ 目录中。

1. 创建目录，并把所有权交给当前用户，后面的 cat 才能写进去：

bash
sudo mkdir -p /www/wwwroot/filestash/state
sudo chown -R "$USER":"$USER" /www/wwwroot/filestash

同名容器还在时：

bash
docker rm -f filestash

2. 写入 compose.yaml。容器监听 8334，宿主机使用同一个端口。

bash
cd /www/wwwroot/filestash
cat > compose.yaml <<'EOF'
name: filestash

services:
  filestash:
    image: docker.xuanyuan.run/machines/filestash:latest
    container_name: filestash
    restart: unless-stopped
    ports:
      - "8334:8334"
    volumes:
      - ./state:/app/data/state
EOF

3. 启动：

bash
cd /www/wwwroot/filestash
docker compose up -d

4. 看状态。filestash 应为 Up，端口是 0.0.0.0:8334->8334/tcp。

bash
docker compose ps

设置管理员密码

容器是 Up 之后，在跑 Docker 的这台机器上打开：

text
http://127.0.0.1:8334

从别的电脑访问时，把 127.0.0.1 换成这台机器的 IP，例如 http://服务器 IP:8334。云服务器还要在安全组里放行 8334。

第一次打开会看到「Welcome Aboard!」。页面原文是「First thing first, setup your password:」。在「Password」里设置管理员密码，然后点右侧箭头。这里没有预置密码。

这个密码用于进入后台。后台地址是：

text
http://127.0.0.1:8334/admin

存储驱动列表在 /admin/storage。当前镜像带了哪些后端，可以打开 /about，查看以 plg_backend 开头的项目。

连接 SFTP

密码设置完成后，登录页上有「WebDav」「FTP」「SFTP」「GIT」「S3」。点「SFTP」。

主表单上的字段是「Hostname」「Username」「Password」。「Hostname」带星号，必填。填服务器 IP 或域名、登录用户名和密码，点击「连接」。

端口不在这个主表单上。SSH 不是 22 时，先勾选「Advanced」，再填写改过的端口。

连上之后，面包屑会显示当前用户，例如 Filestash > root。左侧有「您的文件」。中间可以点「新文件」「新目录」。右下角是上传按钮。

同一页上的「WebDav」「FTP」「GIT」「S3」换的是协议。WebDAV 用于 Nextcloud 这类服务，S3 用于 AWS S3 以及 MinIO 这类兼容接口。字段以当前标签页上显示的为准，填完后同样点击「连接」。

使用域名访问

只在本机使用时，可以继续用 http://127.0.0.1:8334。要用域名给别人打开时，在 Filestash 前面放一层反向代理，并由代理做 HTTPS。官方安装说明把 TLS 放在反向代理上。

下面是一段 Nginx 示例。把 filestash.example.com 换成你的域名。Filestash 仍监听本机 8334。

nginx
server {
    listen 80;
    server_name filestash.example.com;

    location / {
        proxy_pass http://127.0.0.1:8334;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

改完后重载 Nginx。证书和 HTTPS 的其余做法见官方安装文档。

备选：docker run

上面的 Compose 已经在跑时，停在那里即可，不必再做这一节。

没有 Compose、只想短期打开看看时，用一条 docker run。8334 上已经有 Compose 里的容器时，先停掉它。数据目录用 /www/wwwroot/filestash-run/state，不要挂上面的 state/。

bash
cd /www/wwwroot/filestash
docker compose down

bash
sudo mkdir -p /www/wwwroot/filestash-run/state
sudo chown -R "$USER":"$USER" /www/wwwroot/filestash-run
docker run -d 
  --name filestash 
  --restart unless-stopped 
  -p 8334:8334 
  -v /www/wwwroot/filestash-run/state:/app/data/state 
  docker.xuanyuan.run/machines/filestash:latest

然后打开 http://127.0.0.1:8334，按「设置管理员密码」填写。

试用结束、要回到 Compose 时，停掉这个容器，再启动原来的 Compose。不要删除 /www/wwwroot/filestash/state。

bash
docker stop filestash && docker rm filestash
cd /www/wwwroot/filestash
docker compose up -d

常见问题

Q1：刷新后又要设置密码？

管理员密码在 /www/wwwroot/filestash/state。Compose 没有挂载这个目录时，删掉容器就会丢掉密码。确认 compose.yaml 里有 ./state:/app/data/state，并且没有删过 state/。

Q2：8334 打不开？

按这个顺序看：

1. docker compose ps 里 filestash 是否为 Up。
2. 在服务器上打开 http://127.0.0.1:8334。本机打不开时，先看 docker compose logs --tail 80 filestash。
3. 本机通、别的电脑不通时，再检查安全组和防火墙是否放行了 8334。

Q3：SFTP 点连接没有进入目录？

先核对「Hostname」「Username」「Password」。端口不在主表单上，SSH 不是 22 时勾选「Advanced」再改。Filestash 容器要能访问这台 SFTP 服务器，目标机器的防火墙也要允许来自 Filestash 所在主机的连接。

Q4：登录页上没有 LOCAL？

本文这张登录页截图里的协议是 WebDav、FTP、SFTP、GIT、S3，没有 LOCAL。本地文件系统是一种存储驱动，要在 /admin/storage 里启用。只把宿主机目录用 -v 挂进容器，登录页不会自动多出一个 LOCAL 标签。

Q5：如何升级？

本文使用 latest，这个标签会在上游发布新镜像后发生变化。升级前先保留 state/。然后执行：

bash
cd /www/wwwroot/filestash
docker compose pull
docker compose up -d

不要改去使用提交哈希或 latest-amd64。state/ 保持不动。

Q6：如何停止？

还要保留管理员密码和后台配置时，不要删除 state/。

bash
cd /www/wwwroot/filestash
docker compose down

用 docker run 启动的：

bash
docker stop filestash && docker rm filestash

站点不再需要时，再删除数据目录：

bash
rm -rf /www/wwwroot/filestash/state /www/wwwroot/filestash-run

Q7：官方 Compose 里的 Collabora 要不要一起上？

本文不部署它。官方下载的 Compose 里还有一个 WOPI 服务，用来做在线文档。只做文件浏览和 SFTP 时，一个 Filestash 容器就够。要按官方那份文件部署时，见安装文档。

Q8：可以把 8334 直接暴露到公网吗？

登录页会提交存储密码。给公网使用时，用「使用域名访问」里的反向代理做 HTTPS，不要长期开放明文的 8334。

命令速查

bash
docker pull docker.xuanyuan.run/machines/filestash:latest

cd /www/wwwroot/filestash
docker compose up -d
docker compose ps
docker compose logs --tail 80 filestash
docker compose down

没有 Compose 时用「备选：docker run」里的命令。浏览器打开 http://127.0.0.1:8334，在「Password」里设置管理员密码，再点「SFTP」连接。配置在 state/。

延伸阅读

阅读原文

• 轩辕镜像官方博客：https://xuanyuan.cloud/blog/filestash-docker-deploy