Ubuntu 22.04 安装 Syncthing 指南

在 Ubuntu 22.04 上从零安装 Syncthing 2.1.7 的全流程实测指南：官方 apt 源（stable-v2 组件）、deb 离线包、tar.gz 二进制三种方案，systemd 托管、Web GUI 账号与远程访问配置、两节点同步配对验证与排障实录。

Syncthing备份恢复2026/10/22

Ubuntu 22.04 安装 Syncthing 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Syncthing v2.1.7 并以 systemd 托管，完成 Web GUI 初始配置与两节点同步配对验证。全文命令与回显均在 Ubuntu 22.04.5 LTS（systemd 249）环境逐条实测，照抄实录。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（内核与 systemd 版本 249.11-0ubuntu3.22，cat /etc/os-release 实测）
  • 架构：linux-amd64（x86_64）
  • Syncthing 版本：v2.1.7 "Hafnium Hornet"（go1.27.3 编译，构建时间 2026-10-20 19:54:38 UTC，syncthing --version 实测）
  • 演示用户：root（生产环境建议普通用户，见 8.4 节说明）
  • Web GUI：默认 127.0.0.1:8384，本文演示改绑 0.0.0.0:8384 供远程访问
  • 同步验证拓扑：两台 Ubuntu 22.04 服务器（syncthing-server 与 syncthing-client）同内网段互通
  • 关键目录：/root/.local/state/syncthing/（v2 配置与数据目录，syncthing paths 实测确认）

二、前置条件

本节确认安装前系统已具备的条件，逐条给出可执行命令与预期结果。

  1. 系统为 Ubuntu 22.04（20.04/24.04 流程相同，个别 systemd 警告差异见第十章）：
cat /etc/os-release

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
  1. 已安装 curl 与 gnupg（导入官方签名密钥需要；最小系统默认无 curl）：
apt-get install -y curl gnupg

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

Setting up curl ...
Setting up gnupg ...
  1. 时间同步正常（TLS 证书校验与文件时间戳依赖）：
timedatectl status | grep -E 'System clock|NTP'

实测回显：

               System clock synchronized: yes
                       NTP service: active

三、版本选型说明

Syncthing v2 系列与 v1 系列目前并行维护，安装前必须先想清楚装哪条线（来源：apt.syncthing.net 仓库元数据与 GitHub Releases，实查 2026-10-22）：

版本线当前版本apt 源组件说明
v2（推荐新装）2.1.7 "Hafnium Hornet"stable-v22025 年起的新主线，配置/数据目录与 CLI 结构有调整，本文实测对象
v1（存量兼容）1.30.0 "Gold Grasshopper"stable老主线继续维护，老配置可无缝运行
预发布—candidate / nightly想尝鲜新特性才用，生产禁用

选型结论：全新部署直接装 v2.1.7（stable-v2 组件）；已有 v1 存量环境如无 v2 新特性诉求可继续用 v1，待官方迁移指引再升级。⚠️ 最容易踩的坑：照老教程写 syncthing stable 组件只会装到 v1.30.0，详见第十章排障实录 10.1。

四、安装方案 A：官方 APT 在线源（推荐）

本章通过 Syncthing 官方 apt 仓库安装 v2.1.7，适合可联网的服务器，后续 apt upgrade 即可随官方更新。

4.1 导入官方签名密钥

官方下载页（syncthing.net/downloads/，2026-10-22 查证）提供的密钥导入方式，实测执行：

curl -fsSL https://syncthing.net/release-key.gpg | gpg --dearmor -o /usr/share/keyrings/syncthing-archive-keyring.gpg

实测回显（无输出即成功）。验证密钥文件已生成：

ls -l /usr/share/keyrings/syncthing-archive-keyring.gpg

实测回显：

-rw-r--r-- 1 root root 2585 Oct 21 18:09 /usr/share/keyrings/syncthing-archive-keyring.gpg

4.2 写入 apt 源（必须用 stable-v2 组件）

写入官方源，组件指定为 stable-v2（v2 系列稳定版）：

echo "deb [signed-by=/usr/share/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable-v2" > /etc/apt/sources.list.d/syncthing.list
cat /etc/apt/sources.list.d/syncthing.list

实测回显：

deb [signed-by=/usr/share/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable-v2

更新索引并确认候选版本为 2.1.7：

apt-get update
apt-cache policy syncthing | head -6

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

Get:3 https://apt.syncthing.net syncthing InRelease [24.2 kB]
Get:6 https://apt.syncthing.net syncthing/stable-v2 amd64 Packages [1410 B]
Hit:5 https://apt.syncthing.net syncthing InRelease
syncthing:
  Installed: (none)
  Candidate: 2.1.7
  Version table:
     2.1.7 500
        500 https://apt.syncthing.net syncthing/stable-v2 amd64 Packages

⚠️ 注意：若 apt-cache policy 显示 Candidate 是 1.30.0，说明源写成了 syncthing stable 组件（v1 线），改回 stable-v2 再 update。详见第十章 10.1。

4.3 安装

apt-get install -y syncthing

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

Reading package lists... Done
The following NEW packages will be installed:
  syncthing
Preparing to unpack .../syncthing_2.1.7_amd64.deb ...
Unpacking syncthing (2.1.7) ...
Setting up syncthing (2.1.7) ...

4.4 验证版本与包清单

syncthing --version

实测回显：

syncthing v2.1.7 "Hafnium Hornet" (go1.27.3 linux-amd64) debian@github.syncthing.net 2026-10-20 19:54:38 UTC [noupgrade]

查看 deb 包安装的文件清单（确认二进制与 systemd 服务文件位置）：

dpkg -L syncthing | grep -vE 'doc$|man|LICENSE' | grep -E 'bin|systemd|ufw|sysctl'

实测回显：

/etc/ufw/applications.d/syncthing
/lib/systemd/system/syncthing@.service
/usr/bin/syncthing
/usr/lib/sysctl.d/30-syncthing.conf
/usr/lib/systemd/user/syncthing.service

解读：deb 包提供三类系统级资产——/usr/bin/syncthing 单一二进制、/lib/systemd/system/syncthing@.service 系统级模板服务（本章 4.6 使用）、/etc/ufw/applications.d/syncthing 防火墙预设；/usr/lib/sysctl.d/30-syncthing.conf 则把 QUIC 需要的套接字缓冲区调到 7 MiB（内容见 10.5）。

五、安装方案 B：官方 deb 离线包（断网环境）

本章在另一台 Ubuntu 22.04 服务器（syncthing-client）实测：从 GitHub Releases 下载官方 deb 包离线安装，适合服务器无法访问外网或受限网络场景。

5.1 下载 deb 包

在有网机器上下载 v2.1.7 的 amd64 deb 包并校验哈希：

curl -L -o syncthing_2.1.7_amd64.deb https://github.com/syncthing/syncthing/releases/download/v2.1.7/syncthing_2.1.7_amd64.deb
sha256sum syncthing_2.1.7_amd64.deb

实测回显：

01400d260bb6e47f1fe432bbb462cdb35ea6f78fc498198dfba6e292a3614837  syncthing_2.1.7_amd64.deb

文件大小 14054904 字节（约 13.4 MiB）。GitHub 下载慢时可用代理下载：

curl -L -x http://192.168.1.62:7897 -o syncthing_2.1.7_amd64.deb https://github.com/syncthing/syncthing/releases/download/v2.1.7/syncthing_2.1.7_amd64.deb

5.2 传输并安装

将 deb 包拷贝到目标服务器后安装：

dpkg -i syncthing_2.1.7_amd64.deb

实测回显（实测首尾）：

(Reading database ... 6535 files and directories currently installed.)
Preparing to unpack .../syncthing_2.1.7_amd64.deb ...
Unpacking syncthing (2.1.7) ...
Setting up syncthing (2.1.7) ...

验证：

syncthing --version

实测回显：

syncthing v2.1.7 "Hafnium Hornet" (go1.27.3 linux-amd64) debian@github.syncthing.net 2026-10-20 19:54:38 UTC [noupgrade]

⚠️ 注意：deb 包不带依赖，若系统缺 libc 等基础库导致 dpkg 报依赖错误，执行 apt-get install -f 自动补齐。Ubuntu 22.04 最小安装可直接装。

六、安装方案 C：官方 tar.gz 二进制

本章实测直接解包官方 linux-amd64 二进制压缩包，适合不想用包管理器、或需要多版本并存的管理场景。

6.1 下载与解包

curl -L -o syncthing-linux-amd64-v2.1.7.tar.gz https://github.com/syncthing/syncthing/releases/download/v2.1.7/syncthing-linux-amd64-v2.1.7.tar.gz
sha256sum syncthing-linux-amd64-v2.1.7.tar.gz

实测回显：

2edc416e7ed136b7c858ed5f3f02a3b8316589605e54c380228ceea7acbf0142  syncthing-linux-amd64-v2.1.7.tar.gz

解包到独立目录（包内自带顶层目录 syncthing-linux-amd64-v2.1.7/）：

tar -xzf syncthing-linux-amd64-v2.1.7.tar.gz -C /opt

实测回显（tar 无报错即成功；包内容如下）：

syncthing-linux-amd64-v2.1.7/
syncthing-linux-amd64-v2.1.7/etc/
syncthing-linux-amd64-v2.1.7/etc/linux-desktop/
syncthing-linux-amd64-v2.1.7/etc/linux-desktop/syncthing-ui.desktop
syncthing-linux-amd64-v2.1.7/etc/linux-desktop/syncthing-start.desktop
syncthing-linux-amd64-v2.1.7/etc/solaris-smf/

6.2 验证二进制

/opt/syncthing-linux-amd64-v2.1.7/syncthing --version

实测回显：

syncthing v2.1.7 "Hafnium Hornet" (go1.27.3 linux-amd64) builder@github.syncthing.net 2026-10-20 19:54:38 UTC

6.3 手写 systemd 服务托管（tar.gz 方案专用）

tar.gz 方案不自带系统级服务文件，需要手写 unit。创建 /etc/systemd/system/syncthing.service：

[Unit]
Description=Syncthing - Open Source Continuous File Synchronization
Documentation=man:syncthing(1)
After=network.target

[Service]
User=root
ExecStart=/opt/syncthing-linux-amd64-v2.1.7/syncthing serve --no-browser --no-restart
Restart=on-failure
SuccessExitStatus=3 4
RestartForceExitStatus=3 4

[Install]
WantedBy=multi-user.target

配置说明：ExecStart 与官方 syncthing@.service 一致使用 serve --no-browser --no-restart（禁止 GUI 弹浏览器、禁止进程自杀重启，由 systemd 负责）；User 按实际运行用户填写。启用并启动：

systemctl daemon-reload
systemctl enable --now syncthing.service

实测回显（输出节选）：

Created symlink /etc/systemd/system/multi-user.target.wants/syncthing.service → /etc/systemd/system/syncthing.service.

七、方案对比与选择建议

维度方案 A：apt 在线源方案 B：deb 离线包方案 C：tar.gz 二进制
版本2.1.7（stable-v2 组件）2.1.7（GitHub Releases）2.1.7（GitHub Releases）
是否需联网安装与升级均需访问 apt.syncthing.net仅下载时联网，安装离线仅下载时联网，安装离线
安装方式apt-get install syncthingdpkg -i xxx.debtar 解包 + 手写 unit
systemd 服务来源官方 syncthing@.service 模板官方 syncthing@.service 模板需手写 unit 文件
附带资产ufw 预设、sysctl 调优、man 文档同左无（仅二进制与桌面文件）
升级方式apt upgrade重新下载新 deb 覆盖安装重新下载解包 + 改 unit 路径
适用场景可联网服务器（首选）断网/内网服务器多版本并存、极简定制

选择建议：能联网选方案 A（升级最省心）；服务器在内网隔离环境选方案 B（保留包管理器卸载能力）；需要精确控制安装路径或多版本共存选方案 C。

八、配置说明：systemd 托管与 Web GUI 初始配置

本章以方案 A/B 安装后的官方 syncthing@.service 为准，完成「启动服务 → 首次生成配置 → 设置 GUI 账号密码 → 改绑远程访问」四个步骤。

8.1 启用并启动模板服务

syncthing@.service 是按用户实例化的模板服务，@ 后面填运行 Syncthing 的系统用户名（本文以 root 演示）：

systemctl enable syncthing@root

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/syncthing@root.service → /lib/systemd/system/syncthing@.service.

systemctl start syncthing@root

启动后查看状态：

systemctl status syncthing@root --no-pager

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

● syncthing@root.service - Syncthing - Open Source Continuous File Synchronization for root
     Loaded: loaded (/lib/systemd/system/syncthing@.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-21 18:15:26 UTC; 6s ago
       Docs: man:syncthing(1)
   Main PID: 3792 (syncthing)
      Tasks: 26 (limit: 94371)
     Memory: 19.7M
        CPU: 544ms
             ├─3792 /usr/bin/syncthing serve --no-browser --no-restart

验证命令回显：Active: active (running) 即启动成功；进程命令行 /usr/bin/syncthing serve --no-browser --no-restart 说明 systemd 模式下 Syncthing 由服务托管。

8.2 首次启动日志与配置文件位置

首次启动会自动生成设备证书、设备 ID 与默认配置，查看完整日志：

journalctl -u syncthing@root --no-pager -n 25

实测回显（v2.1.7 首启日志原文）：

Oct 21 18:15:26 syncthing-server systemd[1]: Started Syncthing - Open Source Continuous File Synchronization for root.
Oct 21 18:15:26 syncthing-server syncthing[3792]: syncthing v2.1.7 "Hafnium Hornet" (go1.27.3 linux-amd64) debian@github.syncthing.net 2026-10-20 19:54:38 UTC [noupgrade] (log.pkg=main)
Oct 21 18:15:26 syncthing-server syncthing[3792]: Generating key and certificate (cn=syncthing log.pkg=syncthing)
Oct 21 18:15:26 syncthing-server syncthing[3792]: Default config saved; edit to taste (with Syncthing stopped) or use the GUI (path=/root/.local/state/syncthing/config.xml log.pkg=syncthing)
Oct 21 18:15:26 syncthing-server syncthing[3792]: Calculated our device ID (device=BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX log.pkg=syncthing)
Oct 21 18:15:26 syncthing-server syncthing[3792]: QUIC listener starting (address="[::]:22000" log.pkg=connections)
Oct 21 18:15:26 syncthing-server syncthing[3792]: Using discovery mechanism (identity="global discovery server https://discovery-lookup.syncthing.net/v2/?noannounce" log.pkg=discover)
Oct 21 18:15:26 syncthing-server syncthing[3792]: Using discovery mechanism (identity="IPv4 local broadcast discovery on port 21027" log.pkg=discover)
Oct 21 18:15:26 syncthing-server syncthing[3792]: Using discovery mechanism (identity="IPv6 local multicast discovery on address [ff12::8384]:21027" log.pkg=discover)
Oct 21 18:15:26 syncthing-server syncthing[3792]: TCP listener starting (address="[::]:22000" log.pkg=connections)
Oct 21 18:15:26 syncthing-server syncthing[3792]: GUI and API listening (address=127.0.0.1:8384 log.pkg=api)
Oct 21 18:15:26 syncthing-server syncthing[3792]: Access the GUI via the following URL: http://127.0.0.1:8384/ (log.pkg=api)
Oct 21 18:15:27 syncthing-server syncthing[3792]: Measured hashing performance (perf="2363.24 MB/s" log.pkg=syncthing)

解读日志中的关键信息：默认配置写入 path=/root/.local/state/syncthing/config.xml（⚠️ v2 的配置与数据目录是 ~/.local/state/syncthing/，不再是 v1 的 ~/.config/syncthing/）；本机设备 ID 已生成；同步监听 22000（TCP+QUIC）；GUI 默认只监听 127.0.0.1:8384。

用 syncthing paths 汇总确认目录布局：

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

GUI / API HTTPS private key & certificate files:
        /root/.local/state/syncthing/https-key.pem
        /root/.local/state/syncthing/https-cert.pem

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

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

GUI override directory:
        /root/.local/state/syncthing/gui

Default sync folder directory:
        /root/Sync

8.3 设置 Web GUI 管理账号密码

v2.1.7 用 syncthing generate 子命令写入 GUI 认证账号（密码自动以 bcrypt 哈希落盘）。⚠️ v2 语法与 v1 不同：不再接受位置参数指定目录，必须用 --home（或成对 --config/--data），否则报错（排障实录见第十章 10.2）：

systemctl stop syncthing@root
syncthing generate --gui-user=admin --gui-password=q1w2e3r4 --home /root/.local/state/syncthing

实测回显：

2026-10-21 18:17:13 WRN Key exists; will not overwrite (log.pkg=github)
2026-10-21 18:17:13 INF Calculated device ID (device=BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX log.pkg=github)
2026-10-21 18:17:13 INF Updated GUI authentication user (name=admin log.pkg=github)
2026-10-21 18:17:13 INF Updated GUI authentication password (log.pkg=github)

回显确认 Updated GUI authentication user/password 即写入成功（密钥不会被覆盖，仅更新认证信息）。

8.4 GUI 改绑 0.0.0.0 供远程访问

默认 GUI 只监听 127.0.0.1，远程管理需改绑到所有网卡。停止服务后编辑 config.xml 的 <gui><address>：

sed -i 's|<address>127.0.0.1:8384</address>|<address>0.0.0.0:8384</address>|' /root/.local/state/syncthing/config.xml
grep -E '<address>|<user>' /root/.local/state/syncthing/config.xml | head -4

实测回显：

        <address>dynamic</address>
        <address>0.0.0.0:8384</address>
        <user>admin</user>

重启服务并确认监听：

systemctl start syncthing@root
systemctl is-active syncthing@root

实测回显：

active

从另一台机器验证 GUI 已可远程访问（无凭据访问首页返回 200，API 未带 API Key 返回 403）：

curl -s -o /dev/null -w '%{http_code}\n' http://<服务器IP>:8384/

实测回显（在管理机上执行，指向被测服务器）：

200

⚠️ 注意：改绑 0.0.0.0 后 GUI 暴露给网络，必须已设置账号密码（8.3 节），生产环境建议进一步用防火墙限制来源 IP 或改走 HTTPS（GUI 设置 tls="true"）。

⚠️ 关于运行用户：日志会提示 "Syncthing should not run as a privileged or system user; please consider using a normal user account"。生产建议创建专用用户（如 adduser syncuser 后 systemctl enable --now syncthing@syncuser），其配置目录为 /home/syncuser/.local/state/syncthing/，本文为演示简便以 root 运行。

九、两节点同步配对验证

安装的价值在于跑通同步。本章在两台 Ubuntu 22.04 服务器（syncthing-server 与 syncthing-client，同内网互通）上完成「互加设备 → 建共享文件夹 → 文件自动同步」全流程。

9.1 获取两台设备的 Device ID

两台服务器分别执行（设备 ID 也可从首启日志 Calculated our device ID 一行获取）：

syncthing device-id

节点一（syncthing-server）实测回显：

BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX

节点二（syncthing-client）实测回显：

H4EJJ6T-TDBKQFV-AK4FR2S-XCOS326-X3A4NQY-D4HJ7JS-BKYLK3X-IWB6HQB

9.2 互加设备（REST API 方式）

Web GUI「添加远程设备」与 REST 等价，本节用 REST API 演示（脚本化管理更方便；API Key 取自各自 config.xml 的 <apikey> 字段）。节点一添加节点二：

curl -s -X PUT -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" -H "Content-Type: application/json" \
  -d '{"deviceID":"H4EJJ6T-TDBKQFV-AK4FR2S-XCOS326-X3A4NQY-D4HJ7JS-BKYLK3X-IWB6HQB","name":"syncthing-client"}' \
  http://127.0.0.1:8384/rest/config/devices/H4EJJ6T-TDBKQFV-AK4FR2S-XCOS326-X3A4NQY-D4HJ7JS-BKYLK3X-IWB6HQB

实测回显（PUT 成功返回空体）；核对配置：

curl -s -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" http://127.0.0.1:8384/rest/config/devices | python3 -c "import json,sys; d=json.load(sys.stdin); print('devices:', [x['deviceID'][:8] for x in d])"

实测回显：

devices: ['BITUNOQ-', 'H4EJJ6T-']

节点二对称地添加节点一（API Key 各自不同，实测值为 rFSqNpHbtKgugCJsRH3xEbtUZL2TKaJF）：

curl -s -X PUT -H "X-API-Key: rFSqNpHbtKgugCJsRH3xEbtUZL2TKaJF" -H "Content-Type: application/json" \
  -d '{"deviceID":"BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX","name":"syncthing-server"}' \
  http://127.0.0.1:8384/rest/config/devices/BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX

9.3 创建共享文件夹

两台服务器各自创建本地目录并注册同名共享文件夹 sync-demo（文件夹 ID 两端必须一致）。节点一：

mkdir -p /root/sync-demo
curl -s -X PUT -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" -H "Content-Type: application/json" \
  -d '{"id":"sync-demo","label":"sync-demo","path":"/root/sync-demo","type":"sendreceive","devices":[{"deviceID":"BITUNOQ-VKBHIFH-2UWCK4D-CCANXZC-GV6VG3E-6JDFMHV-7VZW57L-F3LTKQX"},{"deviceID":"H4EJJ6T-TDBKQFV-AK4FR2S-XCOS326-X3A4NQY-D4HJ7JS-BKYLK3X-IWB6HQB"}]}' \
  http://127.0.0.1:8384/rest/config/folders/sync-demo

节点二对称执行（path 换为自己的 /root/sync-demo，devices 列表相同）。REST 修改即时生效，无需重启进程。

9.4 放入文件验证自动同步

节点一创建测试文件（文本 + 3MB 二进制）：

echo "hello from node1 $(date)" > /root/sync-demo/hello.txt
dd if=/dev/urandom of=/root/sync-demo/data.bin bs=1M count=3

实测回显（输出节选）：

3145728 bytes (3.1 MB, 3.0 MiB) copied, 0.00590846 s, 532 MB/s

约 30 秒内（本地发现广播周期 30 秒，首次配对含索引交换）节点二目录出现同样文件：

ls -la /root/sync-demo/ && cat /root/sync-demo/hello.txt

节点二实测回显：

total 3088
drwxr-xr-x 3 root root    4096 Oct 21 18:21 .
drwx------ 1 root root    4096 Oct 21 18:20 ..
drwxr-x--- 2 root root    4096 Oct 21 18:20 .stfolder
-rw-r--r-- 1 root root 3145728 Oct 21 18:20 data.bin
-rw-r--r-- 1 root root      46 Oct 21 18:20 hello.txt
hello from node1 Wed Oct 21 18:20:52 UTC 2026

解读：.stfolder 是 Syncthing 的文件夹标记目录（自动创建），两个文件已完整到达节点二。

9.5 连接与同步状态核对

节点一查看连接详情：

curl -s -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" http://127.0.0.1:8384/rest/system/connections | python3 -c "
import json,sys; d=json.load(sys.stdin)
for devid, info in d['connections'].items():
    print(devid[:8], '|', info['address'], '|', info['type'], '| isLocal:', info['isLocal'], '| outBytesTotal:', info['outBytesTotal'])"

实测回显：

H4EJJ6T- | 10.89.67.3:22000 | tcp-client | isLocal: True | outBytesTotal: 3147505

解读：连接类型 tcp-client（LAN 直连 TCP），isLocal: True 说明走了本地网络直连而非中继；输出字节 3147505 与 3MB 测试文件吻合。节点二查看文件夹同步状态：

curl -s -H "X-API-Key: rFSqNpHbtKgugCJsRH3xEbtUZL2TKaJF" "http://127.0.0.1:8384/rest/db/status?folder=sync-demo" | python3 -c "import json,sys; d=json.load(sys.stdin); print('state:', d['state'], '| globalFiles:', d['globalFiles'], '| inSyncFiles:', d['inSyncFiles'])"

实测回显：

state: idle | globalFiles: 2 | inSyncFiles: 2

state: idle 且 inSyncFiles 等于 globalFiles 表示两台设备已完全同步。本地发现缓存亦可核对：

curl -s -H "X-API-Key: LbDgdphpYTUQiq4SHqzaMbmhR36WY9wL" http://127.0.0.1:8384/rest/system/discovery | python3 -m json.tool

实测回显（节点一视角，本地发现已缓存节点二地址）：

{
    "H4EJJ6T-TDBKQFV-AK4FR2S-XCOS326-X3A4NQY-D4HJ7JS-BKYLK3X-IWB6HQB": {
        "addresses": [
            "tcp://10.89.67.3:22000",
            "quic://10.89.67.3:22000",
            "quic://182.54.113.29:16728"
        ]
    }
}

十、常见问题（排障实录）

以下均为本次安装实测中真实遇到并解决的问题。

10.1 照老教程写 syncthing stable 只装到 v1.30.0

现象：apt 源可用，但 apt-get install syncthing 装出来的是 1.30.0 而非 2.1.7，syncthing --version 回显：

syncthing v1.30.0 "Gold Grasshopper" (go1.24.4 linux-amd64) debian@github.syncthing.net 2025-06-20 09:17:23 UTC [noupgrade, noupgrade]

定位：官方 apt 源 suite 为 syncthing，组件（component）在 2025 年后拆分为五个，直接读仓库 InRelease 元数据确认：

curl -s https://apt.syncthing.net/dists/syncthing/InRelease | grep '^Components'

实测回显：

Components: candidate nightly stable stable-v1 stable-v2

即 stable 组件实为 v1 线（1.30.0），stable-v2 才是 v2 线；stable-v1 与 stable 当前同指 v1（stable-v2 的 Packages 索引实测含 syncthing 2.1.7/2.1.6）。

解决：源文件改写为 stable-v2 组件并重新 update（见 4.2 节），已装 v1 时直接 apt-get install syncthing 即升级到 2.1.7，实测升级回显：

Preparing to unpack .../syncthing_2.1.7_amd64.deb ...
Unpacking syncthing (2.1.7) over (1.30.0) ...
Setting up syncthing (2.1.7) ...

10.2 syncthing generate 报错 unexpected argument

现象（v1 时代的位置参数写法在 v2 报错）：

syncthing: error: unexpected argument /root/.local/state/syncthing

继续用 v2 新写法 --config 时又报：

syncthing: error: either both or none of --config and --data must be given, use --home to set both at once

定位：v2 把配置目录（config，存 config.xml 与证书）与数据目录（data，存 index 数据库与日志）概念拆开，--config 与 --data 必须成对出现。

解决：一次性指定两者用 --home（见 8.3 节），命令实测成功。

10.3 systemd 状态里出现单元文件解析警告

现象：journalctl -u syncthing@root 首屏出现两条 systemd 警告：

systemd[1]: /lib/systemd/system/syncthing@.service:115: Failed to parse boolean value, ignoring: disconnected
systemd[1]: /lib/systemd/system/syncthing@.service:123: Unknown key name 'PrivatePIDs' in section 'Service', ignoring.

定位：官方 deb 的单元文件为最新 systemd 编写，ProtectSystem=disconnected 布尔写法与 PrivatePIDs= 键是更高版本 systemd 的能力，Ubuntu 22.04 自带 systemd 249（systemctl --version 首行 systemd 249 (249.11-0ubuntu3.22)）不认识。

解决：无需处理——警告为「ignoring」，服务正常 active (running)，仅牺牲部分新版沙箱加固能力；升级到 24.04+ 的 systemd 后自然消失。

10.4 日志提示 QUIC 接收缓冲区不足

现象：首启日志出现：

failed to sufficiently increase receive buffer size (was: 208 kiB, wanted: 7168 kiB, got: 416 kiB). See https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes for details.

定位：QUIC 传输期望 7 MiB 接收缓冲以获得最佳吞吐，内核默认值偏小。官方 deb 已自带调优文件 /usr/lib/sysctl.d/30-syncthing.conf，实测内容：

# Increase maximum socket buffer sizes to 7MiB for QUIC connections
# see https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes
net.core.rmem_max = 7340032
net.core.wmem_max = 7340032

解决：该配置由 systemd-sysctl 在重启后自动应用；如需立即生效可执行 sysctl --system，再次核验：

sysctl net.core.rmem_max

实测回显：

net.core.rmem_max = 7340032

该警告仅影响 QUIC 吞吐上限，不影响功能可用性。

10.5 tar.gz 方案改用 --gui-address 端口探测失败？

syncthing 首次启动会探测 GUI 端口与同步端口是否空闲，受限环境可加 --no-port-probing（环境变量 STNOPORTPROBING）跳过探测（来源：syncthing serve --help 实测原文 "Don't try to find free ports for GUI and listen addresses on first startup"）。端口被占用时 Syncthing 会自动尝试下一个可用端口并在日志提示，排查时先看日志 GUI and API listening (address=...) 的实际地址。

十一、升级、降级与卸载清理

11.1 升级

方案 A 升级随系统包管理器：

apt-get update && apt-get upgrade syncthing

方案 B/C 下载新版 deb/tar.gz 覆盖安装即可；deb 实测覆盖升级回显见 10.1（Unpacking syncthing (2.1.7) over (1.30.0)）。升级后重启服务：

systemctl restart syncthing@root
syncthing --version

⚠️ apt 源的 deb 默认打 noupgrade 标记（syncthing --version 回显可见），即禁用 GUI 内的自动升级，统一交给包管理器管理，避免双通道升级互相覆盖。

11.2 卸载与残留清理

方案 A/B 卸载软件包（--purge 连同系统配置一并删除）：

apt-get remove --purge -y syncthing

实测回显（输出节选）：

Removing syncthing (2.1.7) ...

用户级运行数据（配置、证书、索引数据库）在运行用户目录下，需手动删除：

rm -rf /root/.local/state/syncthing

方案 C 额外清理二进制目录与手写 unit：

systemctl disable --now syncthing.service
rm /etc/systemd/system/syncthing.service
systemctl daemon-reload
rm -rf /opt/syncthing-linux-amd64-v2.1.7

十二、参考链接

  1. 官方下载页（apt 源与各平台包）：https://syncthing.net/downloads/
  2. 官方文档 systemd 说明：https://docs.syncthing.net/users/autostart.html
  3. 官方防火墙端口说明：https://docs.syncthing.net/users/firewall.html
  4. GitHub Releases（v2.1.7 资产与校验）：https://github.com/syncthing/syncthing/releases/tag/v2.1.7
  5. 本专栏认知篇：《Syncthing 介绍与选型指南》
  6. 本专栏配置篇：《Syncthing 2.1.7 配置参数详解》
  7. 本专栏命令篇：《Syncthing 2.1.7 常用 CLI 命令与工具详解》