Filestash 运维管理与 API 实操详解
Filestash 运维与 API 实操收官篇：/healthz 与 /about 盘点、access.log 四类日志行解剖、AUDIT 审计边界、会话双通道、文件操作全集、22 后端连接表单、共享链接全生命周期，附 zip/search 实测边界与根因（v0.6.20261022，2026-10-22 实测）。
Filestash 运维管理与 API 实操详解
本文是 Filestash 专栏的收官篇，面向已按《Ubuntu 22.04 安装 Filestash 指南》完成部署的运维与平台工程师，覆盖两条主线：运维线——服务状态检查、健康检查端点、/about 构建溯源页、日志文件逐行解剖、审计日志边界；API 线——会话认证、文件操作全集、22 个存储后端连接表单、共享链接全生命周期（创建、口令验证、穿越访问、删除），并对打包下载（zip）与全文搜索（search）两个接口给出实测结论与根因证据。全部命令与回显均来自真实服务器执行记录（版本 v0.6.20261022，实测日期 2026-10-22）。
相关阅读：《Filestash 介绍与选型指南》讲定位与架构，《Ubuntu 22.04 安装 Filestash 指南》讲部署与初始化，《Filestash 配置参数详解》讲配置体系——本文负责"装好之后怎么管、怎么排障、怎么用 API"。
一、环境信息说明
| 项目 | 值 |
|---|---|
| Filestash 服务器 | filestash-server（10.89.57.2），Ubuntu 22.04.5 LTS，服务端口 8334，systemd 托管（filestash.service），安装目录 /opt/filestash |
| Filestash 版本 | v0.6.20261022（构建 commit 244e8b74ebdf60cdbd650a24c1f22569d839a814） |
| 管理员账号 | admin / q1w2e3r4 |
| 存储后端 A | SFTP 服务器 10.89.57.3（OpenSSH，账号 root / q1w2e3r4），/srv/share/ 下有 sample.bin（2MB）、docs/hello.txt、b1-verify/ |
| 存储后端 B | WebDAV 服务器 10.89.57.4:8080（wsgidav，账号 admin / q1w2e3r4），根目录有 dav-sample.bin、via-filestash.txt、b1-verify/ |
| 已配置连接 | connections：{type: sftp, label: SFTP 服务器}、{type: webdav, label: WebDAV 服务器} |
| 日志文件 | /opt/filestash/data/state/log/access.log |
二、运行状态与版本盘点
2.1 服务状态三板斧
日常巡检三条命令（systemd 状态、端口监听、健康端点）：
$ systemctl status filestash --no-pager | head -6
● 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; 4min 42s ago
Main PID: 2917 (filestash.bin)
Tasks: 11 (limit: 629145)
Memory: 76.1M
$ ss -tlnp | grep 8334
LISTEN 0 4096 *:8334 *:* users:(("filestash.bin",pid=2917,fd=9))
$ curl -s http://127.0.0.1:8334/healthz
{"status": "pass"}
2.2 /healthz：健康检查端点的两种形态
/healthz 无需认证，是监控脚本与负载均衡探针的最佳接入点。它有两种实测形态：
形态一：pass——配置齐全、服务正常（本环境当前状态）：
$ curl -s -D- http://127.0.0.1:8334/healthz
HTTP/1.1 200 OK
Content-Type: application/json
X-Powered-By: Filestash/v0.6.20261022 <https://filestash.app>
...
{"status": "pass"}
形态二：transcient（瞬时态）——程序在运行但配置不完整，debug 数组逐项列出缺什么（首启尚未初始化时的实测回显，完整初始化过程见安装篇）：
{"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]"
]}
巡检口径：status=pass 视为健康；transcient 视为"待配置"，刚部署完属预期，长期出现则说明初始化没做完；非 200 响应或超时按服务异常处理。
2.3 /about：构建溯源与插件清单页
/about 页面（无需认证）一次性给出版本、哈希与许可信息，是滚动发布形态下最可靠的"这是哪个构建"取证入口：
$ curl -s http://127.0.0.1:8334/about | python3 -c "
import sys, re
html = sys.stdin.read()
for k in ['Filestash v', 'Commit hash', 'Binary hash', 'Config hash', 'License']:
m = re.search(re.escape(k) + r'\s*</td>\s*<td>\s*([^<]*)', html)
print(k, '->', m.group(1).strip() if m else 'n/a')"
Filestash v -> v0.6.20261022
Commit hash -> 244e8b74ebdf60cdbd650a24c1f22569d839a814
Binary hash ->
Config hash -> beb073f5ba74a72e0436ed110d84dea2ac2f24430a322ebe89f22f0cf19a8abc
License -> AGPL
四个字段读法：Commit hash 是构建对应的源码提交；Config hash 是当前配置内容的指纹（配置一变它就变，可用于确认"配置是否被改过"）；Binary hash 在本构建实测为空；License 显示 AGPL。
页面下方的 Plugins 清单按 STANDARD / ENTERPRISE / CUSTOM / RUNTIME 四类列出全部已编译插件（实测 STANDARD 41 个，ENTERPRISE/CUSTOM/RUNTIME 均为 N/A）：
STANDARD [
plg_authenticate_htpasswd
plg_authenticate_ldap
plg_authenticate_local
plg_authenticate_passthrough
plg_authenticate_wordpress
plg_backend_artifactory
plg_backend_backblaze
plg_backend_dav
plg_backend_dropbox
plg_backend_ftp
plg_backend_gdrive
plg_backend_git
plg_backend_ldap
plg_backend_local
plg_backend_mysql
plg_backend_nfs
plg_backend_nop
plg_backend_perkeep
plg_backend_psql
plg_backend_s3
plg_backend_samba
plg_backend_sftp
plg_backend_storj
plg_backend_tmp
plg_backend_url
plg_backend_webdav
plg_editor_codemirror
plg_editor_wopi
plg_handler_console
plg_handler_mcp
plg_handler_site
plg_image_ascii
plg_image_golang
plg_license
plg_metadata_sqlite
plg_search_stateless
plg_security_scanner
plg_security_svg
plg_starter_http
plg_video_transcoder
plg_widget_console
]
ENTERPRISE [
N/A
]
CUSTOM [
N/A
]
RUNTIME [
N/A
]
这张清单回答"这个构建能做什么"：5 个认证插件、21 个存储后端插件、双编辑器（CodeMirror + WOPI）、console/mcp/site 三个处理器、SVG 安全防护与扫描器防护、HTTP 启动器、视频转码等。功能缺失排查先看这里——清单里没有的插件，配置项配了也不会生效。
三、日志体系详解：access.log 逐行解剖
3.1 落盘位置与 journald 的分工
应用日志写在工作目录下的 data/state/log/access.log（实测该目录仅有这一个文件）：
$ ls -la /opt/filestash/data/state/log/
-rwxr-xr-x 1 filestash filestash 3908 Oct 22 04:55 access.log
systemd 托管下 stdout 进了 journald，但实测 journald 里只有单元级事件，应用运行日志不会进 journald：
$ journalctl -u filestash --no-pager -o cat | tail -3
Started Filestash web file manager.
排障口径：查应用行为看 access.log，查启停事件看 journalctl -u filestash。 另外 access.log 实测为单文件追加，未见按天/按大小滚动，生产环境建议由日志采集器（或 logrotate 配合 copytruncate）接管长期留存。
3.2 四类日志行
第一类：SYST 系统行（启动、组件状态）。启动三连是判断进程是否正常起监听的标志：
2026/10/22 04:44:21 SYST WARN plg_video_transcoder: "ffmpeg" not found in $PATH, transcoding disabled
2026/10/22 04:44:21 SYST INFO [http] starting ...
2026/10/22 04:44:21 SYST INFO [http] listening on :8334
第一行是环境缺失告警（未装 ffmpeg，视频转码自动禁用），不是故障。
第二类：HTTP 请求行（每个请求一条）。字段依次为：时间、HTTP 标记、状态码、方法、耗时（毫秒）、路径与查询串，DEBUG 级别下还会追加 trace=<32位随机串>：
2026/10/22 04:44:24 HTTP 200 GET 0.5ms /healthz
2026/10/22 04:44:34 HTTP 200 POST 120.9ms /api/session
2026/10/22 04:50:14 HTTP 403 GET 0.0ms /admin/api/config
2026/10/22 04:53:49 HTTP 404 POST 0.0ms /api/files/share?path=/srv/share/docs/
2026/10/22 04:55:07 HTTP 409 POST 0.4ms /api/files/mkdir?path=/srv/share/
2026/10/22 04:59:46 HTTP 200 GET 0.1ms /api/config trace=krSKhWAgKa3XvhCjPRvB1dAmLsfxGKk1
耗时分布有两条经验线：/admin/api/session 稳定在 ~1.5 秒（bcrypt 口令校验成本，正常）；普通接口在毫秒级，出现秒级耗时即需要关注后端存储。
第三类：AUDIT 审计行（见第四节）。
第四类：SYST DEBUG 行（仅 DEBUG 级别，中间件内部错误细节）。排障时最有价值，例如会话失效时的根因、zip 构建超时的原因（见 6.2）：
2026/10/22 04:52:42 SYST DEBUG middleware::session::start action=extractBackend error="Not Allowed"
2026/10/22 05:18:50 SYST DEBUG downloader::timeout zip not completed due to timeout
3.3 log.level 对日志的影响（trace 机制）
配置参数 log.level 从 INFO 切到 DEBUG 后，两个可观测变化（实测）：① 每个请求行追加 trace= 串——同一请求的异常行与请求行共享同一 trace，可串联定位；② 出现 SYST DEBUG 内部错误行。排查完把 log.level 提交回 null 即还原 INFO（还原方法见配置篇 8.3/第九节）。
3.4 实用排查命令
## 实时跟踪
$ tail -f /opt/filestash/data/state/log/access.log
## 只看错误与审计
$ grep -E 'HTTP (4|5)|AUDIT|WARN|ERROR' /opt/filestash/data/state/log/access.log
## 用 trace 串起一次请求的完整链路
$ grep 'trace=L15bXRBZ3RM2JYPTPItq5N98IMzMz08v' /opt/filestash/data/state/log/access.log
## 统计各状态码数量
$ grep -oE 'HTTP [0-9]{3}' /opt/filestash/data/state/log/access.log | sort | uniq -c
四、审计日志（AUDIT）的能力边界
AUDIT 行格式：AUDIT action[动作] backend[后端类型] user[账号] target[来源地址]。实测一天内累计 9 条，全部是登录事件：
2026/10/22 04:44:34 AUDIT action[login] backend[sftp] user[root] target[127.0.0.1]
2026/10/22 04:44:34 AUDIT action[login] backend[webdav] user[admin] target[127.0.0.1]
2026/10/22 04:52:42 AUDIT action[login] backend[sftp] user[root] target[127.0.0.1]
两点能力边界（实测确认）：
- 文件操作不产生 AUDIT 行——上传、下载、删除只有 HTTP 请求行（路径含在 URL 里，可间接还原操作轨迹）。
- 共享链接的创建/删除不产生 AUDIT 行，管理配置修改（POST /admin/api/config）也只有 HTTP 行。
合规要求较高的场景，需要把 HTTP 行中的敏感路径一并采集，且共享链接管理建议定期用 GET /api/share?path= 盘点（见第八节）。
五、会话与认证 API
5.1 用户会话：POST /api/session
用户会话通过存储后端凭据建立。以 SFTP 为例，响应体结构（实测）：
$ curl -s -c /tmp/fs.cookie -H 'X-Requested-With: XmlHttpRequest' -H 'Content-Type: application/json' \
-d '{"type":"sftp","hostname":"10.89.57.3","username":"root","password":"q1w2e3r4"}' \
http://127.0.0.1:8334/api/session
{"status": "ok", "result": {"home": "/root/", "is_authenticated": true,
"backendID": "kdzdebOcMwcQbqdAc1cU", "authorization": "<Bearer 令牌>"}}
四个返回字段：home 是后端给的起始目录（SFTP 登录用户家目录）；is_authenticated 认证结果；backendID 本次会话绑定的后端实例 ID；authorization 即后续 API 用的 Bearer 令牌。同时响应会种下一个名为 auth 的会话 Cookie（实测 Cookie 名）。
5.2 双通道：Bearer（API）与 Cookie（浏览器导航）
脚本调 API 用 Bearer 令牌（Authorization: Bearer <token>）；浏览器直接导航的下载链接靠 Cookie 会话。这个区别在打包下载接口上影响极大——前端就是个普通 <a href> 链接，浏览器不带 Authorization 头（实测复盘见 6.2）。管理会话同理：POST /admin/api/session（密码登录，~1.5 秒 bcrypt 校验）+ Cookie 访问 /admin/api/config。
5.3 认证失败的表现
凭据错误或会话失效时，业务接口返回 401 {"status": "error", "message": "Not authorised"}；未建管理会话访问 /admin/api/config 返回 403；连接列表被清空等"会话找不到后端"的场景返回 403 且 DEBUG 日志出现 middleware::session::start action=extractBackend error="Not Allowed"。
六、文件操作 API 全集
6.1 已验证操作一览
前缀统一为 /api/files/，均需 Bearer 令牌与 X-Requested-With: XmlHttpRequest 头。path 参数放查询串，写操作用对应方法：
| 操作 | 方法与路径 | 实测结果 |
|---|---|---|
| 列目录 | GET /api/files/ls?path=<目录> | 200，results 数组含 name/type/size/time/metadata（权限位、属主等） |
| 下载/读文件 | GET /api/files/cat?path=<文件> | 200，响应体即文件内容（二进制安全） |
| 建空文件 | POST /api/files/touch?path=<文件> | 200 {"status":"ok"}，ls 复核文件出现 |
| 建目录 | POST /api/files/mkdir?path=<目录> | 200；目录已存在时 409 Failure |
| 重命名/移动 | POST /api/files/mv?from=<旧>&to=<新> | 200（安装篇已实测） |
| 删除 | POST /api/files/rm?path=<路径> | 200 {"status":"ok"}，删除点开头文件同样有效 |
| 上传 | POST /api/files/cat?path=<文件>（body 为文件内容） | 200（安装篇已实测，2MB 二进制校验一致） |
| 打包下载 | GET /api/files/zip?path=<路径> | 见 6.2：本构建实测不可用 |
| 搜索 | GET /api/files/search?path=<目录>&q=<关键词> | 见 6.3：默认配置下恒空 |
| 目录监听 | GET /api/files/watch?path=<目录> | 未实测（SSE 流式接口，前端用于目录变更推送） |
ls 结果里的点开头文件始终返回（实测 display_hidden=false 时 .c1hidden.txt 也在 results 中）——是否展示由前端依据 display_hidden 配置决定，服务端接口不过滤。
6.2 zip 打包下载：端点用法与实测结论
前端对 zip 的调用方式（从 assets/<commit>/pages/filespage/ctrl_submenu.js 提取）：多选打包时按 path=<p1>&path=<p2>... 逐项传参，单选文件时直接走 api/files/cat；单选目录时 path=<目录> 并把响应存为 <目录名>.zip：
let href = "api/files/zip?";
href += selections.map(({ path }) => "path=" + encodeURIComponent(path)).join("&");
实测（SFTP 与 WebDAV 双后端、Bearer/Cookie 两种认证、多 path/单文件/共享会话共 8 种组合、3 次重试）全部返回200 + 22 字节空压缩包：
$ curl -s -D- -o /tmp/d1.zip -H 'X-Requested-With: XmlHttpRequest' \
-H "Authorization: Bearer <SFTP会话令牌>" \
'http://127.0.0.1:8334/api/files/zip?path=/srv/share/docs/'
HTTP/1.1 200 OK
Content-Disposition: attachment; filename="docs.zip"
Content-Type: application/zip
X-Request-Id: KlyFasgWo3rZxqDqD9N9iHQkYJb6Leip
...
$ ls -l /tmp/d1.zip
22 /tmp/d1.zip ## 空zip：仅一个 EOCD 结束标记
把 log.level 切到 DEBUG 后抓到根因日志：
2026/10/22 05:18:50 SYST DEBUG downloader::timeout zip not completed due to timeout
2026/10/22 05:18:50 HTTP 200 GET 0.2ms /api/files/zip?path=/srv/share/docs/ trace=L15bXRBZ3RM2JYPTPItq5N98IMzMz08v
即服务端的 zip 构建器在极短的内部时限内未完成打包就终结了响应（用户会话下 0.1~0.2ms 即返回；共享会话下 116.5ms 后仍为空包）。响应头 Content-Disposition: filename="docs.zip" 说明处理器确实解析了 path 参数并推导了文件名，不是路由问题。进程环境变量中亦无相关超时开关（实测仅 8 个环境变量，无一与 timeout/zip 相关）。
结论与建议：v0.6.20261022 构建下，zip 打包下载开箱即不可用（双后端一致），属该构建的实测边界；单文件下载用 /api/files/cat 完全正常。需要打包下载能力时，先用本文的 curl 序列验证目标构建是否修复，再决定是否引入；临时替代方案是在客户端循环 cat 多文件。
6.3 search 搜索：默认配置下恒空
GET /api/files/search?path=<目录>&q=<关键词> 在默认配置下对所有实测关键词（hello、hello.txt、sample.bin，分别命中文件名与文件内容）返回空结果：
$ curl -s -H "Authorization: Bearer <SFTP会话令牌>" \
'http://127.0.0.1:8334/api/files/search?path=/srv/share/&q=hello'
{"status": "ok", "results": []}
$ ls -la /opt/filestash/data/state/search/
## 目录为空：无任何索引文件
/about 清单里 plg_search_stateless 插件存在、/api/config 里 enable_search: true，但 data/state/search/ 索引目录实测为空——即索引从未构建。生产启用搜索前必须先验证索引构建链路，不能默认可用；配置项 features.search.explore_timeout（默认 1500ms）控制的递归探索路径在本次实测中未产生结果。
七、存储后端 API：GET /api/backend 与 22 个连接表单
GET /api/backend（需 Bearer 令牌）返回全部存储驱动的连接表单 Schema——后台"添加连接"页就是拿它渲染的。实测 22 个驱动，每个表单含隐藏的 type 字段与若干明文字段（advanced 开关用 target 联动折叠高级项）：
| 驱动 | 表单字段（* 为关键项） |
|---|---|
| sftp | hostname*、username、password；advanced：path、port、passphrase、hostkey |
| webdav | url*、username、password；advanced：path |
| s3 | access_key_id*、secret_access_key*；advanced：region、endpoint、role_arn、session_token、path、encryption_key、number_thread、timeout |
| ftp | hostname*、username、password；advanced：path、port、conn（连接数） |
| samba | host、username、password；advanced：path、port（如 445）、domain、share |
| nfs | hostname、target（Mount Path）；advanced：uid、gid、gids、machine_name、path（Chroot） |
| local | password（Admin Password）、path |
| git | repo*、username、password；advanced：path、passphrase、commit（提交信息模板）、branch、author_email/author_name、committer_email/committer_name |
| ldap | hostname、bind_dn、bind_password、base_dn；advanced：path、port |
| mysql | host、username、password、port |
| psql | host、port、user、password、dbname、sslmode |
| artifactory | instance（URL）、token、path |
| backblaze | username（KeyID）、password（applicationKey） |
| storj | access-grant |
| perkeep | url（如 http://localhost:3179） |
| dropbox | oauth2（只读，回调 /api/session/auth/dropbox） |
| gdrive | oauth2（只读，回调 /api/session/auth/gdrive） |
| caldav / carddav | url、username、password |
| blackhole | （无字段，空实现） |
| tmp | userID |
| url | url、insecure（开关） |
两个对照事实：/api/backend 给出 22 个表单；/about 插件清单为 21 个 plg_backend_*（22 与 21 的差异源于个别插件注册多个连接类型，两组清单本文均如实列出）。OAuth2 类（dropbox/gdrive）需要先在官方渠道配置回调凭据才能使用。SFTP/WebDAV 两个表单的完整连通性实测（含上传下载闭环）见安装篇第八节。
八、共享链接 API 实操全流程
共享功能四件套（方法与路径均在 v0.6.20261022 实测确认；老资料里的 POST /api/files/share 在本构建为 404）：
| 操作 | 方法与路径 | 说明 |
|---|---|---|
| 创建/更新 | PUT /api/share/<ID> | ID 自定义（前端用 7 位随机串）；body：{"path": "...", "can_read": true, "can_write": false, "can_upload": false}，可选 url/password/expire/users |
| 列表 | GET /api/share?path=<路径> | 返回该路径下的共享对象数组 |
| 口令验证 | POST /api/share/<ID>/proof | 无口令共享传空 body {}；验证通过种下 proof Cookie 并回显共享对象 |
| 穿越访问 | GET /api/files/ls?path=<相对路径>&share=<ID> | 带 proof Cookie + share 参数，对共享内容做文件操作 |
| 删除 | DELETE /api/share/<ID> | {"status": "ok"} |
8.1 创建共享
$ curl -s -X PUT -H 'X-Requested-With: XmlHttpRequest' -H 'Content-Type: application/json' \
-H "Authorization: Bearer <SFTP会话令牌>" \
-d '{"path": "/srv/share/docs/", "can_read": true, "can_write": false, "can_upload": false}' \
"http://127.0.0.1:8334/api/share/d1sh001"
{"status": "ok"}
$ curl -s -H "Authorization: Bearer <SFTP会话令牌>" \
"http://127.0.0.1:8334/api/share?path=/srv/share/docs/"
{"status": "ok", "results": [{"id": "d1sh001", "path": "/", "can_read": true, "can_write": false, "can_upload": false}]}
注意列表返回的 path 是相对共享根的路径（共享 /srv/share/docs/ 时显示 /）——共享对象以被共享目录为根。三个 can_* 布尔位对应前端三种角色：viewer（只读）、uploader（只传）、editor（读写传全开）。
8.2 访问共享：proof 验证 + share 参数
访问方（无需 Filestash 账号）先做 proof 验证拿到 Cookie，再通过 ?share= 参数穿越访问：
## 1. 无口令共享的 proof 验证（带口令时 body 传 {"password": "..."}）
$ curl -s -c /tmp/share.cookie -H 'X-Requested-With: XmlHttpRequest' -H 'Content-Type: application/json' \
-d '{}' http://127.0.0.1:8334/api/share/d1sh001/proof
{"status": "ok", "result": {"id": "d1sh001", "path": "/", "can_read": true, "can_write": false, "can_upload": false}}
## 2. 列共享目录（proof Cookie + share 参数，path 相对共享根）
$ curl -s -b /tmp/share.cookie -H 'X-Requested-With: XmlHttpRequest' \
'http://127.0.0.1:8334/api/files/ls?path=/&share=d1sh001'
{"status": "ok", "results": [{"name": "hello.txt", "type": "file", "size": 24, "time": 1792641827000, "metadata": {...}]}
## 3. 读取共享文件
$ curl -s -b /tmp/share.cookie -H 'X-Requested-With: XmlHttpRequest' \
'http://127.0.0.1:8334/api/files/cat?path=/hello.txt&share=d1sh001'
hello from sftp backend
权限位说明：三个 can_* 布尔位对应前端三种角色——viewer（can_read）、uploader（can_upload）、editor（三者全开）。本次实测通过共享会话完成了目录列举与文件读取的穿越访问闭环；/s/<ID> 落地页对任意访问者返回 200（页面壳，口令/邮件验证流程由前端 JS 经 proof 接口驱动）。测试完删除：
$ curl -s -X DELETE -H "Authorization: Bearer <SFTP会话令牌>" http://127.0.0.1:8334/api/share/d1sh001
{"status": "ok"}
盘点命令（共享只在创建时校验路径，长期运行建议周期性列出核对）：对关键目录逐个 GET /api/share?path= 核对清单，发现未知共享立即 DELETE。另注意配置篇 8.4 的实测结论：features.share.enable=false 只隐藏前端入口，本节 API 不受其拦截。
九、管理控制台与 /admin/tty/
配置项 features.server.console_enable（默认 false）控制内置交互式控制台，开启后位于 /admin/tty/（用户名 admin、密码同管理后台）。实测开关行为：
>>> admin_post({"features.server.console_enable": True})
(200, {'status': 'ok'})
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8334/admin/tty/
200 ## 页面标题 "Admin Console"
>>> admin_post({"features.server.console_enable": None})
(200, {'status': 'ok'})
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8334/admin/tty/
200 ## 页面壳仍返回 200
两点提醒：① 控制台是 Web 终端，权限等同于运行进程的系统账号（filestash），默认关闭是对的，开启期间要控制网络暴露面；② 实测关闭开关后 /admin/tty/ 路由仍返回 200 页面壳，如需彻底封禁建议在反向代理层拦截 /admin/tty/ 路径。
十、运维速查表
| 目标 | 命令/端点 |
|---|---|
| 服务状态 | systemctl status filestash；ss -tlnp | grep 8334 |
| 健康探针 | curl -s http://127.0.0.1:8334/healthz（pass / transcient） |
| 版本与构建 | curl -s http://127.0.0.1:8334/about（commit/config hash/插件清单）；响应头 X-Powered-By |
| 配置指纹比对 | /about 的 Config hash（配置变更即变） |
| 应用日志 | tail -f /opt/filestash/data/state/log/access.log；grep -E 'HTTP (4|5)|AUDIT' |
| 启停事件 | journalctl -u filestash |
| 排障提详 | 管理后台把 log.level 置 DEBUG（trace 串联 + SYST DEBUG 行），完事还原 null |
| 用户会话 | POST /api/session（后端凭据）→ Bearer 令牌 |
| 管理会话 | POST /admin/api/session（管理口令）→ Cookie |
| 后端清单 | GET /api/backend（22 个连接表单 Schema） |
| 共享盘点 | GET /api/share?path=<目录> / DELETE /api/share/<ID> |
| 文件操作 | /api/files/：ls、cat、touch、mkdir、mv、rm（zip 与 search 见第六节边界说明） |
至此 Filestash 专栏四篇闭环：选型认知（A1）→ 部署安装（B1）→ 配置体系（C1）→ 运维与 API（本篇）。四篇中的全部命令都在同一套真实服务器上实测取证，版本基线为 v0.6.20261022（2026-10-22）；Filestash 为滚动发布形态，后续版本使用本文命令前建议先复核第六节的两个接口边界（zip/search）是否仍有同类行为。