Syncthing Web界面：GUI操作完全手册

2026-02-05 05:07:14作者：钟日瑜

1. 界面概览与访问配置

1.1 默认访问方式

Syncthing Web界面（Graphical User Interface，图形用户界面）默认通过127.0.0.1:8384地址访问，采用HTTP协议传输。首次启动后会自动打开浏览器窗口，显示主控制台界面。界面布局包含五大核心区域：

flowchart TD
    A[顶部导航栏] -->|系统状态| B[仪表盘]
    A -->|核心功能| C[文件夹管理]
    A -->|设备管理| D[远程设备]
    A -->|高级设置| E[操作面板]
    F[左侧状态栏] -->|快速访问| G[设备ID/连接状态]
    F -->|系统信息| H[CPU/内存占用]
    I[中央内容区] -->|上下文切换| B & C & D & E
    J[底部状态栏] -->|全局状态| K[同步进度/错误提示]

1.2 访问控制配置

通过config.xml文件或环境变量可修改访问参数，核心配置项如下：

参数名	环境变量替代	默认值	说明
`address`	`STGUIADDRESS`	`127.0.0.1:8384`	监听地址，支持`unix:///path/to/socket`格式的Unix套接字
`useTLS`	-	`false`	启用HTTPS加密（需配合`https-cert.pem`证书文件）
`unixSocketPermissions`	-	`0700`	Unix套接字文件权限（八进制表示）
`insecureAdminAccess`	-	`false`	允许远程访问（禁用时仅本地回环地址可访问）

示例：允许局域网访问
修改配置文件或设置环境变量：

export STGUIADDRESS="0.0.0.0:8384"  # 绑定所有网络接口

2. 用户认证与安全设置

2.1 密码保护配置

Web界面支持两种认证模式，通过GUIConfiguration结构体控制：

本地密码认证
需同时设置user和password字段，密码会自动使用bcrypt算法哈希存储：

<gui enabled="true" tls="true">
    <address>127.0.0.1:8384</address>
    <user>admin</user>
    <password>$2a$10$VQx8t5c7h8Z3LczQV6E9UeX8qQZ7QZ7QZ7QZ7QZ7QZ7QZ7QZ7QZ</password>
    <authMode>hash</authMode>
</gui>

LDAP集成认证
设置authMode="ldap"并配置LDAP服务器参数（企业环境适用）：

<ldap>
    <address>ldap://company-domain.com:389</address>
    <bindDN>cn=admin,dc=company,dc=com</bindDN>
    <bindPassword>secret</bindPassword>
    <userBaseDN>ou=users,dc=company,dc=com</userBaseDN>
    <userFilter>(uid=%s)</userFilter>
</ldap>

2.2 API访问控制

通过apiKey实现无界面访问授权，在请求头中携带认证信息：

curl -H "X-API-Key: k1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1" \
  http://127.0.0.1:8384/rest/system/status

安全提示：API密钥长度为32位随机字符串，可通过STGUIAPIKEY环境变量覆盖配置文件值。

3. 文件夹管理核心操作

3.1 文件夹创建向导

通过"添加文件夹"向导配置同步目录，关键参数说明：

sequenceDiagram
    participant User
    participant GUI
    participant Config

    User->>GUI: 点击"添加文件夹"按钮
    GUI->>User: 显示创建表单
    User->>GUI: 输入ID/标签/路径
    User->>GUI: 选择同步类型(sendreceive/sendonly/receiveonly)
    GUI->>Config: 验证路径可写性
    Config-->>GUI: 返回验证结果
    User->>GUI: 选择关联设备
    GUI->>Config: 生成<folder>配置节点
    Config-->>GUI: 返回创建成功提示

同步类型区别：

sendreceive（默认）：双向同步，本地修改会传播到远程
sendonly：仅发送本地变更，忽略远程修改
receiveonly：仅接收远程变更，本地修改需手动确认（通过"覆盖更改"按钮）

3.2 高级文件夹设置

在文件夹编辑界面展开"高级选项"可配置高级参数，常用项包括：

分类	参数名	默认值	优化建议
监控	`fsWatcherEnabled`	`true`	SSD建议启用，网络文件系统建议禁用
性能	`hashers`	`0`（自动）	机械硬盘设置为`2`，SSD设置为CPU核心数一半
冲突处理	`maxConflicts`	`10`	重要数据建议设为`-1`（无限制保留冲突文件）
空间管理	`minDiskFree`	`1%`	大容量存储建议设为`5GB`绝对值

示例：配置版本控制
启用"交错式版本控制"（Staggered Versioning）：

<versioning type="staggered">
    <cleanupIntervalS>86400</cleanupIntervalS>
    <maxAgeS>31536000</maxAgeS>
    <versionsPath>.stversions</versionsPath>
    <keep>
        <period>3600</period>
        <count>24</count>
    </keep>
    <keep>
        <period>86400</period>
        <count>30</count>
    </keep>
</versioning>

4. 设备管理与连接配置

4.1 设备添加流程

添加远程设备需完成以下步骤：

获取目标设备ID（在远程设备"操作→显示ID"处查看）
点击"添加设备"按钮，输入设备ID和友好名称
配置设备地址（支持多种格式）：
- 动态发现：dynamic（默认，依赖全局/本地发现服务）
- 静态地址：tcp://192.168.1.100:22000（TCP直连）
- 中继服务器：relay://relay.example.com:22067（通过中继转发）
选择要共享的文件夹并设置权限

4.2 连接状态诊断

在设备详情页面的"连接"标签页可查看连接状态，常见问题排查：

状态图标	含义	解决方案
🟢 已连接	正常P2P连接	-
🟡 正在连接	正在尝试建立连接	检查防火墙是否放行22000端口（TCP/UDP）
🔴 未连接	连接失败超过5分钟	启用中继服务（`relaysEnabled="true"`）或配置端口转发
⚠️ 降级连接	使用中继而非直连	在路由器配置UPnP或手动端口转发，NAT类型为"完全锥型"最佳

网络诊断命令：

# 检查端口可达性
nc -zv remote-device-ip 22000
# 查看Syncthing连接日志
grep -i "connection established" ~/.local/state/syncthing/syncthing.log

5. 系统监控与性能优化

5.1 仪表盘指标解读

主界面仪表盘显示关键性能指标，需关注：

同步进度条：绿色表示已同步，黄色表示同步中，红色表示错误
系统负载：CPU占用超过80%会导致同步延迟
内存使用：索引数据库大小通常为同步文件总量的1-2%
网络流量：发送/接收速率应匹配网络带宽（可在"设置→连接"中配置限速）

5.2 性能调优参数

通过"操作→设置→性能"调整系统参数，针对不同场景优化：

场景	优化参数组合
大型文件（>1GB）	`blockPullOrder="inOrder"` `copyRangeMethod="standard"`
大量小文件（<10KB）	`hashers="4"` `copiers="2"` `fsWatcherDelayS="30"`
低带宽网络	`maxSendKbps="1024"` `limitBandwidthInLan="false"`
资源受限设备（NAS）	`setLowPriority="true"` `maxFolderConcurrency="1"`

配置示例：通过API应用性能配置

curl -X PATCH -H "X-API-Key: $STGUIAPIKEY" -H "Content-Type: application/json" \
  http://localhost:8384/rest/system/config \
  -d '{"options":{"hashers":4,"copiers":2,"maxFolderConcurrency":2}}'

6. 故障排除与常见问题

6.1 界面访问故障

错误现象	可能原因	解决步骤
拒绝连接（ERR_CONNECTION_REFUSED）	Syncthing未运行或端口被占用	1. `pgrep syncthing`检查进程 2. 检查`STGUIADDRESS`是否被占用
证书错误（NET::ERR_CERT_INVALID）	HTTPS证书自签名或过期	1. 清除浏览器缓存 2. 重新生成证书：`rm ~/.local/state/syncthing/https-*.pem`
401未授权	密码错误或API密钥失效	1. 重置密码：`syncthing cli config gui.user set admin && syncthing cli config gui.password set newpass`

6.2 同步错误处理

常见同步错误及解决方法：

"文件被锁定"错误：关闭占用文件的应用程序，或配置copyRangeMethod="fallback"
"权限被拒绝"错误：检查文件夹权限（至少需要rwx权限），设置ignorePerms="true"
"设备已断开连接"：在防火墙开放22000/TCP、21027/UDP端口，启用"本地发现"

高级诊断：启用调试日志

syncthing --logflags=0x7fffffff > debug.log 2>&1
# 日志包含连接握手、索引交换和文件传输详细信息

7. 高级功能与自定义

7.1 命令行界面（CLI）集成

Syncthing提供CLI工具与Web界面协同工作，常用命令：

# 查看系统状态
syncthing cli system status

# 暂停文件夹同步
syncthing cli folders pause my-folder-id

# 导出配置
syncthing cli config export > backup-config.xml

7.2 主题定制与界面扩展

通过theme参数切换内置主题（default/dark/light/black），或通过自定义CSS扩展：

创建~/.config/syncthing/custom.css

添加自定义样式：

/* 调整导航栏颜色 */
.navbar { background-color: #2c3e50 !important; }
/* 增大字体 */
body { font-size: 14px !important; }

在"设置→界面"中启用"自定义CSS"

8. 自动化与集成

8.1 REST API使用示例

通过API实现自动化操作，Python示例：

import requests

API_KEY = "your-api-key"
BASE_URL = "http://localhost:8384/rest"

def get_sync_status():
    headers = {"X-API-Key": API_KEY}
    response = requests.get(f"{BASE_URL}/system/status", headers=headers)
    return response.json()

def restart_syncthing():
    headers = {"X-API-Key": API_KEY}
    requests.post(f"{BASE_URL}/system/restart", headers=headers)

if __name__ == "__main__":
    status = get_sync_status()
    print(f"Current sync completion: {status['syncCompletion']}%")
    if status["connections"] == 0:
        restart_syncthing()

8.2 第三方集成

监控集成：通过Prometheus导出指标（启用metricsWithoutAuth: true）
文件管理器集成：Windows资源管理器/ macOS Finder扩展（需单独安装）
移动访问：通过insecureAdminAccess: true配合HTTPS反向代理实现手机访问

9. 配置备份与迁移

9.1 配置文件位置

不同操作系统配置文件路径：

操作系统	配置目录	数据库目录
Linux	`~/.local/state/syncthing`	同配置目录
macOS	`~/Library/Application Support/Syncthing`	同配置目录
Windows	`%LOCALAPPDATA%\Syncthing`	`%LOCALAPPDATA%\Syncthing`