Syncthing 2.1.7 配置参数详解

Syncthing 2.1.7 配置体系详解：v2 新目录布局下的 config.xml 结构（v52 配置版本）、options/gui/folder/device 四大段逐项参数说明、四类文件版本控制实测、GUI/REST/配置文件三种修改通道与生产配置模板。

Syncthing备份恢复2026/10/22

Syncthing 2.1.7 配置参数详解

目标：吃透 Syncthing v2.1.7 的 config.xml 每一段参数含义、默认值与修改方式，并通过真实修改实验验证配置生效路径。全文配置内容与命令回显均在 Ubuntu 22.04.5 + Syncthing v2.1.7 环境实测取得。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Syncthing：v2.1.7 "Hafnium Hornet"（官方 apt 源 stable-v2 组件安装，安装过程见 《Ubuntu 22.04 安装 Syncthing 指南》）
  • 服务形态：systemd 模板服务 syncthing@root
  • 配置版本：<configuration version="52">（v2.1.7 首启生成的默认配置版本号，实测）
  • 演示拓扑：两台服务器已配对共享文件夹 sync-demo（配对过程见安装指南第九章）

二、前置条件

  1. Syncthing v2.1.7 已安装并以 syncthing@root 服务运行：
systemctl is-active syncthing@root

实测回显：

active
  1. 能访问配置目录（本章所有文件操作基于该目录）：
ls /root/.local/state/syncthing/

实测回显：

cert.pem  config.xml  config.xml.v0  https-cert.pem  https-key.pem  index-v2  key.pem  syncthing.lock

三、参数查看与修改方式

Syncthing 有三条配置修改通道，各有适用场景。先看官方目录布局：

syncthing paths

实测回显（输出节选，实测首尾）：

Configuration file:
        /root/.local/state/syncthing/config.xml

Device private key & certificate files:
        /root/.local/state/syncthing/key.pem
        /root/.local/state/syncthing/cert.pem

Database location:
        /root/.local/state/syncthing/index-v2

Log file:
        /root/.local/state/syncthing/syncthing.log

Default sync folder directory:
        /root/Sync

⚠️ v1→v2 目录变化：v2 把配置与数据库统一放在 ~/.local/state/syncthing/（XDG state 目录），v1 时代位于 ~/.config/syncthing/ 的 config.xml 与 ~/.local/share/syncthing/ 的索引库均已迁移；config.xml.v0 是 v2 首启时自动归档的旧格式副本（实测存在于目录中）。从 v1 升级时 Syncthing 会自动完成迁移。

3.1 通道一：Web GUI（适合人工操作）

浏览器访问 GUI（默认 http://127.0.0.1:8384，改绑远程访问见安装指南 8.4 节），「操作 → 设置」面板按四个标签组织，与 config.xml 的对应关系（实测 GUI 设置项与 REST config 字段一一映射）：

GUI 设置标签对应 config.xml 段典型项
常规 General<gui> + 部分 <options>设备名、GUI 管理账号密码、主题、语言
连接 Connections<options>同步协议监听地址、全局/本地发现开关、中继开关、NAT 穿透、带宽限制
默认 Defaults<defaults>新文件夹/新设备的默认参数模板
高级 Advanced全部原始 XML直接以 JSON 形式编辑所有配置项

3.2 通道二：REST API（适合脚本化管理）

所有配置经 /rest/config/... 端点读写。读全局选项：

curl -s -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" http://127.0.0.1:8384/rest/config/options | python3 -c "import json,sys; d=json.load(sys.stdin); print(json.dumps({k:d[k] for k in ['localAnnounceEnabled','localAnnouncePort','globalAnnounceEnabled','relaysEnabled','maxFolderConcurrency','limitBandwidthInLan','setLowPriority']}, indent=2))"

实测回显：

{
  "localAnnounceEnabled": true,
  "localAnnouncePort": 21027,
  "globalAnnounceEnabled": true,
  "relaysEnabled": true,
  "maxFolderConcurrency": 0,
  "limitBandwidthInLan": false,
  "setLowPriority": true
}

改配置用 PATCH（部分更新，即时生效）或 PUT（整体替换）。实测 PATCH 修改文件夹版本器并立即生效（返回 200，无需重启进程，回显与效果见第六章 6.5）：

curl -s -X PATCH -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" -H "Content-Type: application/json" \
  -d '{"versioning":{"type":"simple","params":{"keep":"5"}}}' \
  http://127.0.0.1:8384/rest/config/folders/sync-demo -w "[%{http_code}]"

实测回显：

[200]

3.3 通道三：直接编辑 config.xml（停止服务后）

官方首启日志明确提示 "Default config saved; edit to taste (with Syncthing stopped) or use the GUI"——直接改文件必须在服务停止时进行，否则 Syncthing 退出时会用内存中的配置覆盖手改内容：

systemctl stop syncthing@root
vi /root/.local/state/syncthing/config.xml
systemctl start syncthing@root

💡 三通道怎么选：临时改一两个参数用 REST PATCH（即时生效、免重启）；批量初始化用编辑 config.xml + 重启；给人看与学用 GUI。GUI 与 REST 本质同源（GUI 界面就是调 REST），config.xml 是落盘形态。

四、参数总览：config.xml 结构树

v2.1.7 首启生成的默认 config.xml 全文（实测照抄，<apikey> 为本机真实值，XML 内容解读见第五章）：

<configuration version="52">
    <device id="BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX" name="syncthing-server" compression="metadata" introducer="false" skipIntroductionRemovals="false" introducedBy="">
        <address>dynamic</address>
        <paused>false</paused>
        <autoAcceptFolders>false</autoAcceptFolders>
        <maxSendKbps>0</maxSendKbps>
        <maxRecvKbps>0</maxRecvKbps>
        <maxRequestKiB>0</maxRequestKiB>
        <untrusted>false</untrusted>
        <remoteGUIPort>0</remoteGUIPort>
        <numConnections>0</numConnections>
    </device>
    <gui enabled="true" tls="false" sendBasicAuthPrompt="false">
        <address>127.0.0.1:8384</address>
        <metricsWithoutAuth>false</metricsWithoutAuth>
        <apikey>LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL</apikey>
        <theme>default</theme>
        <sessionCookieDurationS>604800</sessionCookieDurationS>
        <sessionCookiePath>/</sessionCookiePath>
    </gui>
    <ldap></ldap>
    <options>
        <listenAddress>default</listenAddress>
        <globalAnnounceServer>default</globalAnnounceServer>
        <globalAnnounceEnabled>true</globalAnnounceEnabled>
        <localAnnounceEnabled>true</localAnnounceEnabled>
        <localAnnouncePort>21027</localAnnouncePort>
        <localAnnounceMCAddr>[ff12::8384]:21027</localAnnounceMCAddr>
        <maxSendKbps>0</maxSendKbps>
        <maxRecvKbps>0</maxRecvKbps>
        <reconnectionIntervalS>20</reconnectionIntervalS>
        <relaysEnabled>true</relaysEnabled>
        <relayReconnectIntervalM>10</relayReconnectIntervalM>
        <startBrowser>true</startBrowser>
        <natEnabled>true</natEnabled>
        <natLeaseMinutes>60</natLeaseMinutes>
        <natRenewalMinutes>30</natRenewalMinutes>
        <natTimeoutSeconds>10</natTimeoutSeconds>
        <urAccepted>0</urAccepted>
        <urSeen>0</urSeen>
        <urUniqueID></urUniqueID>
        <urURL>https://data.syncthing.net/newdata</urURL>
        <urInitialDelayS>1800</urInitialDelayS>
        <autoUpgradeIntervalH>12</autoUpgradeIntervalH>
        <upgradeToPreReleases>false</upgradeToPreReleases>
        <keepTemporariesH>24</keepTemporariesH>
        <progressUpdateIntervalS>5</progressUpdateIntervalS>
        <limitBandwidthInLan>false</limitBandwidthInLan>
        <minHomeDiskFree unit="%">1</minHomeDiskFree>
        <releasesURL>https://upgrades.syncthing.net/meta.json</releasesURL>
        <overwriteRemoteDeviceNamesOnConnect>false</overwriteRemoteDeviceNamesOnConnect>
        <tempIndexMinBlocks>10</tempIndexMinBlocks>
        <unackedNotificationID>authenticationUserAndPassword</unackedNotificationID>
        <trafficClass>0</trafficClass>
        <setLowPriority>true</setLowPriority>
        <maxFolderConcurrency>0</maxFolderConcurrency>
        <crashReportingURL>https://crash.syncthing.net/newcrash</crashReportingURL>
        <crashReportingEnabled>true</crashReportingEnabled>
        <stunKeepaliveStartS>180</stunKeepaliveStartS>
        <stunKeepaliveMinS>20</stunKeepaliveMinS>
        <stunServer>default</stunServer>
        <maxConcurrentIncomingRequestKiB>0</maxConcurrentIncomingRequestKiB>
        <announceLANAddresses>true</announceLANAddresses>
        <sendFullIndexOnUpgrade>false</sendFullIndexOnUpgrade>
        <auditEnabled>false</auditEnabled>
        <auditFile></auditFile>
        <connectionLimitEnough>0</connectionLimitEnough>
        <connectionLimitMax>0</connectionLimitMax>
        <connectionPriorityTcpLan>10</connectionPriorityTcpLan>
        <connectionPriorityQuicLan>20</connectionPriorityQuicLan>
        <connectionPriorityTcpWan>30</connectionPriorityTcpWan>
        <connectionPriorityQuicWan>40</connectionPriorityQuicWan>
        <connectionPriorityRelay>50</connectionPriorityRelay>
        <connectionPriorityUpgradeThreshold>0</connectionPriorityUpgradeThreshold>
    </options>
    <defaults>
        <folder id="" label="" path="" type="sendreceive" rescanIntervalS="3600" fsWatcherEnabled="true" fsWatcherDelayS="10" fsWatcherTimeoutS="0" ignorePerms="false" autoNormalize="true">
            <filesystemType>basic</filesystemType>
            <device id="BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX" introducedBy="">
                <encryptionPassword></encryptionPassword>
            </device>
            <minDiskFree unit="%">1</minDiskFree>
            <versioning>
                <cleanupIntervalS>3600</cleanupIntervalS>
                <fsPath></fsPath>
                <fsType>basic</fsType>
            </versioning>
            <copiers>0</copiers>
            <pullerMaxPendingKiB>0</pullerMaxPendingKiB>
            <hashers>0</hashers>
            <order>random</order>
            <ignoreDelete>false</ignoreDelete>
            <scanProgressIntervalS>0</scanProgressIntervalS>
            <pullerPauseS>0</pullerPauseS>
            <pullerDelayS>1</pullerDelayS>
            <maxConflicts>10</maxConflicts>
            <disableSparseFiles>false</disableSparseFiles>
            <paused>false</paused>
            <markerName>.stfolder</markerName>
            <copyOwnershipFromParent>false</copyOwnershipFromParent>
            <modTimeWindowS>0</modTimeWindowS>
            <maxConcurrentWrites>16</maxConcurrentWrites>
            <disableFsync>false</disableFsync>
            <blockPullOrder>standard</blockPullOrder>
            <copyRangeMethod>standard</copyRangeMethod>
            <caseSensitiveFS>false</caseSensitiveFS>
            <junctionsAsDirs>false</junctionsAsDirs>
            <syncOwnership>false</syncOwnership>
            <sendOwnership>false</sendOwnership>
            <syncXattrs>false</syncXattrs>
            <sendXattrs>false</sendXattrs>
            <blockIndexing>true</blockIndexing>
            <xattrFilter>
                <maxSingleEntrySize>1024</maxSingleEntrySize>
                <maxTotalSize>4096</maxTotalSize>
            </xattrFilter>
        </folder>
        <device id="" compression="metadata" introducer="false" skipIntroductionRemovals="false" introducedBy="">
            <address>dynamic</address>
            <paused>false</paused>
            <autoAcceptFolders>false</autoAcceptFolders>
            <maxSendKbps>0</maxSendKbps>
            <maxRecvKbps>0</maxRecvKbps>
            <maxRequestKiB>0</maxRequestKiB>
            <untrusted>false</untrusted>
            <remoteGUIPort>0</remoteGUIPort>
            <numConnections>0</numConnections>
        </device>
        <ignores></ignores>
    </defaults>
</configuration>

结构解读：config.xml 分五大段——<device>（本机设备声明，每个远程设备一段）、<gui>（Web GUI 与 API）、<ldap>（LDAP 认证，默认空）、<options>（全局行为）、<defaults>（新建文件夹/设备的默认模板）。version="52" 是配置 schema 版本，Syncthing 升级时自动迁移版本号。

五、核心参数分类详解

5.1 <options> 全局行为参数

参数默认值说明
listenAddressdefault同步协议监听地址；default 展开为 tcp://0.0.0.0:22000, quic://0.0.0.0:22000, dynamic+https://relays.syncthing.net/endpoint（TCP+QUIC+动态中继）
globalAnnounceEnabledtrue全局发现开关；内网隐私场景可关
globalAnnounceServerdefault全局发现服务器，默认官方集群
localAnnounceEnabledtrue本地发现开关（UDP 21027 广播/组播）
localAnnouncePort / localAnnounceMCAddr21027 / [ff12::8384]:21027本地发现端口与 IPv6 组播地址
relaysEnabled / relayReconnectIntervalMtrue / 10是否允许经官方中继池转发（无直连时兜底）
natEnabled 及 natLeaseMinutes/natRenewalMinutes/natTimeoutSecondstrue / 60 / 30 / 10UPnP/NAT-PMP 端口映射
maxSendKbps / maxRecvKbps0全局带宽限速（KiB/s，0 不限）
limitBandwidthInLanfalse限速是否也作用于局域网直连；默认 LAN 不限速
maxFolderConcurrency0并发同步的文件夹数；0=自动
reconnectionIntervalS20断线重连间隔（秒）
startBrowsertrue启动后弹系统浏览器打开 GUI（服务模式由 --no-browser 抑制）
setLowPrioritytrue进程降为低 CPU 优先级（nice），避免抢占业务
keepTemporariesH24同步临时文件（.syncthing.* 前缀）保留小时数
minHomeDiskFree1 %配置目录所在盘最低剩余空间，低于则拒写
urAccepted0匿名使用统计同意标记；0=未同意不上报
crashReportingEnabledtrue崩溃报告上报 crash.syncthing.net
auditEnabled / auditFilefalse / 空审计日志开关与文件（合规场景开启）
announceLANAddressestrue发现公告是否携带局域网地址
connectionPriorityTcpLan/QuicLan/TcpWan/QuicWan/Relay10/20/30/40/50连接方式优先级，数值小者优先（解释了「能直连不走中继」）
autoUpgradeIntervalH / upgradeToPreReleases12 / false自动升级检查间隔与是否吃预发布版（deb 包 noupgrade 标记时无效）
stunServer 等 STUN 族default / 180 / 20STUN 探测公网地址（NAT 穿透辅助）

解读：与「发现/连接」相关的开关是内网隐私加固的重点（globalAnnounce/localAnnounce/relaysEnabled/natEnabled 四件套）；setLowPriority 与 maxFolderConcurrency 是业务混部时最先调的两项。

5.2 <gui> Web GUI 与 API 参数

参数默认值说明
enabled / tlstrue / falseGUI 开关；tls="false" 时 GUI 为 HTTP，改 true 自动生成自签 HTTPS 证书（https-cert.pem/https-key.pem，syncthing paths 可见）
address127.0.0.1:8384监听地址；远程访问改 0.0.0.0:8384（实测见安装指南 8.4）
user / password无管理账号与 bcrypt 哈希密码；syncthing generate --gui-user/--gui-password 写入（实测回显见安装指南 8.3）
apikey随机生成REST API 调用凭据，请求头 X-API-Key
themedefaultGUI 主题
sessionCookieDurationS604800登录会话 Cookie 有效期（秒，7 天）
metricsWithoutAuthfalse是否允许无认证访问 /metrics 端点
sendBasicAuthPromptfalse是否发送 HTTP Basic 认证质询

安全要点：改绑 0.0.0.0 的前提是 user/password 已设置；生产建议 tls="true" 并继续用反向代理终止 TLS 的方案二选一。

5.3 文件夹参数（<folder> 与 <defaults><folder>）

文件夹参数在每个 <folder> 段（本机实测有一个共享文件夹 sync-demo）。核心项（默认值取自实测 <defaults> 段）：

参数默认值说明
typesendreceive同向类型；可选 sendonly（仅发送）、receiveonly（仅接收）、receiveencrypted（加密接收中转）
rescanIntervalS3600全量重扫周期（秒）；文件系统监听正常时兜底用
fsWatcherEnabled / fsWatcherDelayStrue / 10文件系统监听与事件聚合延迟（秒），决定「秒级感知」
ignorePermsfalse忽略权限差异（跨文件系统/Windows 混合同步常开）
autoNormalizetrue文件名 Unicode 规范化
filesystemTypebasic文件系统抽象；挂载类目录可换 fake（仅索引不落盘）等
minDiskFree1 %本地磁盘剩余低于此值停止 pull
copiers / hashers0 / 0复制与哈希并发数；0=自动按 CPU
orderrandom拉取顺序；可改 alphabetic、smallestFirst、largestFirst、newestFirst、oldestFirst
maxConflicts10冲突副本保留上限（0 禁用冲突副本）
pullerDelayS / pullerPauseS1 / 0pull 批次间延迟与暂停
maxConcurrentWrites16并发写文件数
disableSparseFiles / disableFsyncfalse / false稀疏文件支持与每文件 fsync
blockPullOrder / copyRangeMethodstandard / standard块拉取顺序与拷贝范围方法（inOrder/random/progress；ioctl/send+receive/all/standard）
markerName.stfolder文件夹标记目录名
versioning 子段见 5.4文件版本器配置
syncOwnership/sendOwnership/syncXattrs/sendXattrsfalse属主与扩展属性同步（类 Unix）
xattrFilter1024/4096单条与总量 xattr 大小过滤（字节，KiB 为单位实测值为 1024/4096）
ignoreDeletefalse忽略远端删除（防误删兜底之一）
pausedfalse暂停该文件夹同步

💡 技术拓展：文件夹同步方向类型对比——

类型本端可改远端变更拉取适用场景
sendreceive（默认）是是普通双向同步
sendonly是（仅作源）否主备份源，防远端脏写回灌
receiveonly否是纯接收备份靶机，本地改动会被覆盖
receiveencrypted否（只见密文）是（密文）不可信中转节点存储加密数据

本文实验使用默认 sendreceive（两端可写），备份到 NAS 的场景推荐 sendonly + receiveonly 组合。

5.4 文件版本控制（<versioning>）与实测

Syncthing 提供四类版本器（来源：docs.syncthing.net/users/versioning.html，2026-10-22 查证；类型与参数为实测确认）：

版本器原理关键参数
trashcan删除/覆盖的文件移入 .stversions，按 cleanoutDays 过期清理cleanoutDays（默认 0=永不过期）
simple同上，但同文件最多保留 keep 份keep
staggered按时间阶梯保留（最近 7 天每份、7-30 天每天 1 份、…）直到 maxAgemaxAge、cleanInterval、fsPath/fsType
external每次归档调用外部命令command

实测：给 sync-demo 启用 simple 版本器（keep=5），由对端设备删除文件后观察本端归档行为。启用（REST PATCH，回显见 3.2 节，[200]）；对端删除 hello2.txt 后本端目录状态：

ls -la /root/sync-demo/ && ls -la /root/sync-demo/.stversions/

实测回显：

total 3088
drwxr-xr-x 4 root root    4096 Oct 21 18:26 .
drwx------ 1 root root    4096 Oct 21 18:19 ..
drwxr-x--- 2 root root    4096 Oct 21 18:19 .stfolder
drwxr-x--- 2 root root    4096 Oct 21 18:26 .stversions
-rw-r--r-- 1 root root 3145728 Oct 21 18:20 data.bin
total 12
drwxr-x--- 2 root root    4096 Oct 21 18:26 .
drwxr-xr-x 4 root root    4096 Oct 21 18:26 ..
-rw-r--r-- 1 root root   21 Oct 21 18:26 hello2~20261021-182649.txt

结论验证：远端删除传播到本端时，被删文件以「原文件名~删除时间戳」格式归档进 .stversions/（hello2~20261021-182649.txt），误删可从该目录找回。⚠️ 实测中还有一个值得记录的细节：本地直接 rm 文件不会进 .stversions（本地删除直接向全网传播），版本归档只发生在「Syncthing 执行覆盖/删除动作」时——simple/trashcan 版本器防的是「同步带来的覆盖与删除」，不是本地误删的实时保险。

5.5 设备参数（<device>）

参数默认值说明
id—64 位设备 ID（证书指纹），必填
name主机名备注名
compressionmetadata压缩策略：always/metadata/never（元数据必压，数据可选）
addressdynamicdynamic 用发现机制找地址，也可写静态 tcp://10.0.0.2:22000
introducer / introducedByfalse / 空是否为「介绍人」设备 / 由谁介绍
autoAcceptFoldersfalse对端新建共享文件夹时自动接受（配合介绍人实现级联）
maxSendKbps / maxRecvKbps0每设备限速
maxRequestKiB0单请求块上限
untrustedfalse标记不可信设备（配合 receiveencrypted 使用）
pausedfalse暂停与该设备的连接
remoteGUIPort0允许从本端 GUI 跳转到对端 GUI 的端口（0 禁用）

六、生产配置模板

6.1 模板说明

适用场景：2-10 台 Linux 服务器/NAS 组成的内网同步集群，4 GB 内存、SSD/HDD 混合磁盘、日常同步量 < 100 GB。以下为在默认配置上叠加的增量片段（注释标明改动理由）。

6.2 全局段增量（<options>）

<options>
    <!-- 内网集群不需要公网发现与中继 -->
    <globalAnnounceEnabled>false</globalAnnounceEnabled>
    <relaysEnabled>false</relaysEnabled>
    <!-- 保留本地发现（同网段自动配对地址） -->
    <localAnnounceEnabled>true</localAnnounceEnabled>
    <!-- 大文件夹多时放开并发；16 内存充裕机器可设 8-16 -->
    <maxFolderConcurrency>4</maxFolderConcurrency>
    <!-- 混部服务器进程降级保持默认开启 -->
    <setLowPriority>true</setLowPriority>
</options>

逐项说明：关闭全局发现与中继后，跨网段同步需在设备上写静态 address（tcp://<IP>:22000），换来的是零公网信息泄露；maxFolderConcurrency 从自动（0）调到 4 可提升多文件夹并行吞吐，代价是瞬时 IO 与内存占用升高。

6.3 GUI 段生产加固（<gui>）

<gui enabled="true" tls="true" sendBasicAuthPrompt="false">
    <address>0.0.0.0:8384</address>
    <user>admin</user>
    <password>$2a$10$MID3S4HT3RhSsREu0n5LguPxrFIyQKycaDBTWk0JXSK0axqZ2oCLS</password>
    <apikey>LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL</apikey>
</gui>

说明：tls="true" 启用 HTTPS（自签证书自动生成）；address 改绑 0.0.0.0 仅在配合防火墙白名单时使用；账号密码用 syncthing generate --gui-user=admin --gui-password=q1w2e3r4 --home /root/.local/state/syncthing 生成（回显见安装指南 8.3 节，<password> 为其落盘的 bcrypt 哈希实测值）。

6.4 文件夹模板增量（备份型）

<folder id="backup-data" label="backup-data" path="/data/backup" type="sendreceive"
        rescanIntervalS="3600" fsWatcherEnabled="true" fsWatcherDelayS="10">
    <versioning>
        <cleanupIntervalS>3600</cleanupIntervalS>
        <fsPath></fsPath>
        <fsType>basic</fsType>
        <type>staggered</type>
        <maxAge>2678400</maxAge>
    </versioning>
    <order>alphabetic</order>
    <ignoreDelete>false</ignoreDelete>
</folder>

说明：staggered 版本器 30 天内阶梯保留历史版本（maxAge 单位秒，2678400=31 天）；order=alphabetic 让同步顺序可预期；该模板适合「多台服务器把关键目录汇到一台 NAS」的备份拓扑（源端用 sendonly、NAS 用 receiveonly 更稳）。

6.5 模板生效验证

配置写入并重启后核对（以实测的 simple 版本器为例）：

curl -s -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" http://127.0.0.1:8384/rest/config/folders/sync-demo | python3 -c "import json,sys; d=json.load(sys.stdin); print('versioning:', json.dumps(d.get('versioning')))"

实测回显：

versioning: {"type": "simple", "params": {"keep": "5"}, "cleanupIntervalS": 3600, "fsPath": "", "fsType": "basic"}

归档行为验证回显见 5.4 节（.stversions/hello2~20261021-182649.txt）。配置落盘需进程异步写盘，若直接改文件，务必在服务停止状态修改后重启（见 3.3 节）。

七、常见问题

Q1：改了 config.xml 不生效？ Syncthing 运行中手改文件会被内存配置覆盖（服务退出时回写）。要么停止服务后改再启动，要么走 REST/GUI 通道（即时生效）。

Q2：REST PATCH 返回 200 但 config.xml 没变？ 实测发现 PATCH 后内存配置立即生效（版本器行为已变），config.xml 落盘是异步的（触发条件包括 ConfigSaved 事件周期、进程退出等）。以 GET /rest/config/... 返回值为准，不必等落盘。

Q3：GUI 打不开？ 按顺序查：systemctl is-active syncthing@root 是否 active → grep '<address>' config.xml 看监听地址 → curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8384/ 是否 200 → 防火墙是否放行 8384（官方 deb 自带 ufw 预设 ufw allow syncthing-gui）。

Q4：忘记 GUI 密码？ syncthing generate --gui-user=admin --gui-password=q1w2e3r4 --home /root/.local/state/syncthing 重设（实测回显见安装指南 8.3），或停止服务后删除 <user>/<password> 两行临时免密进入再设置。

Q5：两台设备死活连不上？ 查三层：① 互加设备 ID 是否双向完成（各自 /rest/config/devices 都应有对方）；② 地址可达（telnet <对端> 22000 或看 /rest/system/discovery 是否有对端地址缓存）；③ 若关闭了全局发现且跨网段，需给设备写静态 address。实测案例中本地发现 30 秒周期内即可缓存对端 tcp:///quic:// 地址（回显见安装指南 9.5 节）。

八、参考链接

  1. 官方配置文档（config 项全集）：https://docs.syncthing.net/users/config.html
  2. 官方版本控制文档：https://docs.syncthing.net/users/versioning.html
  3. 官方 FAQ（安全与目录）：https://docs.syncthing.net/users/faq.html
  4. 本专栏认知篇：《Syncthing 介绍与选型指南》
  5. 本专栏部署篇：《Ubuntu 22.04 安装 Syncthing 指南》
  6. 本专栏命令篇：《Syncthing 2.1.7 常用 CLI 命令与工具详解》