Ubuntu 22.04 安装 Filestash 指南

Ubuntu 22.04 服务器安装 Filestash 的三方案实测全流程：官方二进制+systemd 托管、离线安装、前台运行，含 Web 初始化、SFTP/WebDAV 双后端上传下载验证闭环、升级与卸载（v0.6.20261022，2026-10-22 实测）。

FilestashFilestashUbuntu 22.04Linux系统2026/10/22

Ubuntu 22.04 安装 Filestash 指南

Filestash 是一个网关型的自托管 Web 文件管理器，官方以单个静态编译的二进制文件分发 Linux 版本，"0 依赖，甚至不依赖 libc"（官方安装页原文），因此安装动作可以压缩为「下载 → 赋权 → 运行」三步。本文面向 Ubuntu 22.04 服务器，完整给出在线安装（含 systemd 托管）、离线安装、前台快速运行三种部署路径的实测全过程，并覆盖 Web 初始化、连接 SFTP/WebDAV 存储后端的上传下载验证闭环、升级与卸载，全部命令与回显均来自真实服务器执行记录（安装版本 v0.6.20261022，实测日期 2026-10-22）。

相关阅读：《Filestash 介绍与选型指南》完成了 Filestash 的定位、插件架构与 FileBrowser/Nextcloud/Seafile 的量化对比，本文不重复展开，仅聚焦"装起来、跑起来、用起来"。

一、环境信息说明

本文所有命令与输出均在下列真实服务器环境中执行并逐行采集，未做任何模拟或修饰。

项目值
演示服务器filestash-server（10.89.57.2），独立 Ubuntu 22.04 服务器
操作系统Ubuntu 22.04.5 LTS（x86_64）
服务端口8334（Filestash 默认端口）
Filestash 版本v0.6.20261022（滚动 latest 构建，构建日期即下载日 2026-10-22）
二进制体积14072316 字节（约 13.4 MiB）
二进制 SHA-2566234dafb71bad6b409dde93396888162bcb5686c51e9659daf9a24cd80d9c122
安装目录/opt/filestash
服务账号filestash（系统用户，uid=999，禁止登录 shell）
进程托管systemd（filestash.service）
存储后端 ASFTP 服务器 10.89.57.3（OpenSSH，账号 root / q1w2e3r4）
存储后端 BWebDAV 服务器 10.89.57.4:8080（wsgidav，账号 admin / q1w2e3r4）

版本号的取证方式：向服务端口发起请求，从响应头读取运行版本，这是滚动发布形态下最可靠的本机确认手段：

$ curl -s -D- -o /dev/null http://127.0.0.1:8334/
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: text/html
Etag: HFEb0cWFbS
Referrer-Policy: same-origin
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-Powered-By: Filestash/v0.6.20261022 <https://filestash.app>
X-XSS-Protection: 1; mode=block
Date: Thu, 22 Oct 2026 04:20:28 GMT
Transfer-Encoding: chunked

二、前置条件

  1. 一台 Ubuntu 22.04 服务器（1 核 / 128MB 内存即可满足官方最低要求；本文实测空载进程常驻内存约 76MB）。
  2. 服务器能访问互联网（方案 A / 下载阶段需要）；离线环境走方案 B。
  3. 具备 root 或 sudo 权限。
  4. 放行防火墙端口 8334（见下文 ufw 实测）。
  5. 一台可供连接的存储后端（SFTP、WebDAV 均可；本文准备了两台用于验证闭环）。Filestash 本身不提供存储，它通过后端插件连接到已有存储，这是它与 Nextcloud 这类"自带存储"产品的本质差异。

防火墙放行的实测记录（在 filestash-server 上执行，并从另一台服务器 10.89.57.3 验证效果）：

$ ufw allow 8334/tcp
Rules updated
Rules updated (v6)
$ ufw --force enable
Firewall is active and enabled on system startup
$ ufw status verbose
Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
8334/tcp                   ALLOW IN    Anywhere
8334/tcp (v6)              ALLOW IN    Anywhere (v6)

从另一台服务器验证：放行端口可达、未放行端口被拦截——

$ curl -s --max-time 5 http://10.89.57.2:8334/healthz
{"status": "pass"}
$ curl -s --max-time 3 http://10.89.57.2:9999/
curl: (28) Connection timed out

三、版本选型说明

Filestash 的发布形态需要特别说明，这直接影响安装命令的写法：

  • 官方下载站滚动分发：https://downloads.filestash.app/latest/ 目录下的 filestash_linux_<架构>.bin 始终指向最新构建。文件名中的 $(uname -m) 由安装命令动态替换（x86_64 服务器实际下载的是 filestash_linux_x86_64.bin）。
  • 版本号即构建日期：本次下载的运行版本为 v0.6.20261022（见响应头 X-Powered-By），其中 20261022 即构建日期，与下载日一致。选择"latest 滚动版"意味着每次重新下载都可能拿到更新的构建。
  • GitHub Releases 页为空：官方仓库（filestash/filestash）的 Releases 页面没有发布条目，最新 git tag 停留在 v0.4（查询日期 2026-10-22）。因此不要以 GitHub 页面判断软件的"最新版本"，应以下载站 + 响应头实测为准。
  • 许可：AGPL-3.0 开源 + 商业双许可，直接安装使用开源版无需购买授权（config 中的 license 字段默认值为 agpl）。
  • 校验值：官方下载站未随包发布 SHA256SUMS 文件，本文在安装当日实测三次下载（在线装、离线跳板机、scp 传输后）哈希完全一致，可作为当日构建的基线参照；读者实际安装时应重新计算并自行核对来源可信（HTTPS 官方域名）。

四、方案A：官方二进制在线安装（推荐）

这是官方文档的 Door 1 主路径："download the 13MB binary, run it, done"。全程约 2 分钟。

4.1 下载二进制

$ mkdir -p /opt/filestash && cd /opt/filestash
$ curl -o filestash.bin https://downloads.filestash.app/latest/filestash_linux_$(uname -m).bin

说明：官方文档给的是前台进度条形式，实测记录补上结果行——下载完成后校验体积与哈希：

$ curl -o filestash.bin -sS -w "HTTP %{http_code} %{size_download} bytes\n" https://downloads.filestash.app/latest/filestash_linux_$(uname -m).bin
HTTP 200 14072316 bytes
$ sha256sum filestash.bin
6234dafb71bad6b409dde93396888162bcb5686c51e9659daf9a24cd80d9c122  filestash.bin

4.2 创建系统用户

为服务创建无登录权限的系统账号，家目录即安装目录：

$ useradd -r -m -d /opt/filestash -s /usr/sbin/nologin filestash
useradd: warning: the home directory /opt/filestash already exists.
useradd: Not copying any file from skel directory into it.
$ id filestash
uid=999(filestash) gid=999(filestash) groups=999(filestash)

提示：warning 是因为目录已存在（二进制已先下载进去），useradd 跳过骨架文件复制，无害。若希望输出干净，可先建用户再下载。

4.3 赋权并固定归属

$ chmod +x filestash.bin
$ chown -R filestash:filestash /opt/filestash
$ ls -la /opt/filestash
total 13756
drwxr-xr-x 3 filestash filestash     4096 Oct 22 04:44 .
drwxr-xr-x 1 root      root          4096 Oct 22 04:44 ..
drwxr-xr-x 4 filestash filestash     4096 Oct 22 04:44 data
-rwxr-xr-x 1 filestash filestash 14072316 Oct 22 04:44 filestash.bin

data/ 目录是首次运行后自动生成的状态目录（见 4.6），最终形态如上：属主为 filestash 用户。

4.4 编写 systemd 单元

$ cat > /etc/systemd/system/filestash.service <<'EOF'
[Unit]
Description=Filestash web file manager
Documentation=https://www.filestash.app/docs/
After=network.target

[Service]
Type=simple
User=filestash
WorkingDirectory=/opt/filestash
ExecStart=/opt/filestash/filestash.bin
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
$ systemctl daemon-reload && systemctl enable --now filestash
Created symlink /etc/systemd/system/multi-user.target.wants/filestash.service → /etc/systemd/system/filestash.service.

两个要点：

  • WorkingDirectory=/opt/filestash 必须正确：Filestash 把状态数据写到工作目录下的 data/，工作目录不对会导致配置"消失"。
  • Restart=on-failure + RestartSec=5：异常退出 5 秒后自动拉起，生产环境建议保留。

4.5 确认服务状态

$ systemctl status filestash --no-pager -l
● filestash.service - Filestash web file manager
     Loaded: loaded (/etc/systemd/system/filestash.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 04:44:20 UTC; 3s ago
       Docs: https://www.filestash.app/docs/
   Main PID: 2917 (filestash.bin)
      Tasks: 11 (limit: 629145)
     Memory: 76.1M
        CPU: 717ms
     CGroup: /system.slice/filestash.service
             └─2917 /opt/filestash/filestash.bin

Oct 22 04:44:20 filestash-server systemd[1]: Started Filestash web file manager.
$ ss -tlnp | grep 8334
LISTEN 0      4096               *:8334             *:*    users:(("filestash.bin",pid=2917,fd=9))

进程常驻内存 76.1M，监听 0.0.0.0:8334。

4.6 首次启动的健康状态与目录结构

首次启动后（尚未完成 Web 初始化前），健康端点返回"待配置"状态，这是判断安装是否完成、配置是否齐全的第一检查点：

$ curl -s http://127.0.0.1:8334/healthz
{"status": "transcient", "reason": "configuration_error", "debug": [
    "general.secret_key[size=16]",
    "admin.auth[size=0]",
    "log[level=INFO]",
    "connections[size=0]",
    "middleware.identity_provider[type=][params=0]",
    "middleware.attribute_mapping[type=][params=0]"
]}

transcient（瞬时态）+ configuration_error 表示程序在正常运行、但管理员密码与存储连接尚未设置。此时状态目录已自动生成：

$ ls /opt/filestash/data/state/
certs
config
db
log
plugins
search
$ head -8 /opt/filestash/data/state/config/config.json
{
    "general": {
        "secret_key": "tcCVN9MHxDvQyvgw"
    },
    "connections": []
}

config.json 中的 secret_key 是首次启动随机生成的 16 位会话密钥。整个初始化完成后（第八节），/healthz 会变为 {"status": "pass"}——这也是判断"装完了没有"的最简标准。

五、方案B：离线安装（内网/隔离环境）

适用于目标服务器无法访问外网的场景（官方文档称 "air-gapped" 旁路场景）。核心思路：在一台有外网的跳板机下载并校验，再传到目标服务器。以下实测中，跳板机为 10.89.57.3，目标服务器仍为 filestash-server（10.89.57.2）。

5.1 跳板机：下载与校验

$ curl -o /tmp/filestash.bin -sS -w "HTTP %{http_code} | %{size_download} bytes\n" https://downloads.filestash.app/latest/filestash_linux_x86_64.bin
HTTP 200 | 14072316 bytes
$ sha256sum /tmp/filestash.bin
6234dafb71bad6b409dde93396888162bcb5686c51e9659daf9a24cd80d9c122  /tmp/filestash.bin

与 4.1 在线安装下载的哈希完全一致，说明当日滚动构建内容稳定。

5.2 传输到目标服务器并二次校验

$ scp root@10.89.57.3:/tmp/filestash.bin /opt/filestash/filestash.bin
root@10.89.57.3's password:
filestash.bin                                                    100%   13MB  33.7MB/s   00:00
$ cd /opt/filestash && sha256sum filestash.bin > filestash.bin.sha256
$ sha256sum -c filestash.bin.sha256
filestash.bin: OK

若目标服务器连跳板机方向也不可达，可经 U 盘等介质拷贝，校验步骤不变。

5.3 后续步骤

从 4.2（创建用户）开始，与方案 A 完全一致——离线只影响"文件怎么来"，不影响"怎么装、怎么跑"。

六、方案C：前台快速运行（临时验证）

不配置 systemd，直接前台运行，适合 5 分钟内验证二进制在本机可用（依赖、端口、防火墙）：

$ cd /opt/filestash
$ ./filestash.bin
2026/10/22 04:41:39 SYST WARN plg_video_transcoder: "ffmpeg" not found in $PATH, transcoding disabled
2026/10/22 04:41:39 SYST INFO [http] starting ...
2026/10/22 04:41:39 SYST INFO [http] listening on :8334

三行输出读法：

  1. plg_video_transcoder ... ffmpeg not found：视频转码插件没找到 ffmpeg，相关功能自动禁用。这不是错误，不影响文件管理主功能；需要视频转码时再安装 ffmpeg 并重启。
  2. [http] starting ... / listening on :8334：服务启动并监听 8334，与官方文档展示的启动输出一致。
  3. Ctrl-C 即停止。验证通过后建议改用方案 A 的 systemd 托管。

若希望保持前台运行但退出终端不中断，可用 nohup ./filestash.bin > /var/log/filestash.log 2>&1 &，但进程将脱离 service 用户管理，仅建议临时使用。

七、方案对比与选择建议

维度方案A 在线+systemd方案B 离线方案C 前台运行
适用场景常规服务器首选内网/隔离环境快速验证、临时演示
外网依赖下载时需要仅跳板机需要下载时需要
进程托管systemd，开机自启systemd（同 A）无，终端/会话生命周期
崩溃自愈Restart=on-failure同 A无
升级方式重新下载替换 + 重启重新走跳板机链路重新下载替换
实测耗时约 2 分钟约 5 分钟约 1 分钟

选择建议：能上外网直接方案 A；安全基线要求"服务器不出网"用方案 B，且务必执行 sha256 校验；方案 C 只做可用性验证，不要作为长期运行形态。三方案安装的同一份二进制，运行行为完全一致。

八、Web 初始化与首次连接

8.1 浏览器向导（标准路径）

服务启动后访问 http://<服务器IP>:8334（本文为 http://10.89.57.2:8334），进入三步向导：

  1. step 1 设置管理员密码：为 admin 账号设置密码（本文统一使用 q1w2e3r4）。官方也支持通过环境变量注入 bcrypt 哈希跳过此步。
  2. step 2 选择预设：向导提供预设模板（如"local storage, just for me"），也可跳过预设自行配置。本文因需要同时连接 SFTP 与 WebDAV 两类后端，选择手动配置连接清单。
  3. step 3 进入登录页：访问 /login，从连接列表选择后端、输入后端凭据登录；官方文档特别强调在 Web 内置控制台里"永远不要用 sudo，直接 ls"。

8.2 等价 API 序列（自动化初始化）

向导动作与一组管理 API 一一对应，便于自动化部署。以下为与 8.1 等价的 API 实测记录（在 filestash-server 本机执行）。

第一步，读取管理端配置表单（管理端点要求携带 X-Requested-With: XmlHttpRequest 请求头，否则返回 403）：

$ curl -s http://127.0.0.1:8334/admin/api/config | head -30
{
    "status": "ok",
    "result": {
        "general": {
            "name": {
                "label": "Name",
                "type": "text",
                "description": " Hastings 表示的是您的组织/公司名称",
                "placeholder": "Your company name",
                "default": null,
                "value": null
            },
            ...

返回体是完整参数 schema（每项含 label/type/description/default/value）。第二步，把表单按"叶子节点取 value"的规则拍平、写入 admin 的 bcrypt 哈希与连接清单后整体提交：

import bcrypt, json, urllib.request, http.cookiejar

H = {"Content-Type": "application/json", "X-Requested-With": "XmlHttpRequest"}
def call(url, payload=None):
    data = json.dumps(payload).encode() if payload is not None else None
    return json.load(urllib.request.urlopen(urllib.request.Request(
        url, data=data, headers=H, method="POST" if payload is not None else "GET")))

def flatten(o):
    out = {}
    for k, v in o.items():
        if isinstance(v, dict) and all(k in v for k in ("label", "type", "default", "value")):
            val = v["value"]
            if v["type"] == "number":
                try: val = int(val)
                except Exception: val = 0
            out[k] = val
        elif isinstance(v, dict): out[k] = flatten(v)
        else: out[k] = v
    return out

body = flatten(call("http://127.0.0.1:8334/admin/api/config")["result"])
body["auth"]["admin"] = bcrypt.hashpw(b"q1w2e3r4", bcrypt.gensalt(rounds=10)).decode()
body["connections"] = [
    {"type": "sftp",   "label": "SFTP 服务器"},
    {"type": "webdav", "label": "WebDAV 服务器"},
]
print(call("http://127.0.0.1:8334/admin/api/config", body))
print(call("http://127.0.0.1:8334/admin/api/session", {"password": "q1w2e3r4"}))

实测输出：

$ python3 admin_init.py
{'status': 'ok'}
{'status': 'ok', 'result': True}

第三步，验证：healthz 转为 pass，连接清单出现在公共配置中——

$ curl -s http://127.0.0.1:8334/healthz
{"status": "pass"}
$ curl -s http://127.0.0.1:8334/api/config | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin)['result']['connections'], ensure_ascii=False, indent=2))"
[
  {
    "label": "SFTP 服务器",
    "type": "sftp"
  },
  {
    "label": "WebDAV 服务器",
    "type": "webdav"
  }
]

8.3 连接 SFTP 后端：登录与上传下载验证闭环

以下通过 Filestash 的文件 API 完成一次完整闭环（会话建立 → 列目录 → 建目录 → 移动 → 下载 → 上传 → 删除），全部命令与回显为实测原文。

建立会话（POST /api/session 提交后端类型与后端凭据，返回 Bearer 令牌）：

$ curl -s -X POST http://127.0.0.1:8334/api/session \
    -H "Content-Type: application/json" -H "X-Requested-With: XmlHttpRequest" \
    -d '{"type": "sftp", "hostname": "10.89.57.3", "username": "root", "password": "q1w2e3r4"}'
{
    "status": "ok",
    "result": {
        "home": "/root/",
        "is_authenticated": true,
        "backendID": "ncEdocxbRDbr4dWbQcPn",
        "authorization": "hrEYrM3XnFjEYlBhVNWaS_xUG6BpDeBt..."
    }
}

后续请求以 Authorization: Bearer <authorization> 携带令牌（下称 $TOK）。

列目录（后端 /srv/share/ 下预置了 2MB 的 sample.bin 与 up_test.txt）：

$ curl -s "http://127.0.0.1:8334/api/files/ls?path=/srv/share/" \
    -H "Authorization: Bearer $TOK" -H "X-Requested-With: XmlHttpRequest"
{
    "status": "ok",
    "results": [
        {"name": "sample.bin", "type": "file", "size": 2097152, ...},
        {"name": "up_test.txt", "type": "file", "size": 55, ...},
        {"name": "docs", "type": "directory", ...}
    ]
}

注意列表键名是复数 results。

建目录 / 移动 / 下载 / 上传 / 删除：

$ curl -s -X POST "http://127.0.0.1:8334/api/files/mkdir?path=/srv/share/b1-verify/" -H "Authorization: Bearer $TOK" -H "X-Requested-With: XmlHttpRequest"
{"status": "ok"}

$ curl -s -X POST "http://127.0.0.1:8334/api/files/mv?from=/srv/share/up_test.txt&to=/srv/share/b1-verify/up_test.txt" -H "Authorization: Bearer $TOK" -H "X-Requested-With: XmlHttpRequest"
{"status": "ok"}

$ curl -s "http://127.0.0.1:8334/api/files/cat?path=/srv/share/b1-verify/up_test.txt" -H "Authorization: Bearer $TOK" -H "X-Requested-With: XmlHttpRequest"
uploaded via filestash api Thu Oct 22 04:10:19 UTC 2026

$ curl -s -X POST "http://127.0.0.1:8334/api/files/cat?path=/srv/share/b1-verify/upload-b1.txt" \
    -H "Authorization: Bearer $TOK" -H "X-Requested-With: XmlHttpRequest" \
    --data-binary "uploaded via filestash api b1"
{"status": "ok"}

$ curl -s -X POST "http://127.0.0.1:8334/api/files/rm?path=/srv/share/b1-verify/upload-b1.txt" -H "Authorization: Bearer $TOK" -H "X-Requested-With: XmlHttpRequest"
{"status": "ok"}

在后端服务器侧交叉验证——文件确实落到了 SFTP 存储上，而非 Filestash 本地：

# 在 10.89.57.3 上
$ ls -la /srv/share/b1-verify/
total 12
drwxr-xr-x 2 root root    4096 Oct 22 04:24 .
drwxr-xr-x 4 root root    4096 Oct 22 04:24 ..
-rw-r--r-- 1 root root   55 Oct 22 04:10 up_test.txt
$ cat /srv/share/b1-verify/up_test.txt
uploaded via filestash api Thu Oct 22 04:10:19 UTC 2026

下载读回的内容与上传写入的内容一致，闭环成立。

8.4 连接 WebDAV 后端（第二协议验证）

同一套 API，仅会话参数不同（url 指向 WebDAV 地址）：

$ curl -s -X POST http://127.0.0.1:8334/api/session \
    -H "Content-Type: application/json" -H "X-Requested-With: XmlHttpRequest" \
    -d '{"type": "webdav", "url": "http://10.89.57.4:8080/", "username": "admin", "password": "q1w2e3r4"}'
{
    "status": "ok",
    "result": {
        "home": "/",
        "is_authenticated": true,
        "backendID": "hdsd4qc4dTXc2tdBcdbN",
        "authorization": "hrEYrM3XnFjEYlBlbeHbIe1BHMEHLEqN..."
    }
}
$ curl -s "http://127.0.0.1:8334/api/files/ls?path=/" -H "Authorization: Bearer $TOK" -H "X-Requested-With: XmlHttpRequest" | python3 -c "import json,sys; print([(f['name'], f['type'], f.get('size')) for f in json.load(sys.stdin)['results']])"
[('readme-dav.txt', 'file', 20), ('dav-sample.bin', 'file', 2097152), ('via-filestash.txt', 'file', 63)]

对 WebDAV 后端同样执行 mkdir → mv → cat 下载 → 上传 → rm，全部返回 {"status": "ok"}，并在 10.89.57.4 的导出目录中确认 b1-verify/readme-dav.txt（20 字节，内容 webdav backend file）真实存在。至此，Filestash 对两类异构存储后端（SFTP、WebDAV）的代理读写能力均验证通过。

九、配置说明

安装形态下与配置相关的文件与行为：

路径/位置说明
/opt/filestash/data/state/config/config.json唯一持久化配置文件，随 WorkingDirectory 相对寻址；手工修改后需重启服务
general.secret_key首次启动随机生成的 16 位密钥，用于会话签名；不可丢失，否则所有在线会话失效
auth.admin管理员密码的 bcrypt 哈希，通过 Web 向导或 8.2 的 API 写入
connections登录页展示的连接卡片清单，每项仅含 type 与 label；用户的后端凭据不落盘在服务端，保存在用户会话令牌中
/opt/filestash/data/state/其余状态：log/（访问与系统日志）、db/、certs/、plugins/、search/
备份建议备份 config/config.json 即可覆盖全部关键配置

最小可用配置示例（与本文实测环境一致的结构）：

{
    "general": {
        "secret_key": "tcCVN9MHxDvQyvgw"
    },
    "auth": {
        "admin": "$2b$10$...(bcrypt hash)"
    },
    "connections": [
        { "type": "sftp", "label": "SFTP 服务器" },
        { "type": "webdav", "label": "WebDAV 服务器" }
    ]
}

配置参数（显示隐藏文件、日志级别、分享开关、Office/MCP 网关等）的逐项含义与在线修改实测，见《Filestash 配置参数详解》。

十、升级、降级与多版本共存

Filestash 的升级即"替换二进制 + 重启"，因为状态全部在 data/，与二进制无关：

$ cd /opt/filestash
$ curl -o filestash.bin.new https://downloads.filestash.app/latest/filestash_linux_$(uname -m).bin
$ sha256sum filestash.bin.new
$ systemctl stop filestash
$ mv filestash.bin.new filestash.bin && chmod +x filestash.bin && chown filestash:filestash filestash.bin
$ systemctl start filestash && systemctl is-active filestash
active
$ curl -s http://127.0.0.1:8334/healthz
{"status": "pass"}

要点：

  • 升级前备份 data/state/config/config.json；滚动 latest 可能引入配置结构变化，保留旧文件可快速回退。
  • 回退：保留旧版本二进制副本（如 filestash.bin.v0.6.20261022），降级 = 换回旧文件 + 重启。
  • 多版本共存：Filestash 的状态目录跟随 WorkingDirectory，把不同版本二进制放到不同目录（各自 data/ 独立）即可并行运行，仅需为每个实例分配不同端口（config 中 general.port 或前端反代）。
  • 由于 latest 是滚动构建，重装/升级后请用响应头 X-Powered-By 重新确认实际运行版本，而不是假设与本文一致。

十一、常见问题与排障实录

Q1：启动日志出现 plg_video_transcoder: "ffmpeg" not found in $PATH, transcoding disabled，要紧吗？

不要紧。这是视频转码插件提示缺 ffmpeg，相关功能自动禁用，文件管理主功能不受影响。需要在线视频播放转码时安装 ffmpeg 后重启服务即可。

Q2：/healthz 一直返回 {"status": "transcient", "reason": "configuration_error", ...}？

这是未完成初始化的正常状态（见 4.6）。debug 数组会列出缺什么：admin.auth[size=0] 表示管理员密码未设置，connections[size=0] 表示没有可用连接。完成第八节初始化后即变 {"status": "pass"}。

Q3：调用 POST /api/session 返回 403 {"status": "error", "message": "Not Allowed"}？

实测踩过的坑：会话提交体中的后端类型字段名必须是 type，而不是 backend。写错时服务日志会出现 AUDIT action[fail] backend[] user[...] target[...]（backend 字段为空），随后 403。正确写法：{"type": "sftp", "hostname": "...", "username": "...", "password": "..."}。

Q4：带 Cookie 直接 curl 调用文件接口时好时坏，甚至被 403 拦截，日志出现 Intrusion detection？

Filestash 内置入侵检测，对"非浏览器形态"的直连调用会累积失败计数并主动封锁。脚本集成应使用 8.3 的 Bearer 令牌方式（POST /api/session 换取 authorization，后续请求带 Authorization: Bearer <token>），实测 Bearer 调用不受该防护影响。

Q5：mkdir 一个已存在的目录返回 409？

实测返回 HTTP 409 Conflict + {"status": "error", "message": "Failure"}。目录已存在时 mkdir 不会幂等成功，脚本中应先 ls 判断或捕获 409 跳过。

Q6：列目录接口返回里找不到文件列表？

键名是 results（复数），不是 result；且各条目的时间字段为 time（毫秒时间戳），详细 mode/uid 等在 metadata 里。

Q7：端口 8334 被其他进程占用？

ss -tlnp | grep 8334 找到占用进程；变更 Filestash 端口需在 config.json 设置 general.port 后重启，防火墙同步放行新端口。

Q8：改了 config.json 不生效？

配置仅在后端启动时读取，手工修改后必须 systemctl restart filestash。优先使用管理界面/Admin API 修改（实时生效），手工编辑适合初始化前的预置。

十二、卸载清理

完整卸载的实测记录（验证"卸干净"的每一步）：

$ systemctl stop filestash
$ systemctl disable filestash
Removed /etc/systemd/system/multi-user.target.wants/filestash.service.
$ rm -f /etc/systemd/system/filestash.service && systemctl daemon-reload && systemctl reset-failed
$ userdel -r filestash
userdel: filestash mail spool (/var/mail/filestash) not found
$ rm -rf /opt/filestash

（userdel 提示邮件池目录本就不存在，可忽略；退出码为 0。）

验证卸载结果：

$ systemctl status filestash
Unit filestash.service could not be found.
$ id filestash
id: 'filestash': no such user
$ ls /opt/filestash
ls: cannot access '/opt/filestash': No such file or directory
$ curl -s http://127.0.0.1:8334/healthz
curl: (7) Failed to connect to 127.0.0.1 port 8334 after 0 ms: Connection refused

服务单元、系统账号、安装目录与监听端口四项全部清空，即卸载完成。若需保留用户数据另装，请在 rm -rf /opt/filestash 前备份 data/state/config/config.json。

十三、参考链接

  1. Filestash 官方安装文档（Install and Upgrade）：https://www.filestash.app/docs/install/
  2. 官方下载站（滚动 latest 二进制与 docker-compose 文件）：https://downloads.filestash.app/latest/
  3. 健康端点：http://<服务器IP>:8334/healthz
  4. 站内相关文档：

本文实测环境：Ubuntu 22.04.5 LTS，Filestash v0.6.20261022（官方滚动 latest，下载于 2026-10-22）。文中所有命令输出均为当日实测原文；滚动发布形态下，新下载的构建版本号可能更新。