在 Syncthing 版本历史中查找当前缺失的文件

先确认这份历史符合你的需要

请使用已经保存了相关版本的设备。Syncthing 的文件版本控制需要在每台设备上，针对每个文件夹分别配置。它会在收到其他设备传来的变更时归档受影响的文件；在本设备上直接进行的编辑或删除，不会被本设备的版本控制记录下来。

还要考虑版本保留策略。历史版本可能已经过期，也可能已按所选策略被精简或替换。现在才启用版本控制，无法重新生成那些早先的副本。本次核查只涵盖所选实例仍能返回的条目，因此空报告不能证明文件从未被删除过。

这里的月份指版本进入归档的时间。某个文件可能在一次较早的编辑后留下归档版本，过了很久才消失。无论归档时间还是此前的修改时间，都不能说明它的当前路径何时消失。

核对实例、文件夹 ID 和当前文件夹

运行辅助脚本的机器和文件系统环境，必须与所查询的 Syncthing 实例相同。在该实例的网页界面中，找到文件夹 ID 及其配置路径。ID 不一定等于界面显示的文件夹名称。--root 应传入当前使用的文件夹，而不是其中的 .stversions 目录。

确认所需存储已经挂载且可读，也要检查文件夹内部的独立挂载点。在每个相关位置打开一个你熟悉的文件。驱动器断开后，原挂载点可能只剩一个空目录；路径字符串相同，并不能证明预期的存储仍然在位。

辅助脚本要求使用与配置相符的绝对根路径，以及 Syncthing 的 basic 文件系统。根目录及其所有上级目录都必须是真实目录，不能是符号链接。如果配置路径使用 ~，运行脚本时应采用与 Syncthing 相同的账户及主目录映射。容器内路径与宿主机上的绑定挂载路径不能互换；匹配失败时，应修正运行环境或路径。

选定一个工作目录，并在所有同步文件夹之外的现有目录中，为输出指定一个尚不存在的文件名。辅助脚本只检查指定的根目录，不会遍历你同步的其他文件夹。保持 Syncthing 运行，以便访问 API，并等编辑、移动和同步活动平稳下来再操作。结果反映运行期间的观察，并非同一瞬间取得的原子快照。

保存并检查辅助脚本

请在使用普通 basic 文件系统的 POSIX 系统上，使用 Python 3.12 或更高版本。用纯文本编辑器将下面完整的一行保存为 unpack_audit.py，放在选定的工作目录中。这一行包含辅助脚本源码及完整性校验；不要把这行 Python 代码直接粘贴到 Bash 中。运行前，先执行 python3 --version 检查版本；辅助脚本会在处理文件夹或访问 API 之前拒绝旧版 Python。

import base64,zlib,hashlib,sys; from pathlib import Path; data=zlib.decompress(base64.b64decode('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',validate=True)); f=Path('audit.py').open('xb') if hashlib.sha256(data).hexdigest()=='71717f0699b0ab624944f1d8746eafff0d34f08f3cde079e98278112ed51d139' else sys.exit('SHA-256 mismatch; no helper file written'); f.write(data); f.close(); print('Created audit.py for inspection; it has not been run.')

在该目录中运行以下命令，生成可直接阅读的辅助脚本：

python3 unpack_audit.py

解包程序会校验 SHA-256，并且只有在 audit.py 尚不存在时才创建它。它不会运行还原出的辅助脚本。生成的 audit.py 应为 16,912 字节，SHA-256 必须是 71717f0699b0ab624944f1d8746eafff0d34f08f3cde079e98278112ed51d139。提供 API 密钥之前，先用文本编辑器打开它，检查代码。

核查脚本会读取文件夹配置和保留版本，再检查磁盘上的当前路径。新生成的 HTML 文件包含完整的报告 JSON，不需要网络资源，也不需要执行 JavaScript。它不会恢复文件或修改已同步的内容。如果报告中的路径会暴露个人信息，请妥善保存，不要随意分享。

设置 API 密钥，避免写入命令历史

从这个本地实例的 GUI 设置中复制 API 密钥。它是访问 API 的凭据，不要把它写进命令本身、截图或报告。在 Bash 中执行下面的命令，然后在不回显的提示处输入密钥；这些命令只会将密钥保存在当前 shell 的环境变量中。

read -r -s -p 'Syncthing API key: ' SYNCTHING_API_KEY && export SYNCTHING_API_KEY

默认连接地址是 http://127.0.0.1:8384。如果同一本地实例使用其他端口或可信的 HTTPS 地址，可添加 --url 并填写该实例的直接地址。含凭据或路径前缀的 URL 会被拒绝；脚本不会跟随重定向，也不会使用环境变量指定的代理。API 实例与待检查文件夹必须位于同一台机器上。

核查一个 UTC 自然月

将示例中的文件夹 ID 和绝对路径换成你自己的值，并选用新的输出文件名。此示例查询 2026 年 9 月，包含归档时间等于或晚于 2026-09-01T00:00:00Z、且早于 2026-10-01T00:00:00Z 的版本。

python3 audit.py --folder 'YOUR-FOLDER-ID' --root '/absolute/path/to/Sync' --month 2026-09 --output '/absolute/path/outside/Sync/report-2026-09.html'

带时区偏移的时间戳会先换算成 UTC 再比较。例如，2026-09-01T01:00:00+01:00 恰好对应本报告中 9 月的起点。因此，接近月界时，本地日历日期可能与 UTC 日期不同；判断该核查哪个月时，请以报告显示的 UTC 区间为准。

成功时，命令以退出码 0 结束，并输出一小段包含 status: written 和 counts 的 JSON 信息。用浏览器在本地打开新生成的 HTML 文件。报错不等于结果为空。完成后，用下面的命令清除当前 shell 中的凭据；如果需要再次运行，请重新在不回显的提示处输入密钥。

unset SYNCTHING_API_KEY

分别查看缺失路径和无法确定的结果

先核对报告中的文件夹和月份，再按时间顺序查看缺失条目。每条记录对应一个归档版本，表示检查时它的原相对路径不存在。在认定文件意外丢失之前，先到当前文件夹中查找是否有改名或移动后的副本。

表格会分别统计去重后的路径数和保留版本数。同一缺失路径出现两行，表示一条路径、两个版本，并非两次删除。完整的报告 JSON 还包含当前存在的路径、原始 versionTime 和 modTime 值、换算后的 UTC 时间，以及 size、current_path_state 和 state_reason。

也要逐一查看 unknown 条目。路径不可读，或其上级路径无法按支持的方式解析时，不能据此判为缺失。请修复报告指出的访问或路径问题，再运行一次并生成新的报告。如果最终路径本身是符号链接，即使它指向的目标不可用，也会被视为路径存在；这不代表目标内容可用或完整。

missing 为零但仍有 unknown 条目，表示这些路径尚未查明。两者都为零，则表示此次成功检查在所选时间范围内返回的版本中，没有发现当前缺失的路径。这个结果不能说明已经过期的历史、另一台设备上的版本，或从未进入本归档的缺失文件。

先处理失败，再判断结果

遇到连接或身份验证错误时，确认本地实例正在运行、GUI 地址正确，并且密钥属于该实例。根路径不匹配时，应同时核对文件夹 ID 和配置路径。驱动器不可用或目录不可读时，先恢复访问；不要为了让检查继续，临时创建一个空目录来代替它。

响应格式错误、不支持的路径或时间戳，以及不符合预期的文件夹配置，都会使核查停止，而不是产生空列表。API 或根目录错误会以退出码 1 和具体错误信息结束；命令语法错误的退出码为 2。解决错误后，请选用新的输出文件名。已有报告会被保留。如果写入失败，可能留下一个不完整的新文件；重试前应检查或删除该文件，也可以另选文件名。

如果运行期间文件发生了变化，请等活动平稳后重新检查。对可疑条目采取操作之前，还应立即再核对一次。先前保存的报告无法告诉你，文件后来是否已经重新出现。

只恢复你已经确认需要的版本

确认某条路径缺失，并决定需要某个保留副本后，在 Syncthing 中为同一个文件夹打开 Restore Versions。使用 Filter by name 和 Filter by date 找到条目，核对路径及所选版本后，再使用 Restore。请将实际时间戳与报告对照；不要假定 GUI 的日期显示与报告采用相同的 UTC 月份边界。

在预期的当前路径检查恢复出的文件，并查看 Syncthing 是否报告恢复错误。恢复较旧版本之前，也要考虑该位置已有的内容。HTML 核查报告不会替你选中任何待恢复条目，也无法判断哪个归档副本才适合你当前的工作。

Restorething 已经能够检查原路径是否存在，并提供按日期选择、先模拟再恢复的功能，这一点应予以说明。本指南补充的是一个有明确范围的核查流程：取出一个 UTC 月份内返回的全部版本，检查路径当前是否缺失，生成按时间排序的 HTML，并明确列出无法确定的结果。你作出恢复选择后，仍可使用 Syncthing 原生恢复功能。

实际验证了哪些内容

本文提供的辅助脚本在 Python 3.12.14/Linux 上，使用本地 HTTP 测试服务器和真实临时文件，通过了 28 次命令行运行及 29 组断言。检查涵盖从 API 到 HTML 的完整流程、UTC 边界和纳秒级排序、去重路径数与版本数的区别、文件名转义、missing／present／unknown 路径分类，以及必须报错而不能伪装成空结果的失败情形。解包程序另通过了三个独立的子进程用例：准确还原源码且不执行、拒绝损坏的数据、保留已经存在的辅助脚本。

这些验证没有使用真实运行的 Syncthing 实例或原生恢复 GUI，也没有在 Windows 或 macOS 上运行。权限拒绝通过注入错误模拟，并未测试操作系统的访问控制规则。这些检查不能证明脚本可以防住并发的文件系统或挂载变化。报告无法确定路径消失的原因，无法区分移动与删除，也无法找回已过期的版本。