Syncthing 2.1.1：修复运行中 REST 升级问题，你的 P2P 文件同步更稳了

预计阅读时间：8 分钟

Syncthing 是一款开源的连续文件同步工具，核心思路很简单：数据直接从一台机器传到另一台，不经过任何云端中转。这意味着你不需要把文件交给第三方服务器，同步过程全程加密，只有你自己的设备能解密。2.1.1 版本虽然是个小版本，但修了一个实际部署中容易踩的坑——在 Syncthing 运行期间通过 REST API 触发升级，之前的行为并不正确。

修了什么

这次更新集中在两个修复：

REST 升级修复（#10699，对应 issue #10697）：当 Syncthing 已经在运行时，通过 REST API 发起升级请求，旧版本的处理流程有缺陷，可能导致升级不完整或状态不一致。2.1.1 修正了这个升级路径，确保运行中的实例能被正确替换。
Versioner 修复：文件版本管理器（versioner）在特定场景下行为异常，具体细节虽未在公告中展开，但如果你用了 simple 或 staggered 版本保留策略，建议尽快更新。

这两个修复都不涉及功能变更，但第一个尤其重要——很多运维脚本和自动化工具正是通过 REST API 来管理 Syncthing 的，升级流程出错意味着下次重启可能版本回退或配置丢失。

实际部署中 REST 升级怎么用

Syncthing 提供了一套完整的 REST API，升级只是其中一个端点。下面是一个完整的实操示例：安装、配置、并通过 API 触发升级检查。

安装与启动

# Linux 下载最新版（以 x86_64 为例）
curl -L https://github.com/syncthing/syncthing/releases/download/v2.1.1/syncthing-linux-amd64-v2.1.1.tar.gz -o syncthing.tar.gz
tar -xzf syncthing.tar.gz
sudo mv syncthing-linux-amd64-v2.1.1/syncthing /usr/local/bin/

# 启动（首次运行会生成配置和设备 ID）
syncthing -no-browser

# 配置文件位置：~/.local/state/syncthing/config.xml
# GUI 默认监听 127.0.0.1:8384

启动后浏览器打开 http://127.0.0.1:8384 就能看到 Web UI。如果你在远程服务器上跑，可以临时改成 0.0.0.0:8384，但务必设置用户名密码。

通过 REST API 检查和触发升级

Syncthing 的 API 需要 API Key，它在配置文件里自动生成，也可以在 Web UI 的 Actions → API Key 里查看。

# 从配置文件提取 API Key（xmlstarlet 需单独安装，也可手动查看）
API_KEY=$(xmlstarlet sel -t -v "//gui/apiKey" ~/.local/state/syncthing/config.xml)

# 查看当前版本
curl -s -H "X-API-Key: $API_KEY" http://127.0.0.1:8384/rest/system/status | python3 -m json.tool | grep version

# 检查是否有新版本可用
curl -s -H "X-API-Key: $API_KEY" http://127.0.0.1:8384/rest/system/upgrade | python3 -m json.tool

# 触发升级（这就是 2.1.1 修复的操作——运行中直接升级）
curl -X POST -H "X-API-Key: $API_KEY" http://127.0.0.1:8384/rest/system/upgrade

在 2.1.1 之前，最后一步 POST /rest/system/upgrade 在某些情况下升级流程不完整，可能导致二进制替换后旧进程仍在运行。修复后，升级流程会正确处理进程替换和重启。

添加远程设备并共享文件夹

REST API 也能完成日常配置，比如添加另一台设备：

# 假设远程设备的 ID 为 DEVICE-ID-HERE
curl -X POST -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": [{
      "deviceID": "DEVICE-ID-HERE",
      "name": "remote-laptop",
      "addresses": ["dynamic", "tcp://192.168.1.50:22000"]
    }]
  }' \
  http://127.0.0.1:8384/rest/config/devices

# 共享一个文件夹给该设备
curl -X PATCH -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sharedWithDevices": ["DEVICE-ID-HERE"]
  }' \
  "http://127.0.0.1:8384/rest/config/folders/default"

两台设备互相确认后，文件就会开始 P2P 同步，数据不经过任何中间服务器。

文件版本保留：Versioner 的实际配置

这次修复涉及的 versioner 是 Syncthing 的一个实用功能——当文件被远程修改覆盖时，旧版本不会直接消失，而是按策略保留。配置写在 config.xml 里，也可以通过 API 设置。

<!-- 在文件夹配置中添加 staggered 版本保留 -->
<folder id="default" path="/home/user/Sync" type="sendreceive">
  <versioning type="staggered">
    <param key="cleanInterval" val="3600"/>
    <param key="maxAge" val="31536000"/>
  </versioning>
</folder>

staggered 策略的意思是：刚被替换的文件保留时间短（几分钟内），越老的版本保留时间越长，最长不超过 maxAge（这里设了 365 天）。这比 simple 策略（只保留最近 N 个版本）更节省磁盘，同时关键历史版本不会丢。

2.1.1 修了 versioner 的一个异常行为，如果你在用 staggered 或 trashcan 版本策略，更新后旧文件保留逻辑会更可靠。

升级建议和注意事项

如果你用自动化脚本管理 Syncthing：2.1.1 是必升版本，REST 升级修复直接影响你的运维流程。升级本身就可以用上面那条 POST /rest/system/upgrade 完成，升级完重启即可。
如果你只用 Web UI 手动升级：影响较小，但 versioner 修复仍然值得更新。
升级前备份配置：cp ~/.local/state/syncthing/config.xml ~/.local/state/syncthing/config.xml.bak，以防万一。
多设备场景：Syncthing 版本不需要所有设备完全一致，但大版本差异可能导致协议不兼容。建议逐台升级，先升一台观察同步状态正常后再升其余。
安全提醒：REST API 默认只监听 localhost，不要为了方便把它暴露到公网。如果需要远程管理，走 SSH 隧道或 VPN 更安全。

Syncthing 的核心价值在于"数据只在你的设备之间流动"，2.1.1 让这个流程中一个关键运维操作变得更可靠。版本虽小，但修的是真实场景中的真实问题。