Filestash 如何接入 Syncthing 后端以只读方式浏览同步文件夹
【免费下载链接】filestash:file_folder: Universal File Storage Client项目地址: https://gitcode.com/GitHub_Trending/fi/filestash
Filestash 的存储后端列表里内置了一个 Syncthing 插件（server/plugin/plg_backend_syncthing/index.go）。它的用途不是"管理 Syncthing"，而是把你的 Syncthing 同步文件夹以只读方式挂进 Filestash 的文件浏览器：根目录列出 Syncthing 的全部同步文件夹，文件夹内可以浏览、查看文件元信息并在线读取内容，但不能新建、上传、重命名、移动或删除。这篇文档说明如何完成这个接入，以及"纯 API 浏览"和"经本地同步目录读取文件"两种模式的区别。
接入前先确认什么
Syncthing 后端初始化时会立即调用一次 Syncthing REST API 拉取文件夹列表（见 index_helper.go 中的fetchFolders，请求/rest/config接口，并使用X-Api-Key请求头）。任何一步不满足，保存连接时就会直接报错，不会等到浏览时才发现：
- Filestash 能访问到的 Syncthing 服务地址。后端表单的
url留空时默认是http://localhost:8384（Syncthing REST API 的默认端口，即 README 中示例容器映射的 8384 端口）。 - 一个可访问 REST API 的 Syncthing API key，填入表单的
api_key字段。 - Syncthing 实例中已存在至少一个同步文件夹（folder），否则 Filestash 根目录只会列出一个空列表。
- 如果需要在线查看文件内容（下载、图片预览等），还需要 Filestash 进程能够以只读方式访问 Syncthing 的本地同步目录，通过
sync_path字段指定该目录（详见下一节）。
插件自带 README 给出了一个可参考的测试实例（server/plugin/plg_backend_syncthing/README.md，其中的./syncthing/config与./syncthing/sync是文档示例中的本地挂载路径）：
docker run --name=syncthing-sync -d -e PUID=1000 -e PGID=1000 -p 8384:8384 -v ./syncthing/config:/var/syncthing -v ./syncthing/sync:/sync syncthing/syncthing这条命令会启动一个容器并把 Syncthing 的 REST 端口 8384 暴露到宿主机。副作用是创建一个名为syncthing-sync的容器并在当前目录生成./syncthing数据目录；如果你已有自己的 Syncthing 实例，跳过这一步，直接把 API 地址指向现有实例即可。
在 Filestash 中配置 syncthing 存储后端
- 访问 Filestash 的管理端（
/admin），进入存储后端（Storage Backend）设置页。该页面渲染可用后端列表与已启用后端的表单（前端逻辑见 ctrl_storage_component_backend.js），点击syncthing项即把它加入已启用后端。 - 在展开的表单中填写三个字段——这是 LoginForm() 定义的全部内容：
| 字段 | 占位提示 | 用途 |
|---|---|---|
url | Address | Syncthing REST API 地址，留空默认http://localhost:8384 |
api_key | API Key | Syncthing API key，用于X-Api-Key请求头 |
sync_path | Sync directory | Syncthing 同步目录在 Filestash 所在主机上的路径，可留空 |
- 填写后保存配置。保存动作会触发后端
Init()，此时 Filestash 立刻用上面的地址和 key 请求/rest/config；如果 API 返回非 200 状态，会以API returned status <code>的形式报错，此时应核对地址与 key，而不是先尝试浏览。
两种浏览模式的区别
sync_path是否为空，决定了文件内容从哪来：
- 不填
sync_path（纯 API 模式）：目录列表通过 Syncthing 的/rest/db/browse接口（参数folder、prefix、levels=1）从 Syncthing 数据库获取，因此文件夹结构、文件名、大小、修改时间都可以看到；但文件会被标记为 Offline，不能在线读取内容。适合只需要在 Filestash 里核对"同步了什么"的场景。 - 填写
sync_path（本地目录模式）：列表仍然来自 Syncthing API，但Stat/Cat等操作改为把路径解析为sync_path+ 文件夹的path（来自/rest/config返回的folders[].path）+ 相对路径，直接以只读方式（os.O_RDONLY）打开本地文件（见 index.go 中的Stat/Cat）。此时文件可正常下载、预览。sync_path下找不到对应目录时会返回文件不存在之类的打开错误。
根目录（/）下只列出同步文件夹本身（每个文件夹显示为一个 directory），不显示sync_path下其他内容。
验证接入是否生效
按以下顺序核对，每一步都能直接落到文档或代码里的事实：
- API 连通：保存后端配置时没有报
API returned status ...错误，说明url与api_key已被 Syncthing 接受（/rest/config返回 200）。 - 根目录：进入 Filestash 的文件页（该后端对应的目录），应看到与 Syncthing 端配置一致的文件夹列表，名字取
label，label为空时回退为id。 - 进入文件夹：列出的文件/子目录、大小与修改时间来自
/rest/db/browse的结果；只识别FILE_INFO_TYPE_FILE和FILE_INFO_TYPE_DIRECTORY两种类型，其他类型会记录错误日志plg_backend_syncthing::ls error=unknownItemType。 - 只读行为：无论是否填
sync_path，Filestash 根目录的元数据都被显式设置为不可建目录、不可建文件、不可重命名、不可移动、不可上传、不可删除（Meta() 中对path == "/"的分支）。在界面上看不到或执行不了写操作，即为预期结果，这不是配置遗漏。 - 内容读取：仅当填写了
sync_path时，点开一个已知文件应能查看/下载；未填写时文件显示为 Offline 属预期行为。
限制与边界
- 该后端不提供 Syncthing 管理功能。如果你想在 Filestash 域名下代理 Syncthing 自己的管理界面，那是另一个独立插件（server/plugin/plg_handler_syncthing/index.go），通过
features.syncthing.enable/SYNCTHING_URL启用后把 Syncthing Web UI 反向代理到/admin/syncthing，与本文的存储后端接入互不依赖，按需启用即可。 - 接入成功与否完全取决于 Syncthing REST 端点的可达性与 key 有效性；文档没有给出 Syncthing 侧需要额外开启的开关，若连接失败，按"地址 → key → 实例中是否已有 folder"的顺序核对即可。
- 只读约束由该后端自身强制（元数据层面禁用全部写操作），不需要再叠加额外的授权插件。
【免费下载链接】filestash:file_folder: Universal File Storage Client项目地址: https://gitcode.com/GitHub_Trending/fi/filestash
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
