服务器只有 79G 磁盘,一个 Syncthing 备份目录就吃掉 18G,可用空间掉到 23G。想扩容,最直接的办法是把备份放进腾讯云 COS;但 Syncthing 的同步路径又不能随便改,改一次要重新配所有客户端。
这篇记录一个不用改应用配置的做法:用 cosfs 把 COS 桶挂载成那个目录。同步路径不变,数据实际落在对象存储里。下面从概念、命令到踩过的坑,一步步来。
一、先弄懂三件事
- 桶(Bucket):云端的“大抽屉”。本例是 syncthing-1259042419,地域 ap-nanjing。
- cosfs:把桶翻译成本地目录的工具,基于 FUSE。
- 挂载点:本地那个目录,本例 /mydata/config/Backup。

要提醒的是:挂载点被 COS 接管后,原来目录里的文件不会删除,但会被“盖住”看不见。生产环境一定要先备份或改名保留。
二、准备工作
1. 安装 cosfs
# Debian/Ubuntu 先装编译依赖
apt-get update
apt-get install -y fuse libcurl4-openssl-dev libssl-dev libxml2-dev make g++
# 下载腾讯云 cosfs 源码后编译(版本号以官方最新为准)
./configure
make
make install
# 验证
cosfs --version
部分镜像已经自带 cosfs(本例是 1.0.21),先执行 cosfs --version 看有没有,有就跳过。
2. 准备密钥(别用主账号)
腾讯云控制台 → 访问管理 → API 密钥。建议新建子账号,只授予这个桶的读写权限。拿到 SecretId / SecretKey 后写进服务器本地文件,不要贴在命令历史或脚本参数里。
3. 建桶、记地域
地域决定 endpoint,例如 ap-nanjing 对应 cos.ap-nanjing.myqcloud.com。地域写错会报桶不存在或签名错误。
三、五步把桶挂上去
第 1 步:写凭证文件

# 一行一个桶。格式:桶名:SecretId:SecretKey
# 注意:文件末尾要有换行,后面再追加新桶时不会粘在一起
vim /etc/passwd-cosfs
# 收紧权限,只有 root 可读
chmod 600 /etc/passwd-cosfs
ls -l /etc/passwd-cosfs
这是 cosfs 的默认凭证来源,权限必须是 600,否则可能拒绝使用。
第 2 步:先挂到空目录试

# 用临时目录测试,确认没问题再动生产路径
mkdir -p /mnt/costest
cosfs syncthing-1259042419 /mnt/costest \
-o allow_other,url=https://cos.ap-nanjing.myqcloud.com,uid=0,gid=0,umask=000
# 三个检查:挂上了吗、容量对吗、能读吗
mountpoint -q /mnt/costest && echo MOUNT_OK
df -h /mnt/costest | tail -1
ls -1A /mnt/costest | head
# 测试完先卸载
fusermount -u /mnt/costest
df 显示 256T 是 COS 的理论上限,不是真实占用,别被吓到。
第 3 步:写进 fstab,开机自动挂

# 先备份,改坏了能回滚
cp -a /etc/fstab /etc/fstab.bak-$(date +%F)
# 末尾追加一行
# 字段:cosfs#桶名 挂载点 fuse 选项 0 0
cosfs#syncthing-1259042419 /mydata/config/Backup fuse _netdev,allow_other,url=https://cos.ap-nanjing.myqcloud.com,uid=0,gid=0,umask=000 0 0
# 验证:卸载后按 fstab 重新挂,返回 0 才算成功
umount /mydata/config/Backup
mount /mydata/config/Backup
echo $?
_netdev 表示等网络就绪再挂载,云主机必备。追加前确认上一行有换行符,这是最容易翻车的地方。
第 4 步:让 Docker 容器看见

# 宿主机新挂载不会自动传进已运行的容器
# 必须重启一次,容器才会重新解析 bind mount
docker restart syncthing
# 从容器内部确认
docker exec syncthing ls -1A /config/Backup
原理是 Docker 默认 rprivate 挂载传播:容器启动时拿到当时的挂载视图,宿主机后来加的挂载它看不见。
第 5 步:数据先对齐,再切换(关键)
如果目录里已经有数据,直接换成空桶会让 Syncthing 认为“文件全被删了”,并把删除同步给其他设备。正确顺序是先上传、核对、再替换:
# 1) 用 rclone 把本地数据原样传到桶里(保留修改时间)
rclone copy /mydata/config/Backup/ cos:syncthing-1259042419/ --transfers 16 --checkers 32
# 2) 对比对象数和总大小,必须一致
rclone size cos:syncthing-1259042419
# 3) 数量一致后:停容器 → 旧目录改名 → 建空目录 → 挂载 → 起容器
docker stop syncthing
mv /mydata/config/Backup /mydata/config/Backup.local-$(date +%F)
mkdir -p /mydata/config/Backup
mount /mydata/config/Backup
docker start syncthing
旧目录别急着删,它就是你的回滚点。
四、举一反三
同样的套路可以套到很多目录,只要应用能接受“文件在本地目录里”这个前提:
| 场景 | 挂什么 | 建议选项 |
|---|---|---|
| 网站附件目录 | 图片/附件桶 | 读多写少,可加 use_cache |
| Nextcloud 数据目录 | 用户文件桶 | 小文件多,注意 stat 性能 |
| 数据库备份 | 归档桶 | 只读挂载 -o ro |
| 日志归档 | 历史日志桶 | 按日期分前缀,定期清理 |
# 只读挂载:适合归档、审计,防止误删
cosfs archive-1259042419 /mnt/archive \
-o ro,allow_other,url=https://cos.ap-nanjing.myqcloud.com
五、四个真实的坑
坑 1:文件末尾没有换行
/etc/passwd-cosfs 和 /etc/fstab 都可能没有结尾换行。直接追加会把新内容粘到最后一行末尾,变成一行五个字段:
# 错误示范:追加后变成 huhouting...0 0syncthing-...
echo "syncthing-1259042419:..." >> /etc/passwd-cosfs
# 正确做法:先补一个换行
[ -n "$(tail -c1 /etc/passwd-cosfs)" ] && echo >> /etc/passwd-cosfs
echo "syncthing-1259042419:..." >> /etc/passwd-cosfs
症状分别是 cosfs 报 could not establish security credentials,以及 mount 报 fstab parse error。
坑 2:ensure_diskfree 误报空间不足
加了 ensure_diskfree=2048 后 cosfs 直接报 no enough disk space,但磁盘明明还剩 23G。这台机器上该参数判断不准,去掉即可;需要限制缓存就换个小一点的值再测。
坑 3:同步目录直接换空 = 删除传播
Syncthing 的 sendreceive 文件夹发现本地文件消失,会把“删除”当成一次变更同步给所有节点。所以必须先上传对齐,再替换挂载点;稳妥的话还可以先暂停文件夹,确认无误再恢复。
坑 4:宝塔面板点“计算大小”把自己卡死

面板文件管理对 COS 目录执行 GetDirSize,会递归遍历几千个文件,每个 stat 都是一次 HTTPS 请求。宝塔单线程处理请求,一个卡住整个面板就没响应了——端口能连、页面一直转圈。排查看进程内核栈:
cat /proc/$(pgrep -f panel/BT-Panel | head -1)/stack
# 输出停在 fuse_readdir,说明卡在挂载目录上
# 重启面板恢复,之后别对大目录点“计算大小”
/etc/init.d/bt restart
六、验证清单
- mountpoint -q 路径 返回成功
- mount | grep 桶名 能看到 fuse.cosfs
- df -h 挂载点 有容量
- 重启后依然挂载(或 mount -a 验证)
- 容器内 ls 能看到目录
- 写入测试:touch 一个文件再删掉,确认可写
- 应用日志无 I/O 错误
七、成本与性能
- COS 按存储量 + 请求次数计费,小文件多时请求费不可忽视。
- FUSE 性能远不如本地盘,适合备份、归档、冷数据,不适合高并发数据库。
- 重要数据仍要有版本控制或多副本,挂载成功不等于备份可靠。
本次环境:Debian 12 / cosfs 1.0.21 / Docker 29.6.1 / Syncthing(linuxserver 镜像)/ 腾讯云 COS ap-nanjing。整套流程在 18G、38,987 个文件的真实目录上跑通,容器内校验、fstab 重挂、面板恢复均已验证。
八、上线后的真实数据:调优没有一次到位
挂载上线后连续观察了两个多小时,把实测数据补在这里。这部分比命令更值钱——它说明“挂上了”和“跑得顺”是两件事。
1. 首轮扫描:18:11–18:36 完成
18:11:23 Completed initial scan jbwh6-7nazi(32k 文件)
18:12:16 Completed initial scan 华三HCL实验(504)
18:12:24 Completed initial scan zav3k-sunjy(6008)
18:36:07 Completed initial scan tmgak-pkpvp(475)
四个文件夹 need=0、errors=0,没有删除事件,数据是齐的。
2. 做了哪些调优
| 参数 | 调整 | 目的 |
|---|---|---|
| max_stat_cache_size | 1000 → 20000 | 减少重复 stat 回源 |
| stat_cache_expire | 无 → 60 秒 | 给元数据陈旧设上限 |
| use_cache | 关闭(清掉 108M 缓存) | 避免缓存涨到 18G 撑爆磁盘 |
| rescanIntervalS | 3600 → 7200 | 降低全量扫描频率 |
3. 实测数据
| 时间 | load | cosfs CPU | 说明 |
|---|---|---|---|
| 17:20 | 2.71 | 162% | 调优前 |
| 17:32 | 2.62 | 154% | 调优后 3 分钟 |
| 18:09 | 3.55 | 160% | 首扫进行中 |
| 18:40 | 2.55 | 92% | 首扫完成 |
| 19:20 | 3.09 | 90% | 重扫循环中 |
| 19:30 | 3.15 | 164%(瞬时) | 仍在扫 |
结论:CPU 从 160% 降到 90% 左右,但离“轻松”还很远,而且会周期性冲高。
4. 发现的问题:扫描完成了,却停不下来
19:29 再查,三个文件夹仍在 scanning,其中最大的 jbwh6-7nazi 从 18:12 一直扫到 19:29,整整 77 分钟。这不是首次扫描该有的时长,而是被反复触发的重扫。
jbwh6-7nazi scanning need=0 err=0
zav3k-sunjy scanning need=0 err=0
华三HCL实验 scan-waiting need=0 err=0
tmgak-pkpvp idle need=0 err=0
5. 原因判断:FUSE 上的 fsWatcher 循环
定时扫描已经改成 2 小时一次,所以不是它。更可疑的是文件监听:
- cosfs 的 mtime 只到秒级精度,Syncthing 扫描时容易反复判定“文件变了”
- 判定变化 → 写元数据 → 触发 watcher 事件 → 再扫一遍
- 本地盘上这个循环瞬间收敛,FUSE 上会拖很久
6. 可选的收尾方案
| 方案 | 做法 | 代价 |
|---|---|---|
| A(推荐) | 关闭 4 个文件夹的 fsWatcher,rescan 降到 1800 秒 | 变化最多晚 30 分钟发现 |
| B | 只关 watcher,保持 7200 秒 | 最坏 2 小时才发现变化 |
| C | 先不动,观察 20:11 定时扫描前后的行为 | 负载继续偏高 |
7. 阶段性结论
数据正确性没有问题(need=0、errors=0、零删除事件),问题集中在性能:cosfs 在替每一次文件操作翻译成 HTTPS 请求,而 Syncthing 的重扫放大了这个成本。下一步优先做隔离验证——依次暂停单个大文件夹,确认是谁在拖,再决定是否关 watcher。本文会随处理结果更新。
九、推荐配置:A + B2,最稳的一套
先说清楚:这里的 A / B2 指“缓存参数”的两个选择,和第八节讨论 fsWatcher 的 A / B / C 不是一回事,别混。
1. 用大白话讲清楚“回源”
cosfs 挂载的目录看起来在本地,其实每个文件的大小、修改时间都存在云端。程序每问一次“这个文件多大”,cosfs 就得跑去 COS 问一次——这就叫回源。
平时感觉不到,因为一次往返只要几十毫秒。但 Syncthing 扫描目录时要问 3.8 万次,等于跑了 3.8 万趟仓库,CPU 和时间都耗在路上了。
2. A:给 cosfs 配一个“便签本”
max_stat_cache_size 就是便签本的大小。默认只记 1000 条,扫到第 1001 个文件时,前面的记录已经被挤掉了,下次还得重新问。
# 记 2 万条,够覆盖大部分重复访问
max_stat_cache_size=20000
# 便签 60 秒后作废,防止记到过期的信息
stat_cache_expire=60
白话理解:先把问过的答案记下来,下次先翻本子;但本子只保存 1 分钟,过期重问。
代价:如果别的程序绕过这个挂载点直接改桶里的文件,最多晚 60 秒才会被发现。对备份场景完全够用。
3. B2:不开“内容缓存”
先回答一个容易搞混的问题:这个缓存是 cosfs 的,不是 Syncthing 的。
打个比方:
· Syncthing 是那个“反复开箱验货的人”,它要确认文件没坏,就得把文件从头到尾读一遍;
· cosfs 是“快递代收点”,每次有人来取货,它就去 COS 把货搬过来;
· use_cache 相当于代收点说:“这箱货我留一份在店里,下次你来直接拿。”——留的那份占的是你服务器的磁盘。
所以:缓存动作是 cosfs 做的,缓存文件躺在本地磁盘;Syncthing 只是那个不断来取货、把缓存撑大的“客户”。Syncthing 自己并不保存文件副本,它保存的是索引数据库(记录“哪个文件、多大、什么哈希”),和这里的缓存完全是两码事。
use_cache 缓存的是文件内容,不是文件信息。读过一次的文件会在 use_cache= 指定的目录里留一份完整拷贝。
听起来很美,但 Syncthing 校验文件要读全文:18G 的备份目录,缓存可能一路涨到 18G,而这台机器当时只剩 23G。真涨满了,面板、数据库、Docker 会一起出问题。
# 推荐:不写 use_cache,只直读不落盘
# 如果确实需要,至少配上磁盘下限,别让它无限长
# ensure_diskfree=2048 # 本机实测会误报空间不足,慎用
白话理解:宁可每次多跑一趟仓库,也不在自家客厅堆 18G 的货。
4. 三个选择对比
| 组合 | 做法 | 优点 | 代价 |
|---|---|---|---|
| A + B2(推荐) | 记 2 万条文件信息,不缓存内容 | 目录读取快、磁盘安全 | 重复读会重复回源;元数据最多陈旧 60 秒 |
| A + B1 | 记 2 万条,同时缓存内容 | 重复读更快 | 缓存会持续涨,有撑爆磁盘风险 |
| 只做 B2 | 只关内容缓存 | 最省事 | 目录扫描依旧慢,CPU 下不来 |
5. 完整配置长这样
# /etc/fstab 里的一行(注意:不要带 use_cache)
cosfs#你的桶名 /你的挂载点 fuse _netdev,allow_other,url=https://cos.地域.myqcloud.com,uid=0,gid=0,umask=000,max_stat_cache_size=20000,stat_cache_expire=60 0 0
已经有挂载在跑的,改完按下面顺序换上去:
# 1) 先停容器,避免卸载时被占用
docker stop syncthing
# 2) 卸载旧挂载
umount /你的挂载点
# 3) 改 fstab(先备份!)
cp -a /etc/fstab /etc/fstab.bak-$(date +%F)
# 4) 按新参数挂回来,返回 0 才算成功
mount /你的挂载点
echo $?
# 5) 旧的内容缓存目录可以删了(本例释放了 108M)
rm -rf /mydata/.cosfs-cache
# 6) 起容器,让它重新解析挂载
docker start syncthing
# 7) 验证:进程参数里能看到两个新选项
ps -eo args | grep '[c]osfs 你的桶名'
docker exec syncthing ls -1A /容器内路径 | head
6. 实测效果(18G / 38,987 个文件)
| 指标 | 调整前 | 调整后 |
|---|---|---|
| 本地内容缓存 | 105M 且持续增长 | 0(目录已删除) |
| cosfs CPU | 160% 左右 | 90% 左右(周期性冲高) |
| 目录读取 | 每次 stat 回源 | 命中便签本,明显变快 |
| 磁盘可用 | 23G | 23G(不再被缓存侵蚀) |
诚实地说:这套配置解决的是“重复回源”和“磁盘被缓存吃掉”,不能解决第十节那种重扫循环。那是另一个层面的问题,别指望一个参数包治百病。
7. 谁适合这么配
- 适合:备份目录、归档、冷数据、磁盘不富裕的机器
- 不适合:大量小文件的高并发业务、要求秒级同步的场景
- 记住:挂载成功只是开始,稳定运行要看负载和磁盘的长期曲线
Docker部署免费开源同步工具Syncthing:https://www.hao0564.com/3123.html
