腾讯云 COS 挂载实战:把 Syncthing 备份目录搬进对象存储

用 cosfs 把腾讯云 COS 挂成 Syncthing 备份目录:路径不变、数据上云。含 5 张配置截图、完整命令注释和 4 个真实踩坑记录。

服务器只有 79G 磁盘,一个 Syncthing 备份目录就吃掉 18G,可用空间掉到 23G。想扩容,最直接的办法是把备份放进腾讯云 COS;但 Syncthing 的同步路径又不能随便改,改一次要重新配所有客户端。

这篇记录一个不用改应用配置的做法:用 cosfs 把 COS 桶挂载成那个目录。同步路径不变,数据实际落在对象存储里。下面从概念、命令到踩过的坑,一步步来。

一、先弄懂三件事

  • 桶(Bucket):云端的“大抽屉”。本例是 syncthing-1259042419,地域 ap-nanjing。
  • cosfs:把桶翻译成本地目录的工具,基于 FUSE。
  • 挂载点:本地那个目录,本例 /mydata/config/Backup。
COS 挂载数据流向图
图 0:容器只认识宿主机目录,cosfs 负责把目录接到 COS

要提醒的是:挂载点被 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 步:写凭证文件

凭证文件配置
图 1:一行一个桶,写完立刻 chmod 600
# 一行一个桶。格式:桶名:SecretId:SecretKey
# 注意:文件末尾要有换行,后面再追加新桶时不会粘在一起
vim /etc/passwd-cosfs

# 收紧权限,只有 root 可读
chmod 600 /etc/passwd-cosfs
ls -l /etc/passwd-cosfs

这是 cosfs 的默认凭证来源,权限必须是 600,否则可能拒绝使用。

第 2 步:先挂到空目录试

手动挂载测试
图 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,开机自动挂

fstab 开机自启配置
图 3:照抄已有 cosfs 行的写法最稳
# 先备份,改坏了能回滚
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 容器看见

容器内验证挂载
图 4:宿主机挂载后必须重启容器
# 宿主机新挂载不会自动传进已运行的容器
# 必须重启一次,容器才会重新解析 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:宝塔面板点“计算大小”把自己卡死

宝塔面板卡死排查
图 5:内核栈直指 fuse_readdir,请求日志显示 GetDirSize

面板文件管理对 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_size1000 → 20000减少重复 stat 回源
stat_cache_expire无 → 60 秒给元数据陈旧设上限
use_cache关闭(清掉 108M 缓存)避免缓存涨到 18G 撑爆磁盘
rescanIntervalS3600 → 7200降低全量扫描频率

3. 实测数据

时间loadcosfs CPU说明
17:202.71162%调优前
17:322.62154%调优后 3 分钟
18:093.55160%首扫进行中
18:402.5592%首扫完成
19:203.0990%重扫循环中
19:303.15164%(瞬时)仍在扫

结论: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 CPU160% 左右90% 左右(周期性冲高)
目录读取每次 stat 回源命中便签本,明显变快
磁盘可用23G23G(不再被缓存侵蚀)

诚实地说:这套配置解决的是“重复回源”和“磁盘被缓存吃掉”,不能解决第十节那种重扫循环。那是另一个层面的问题,别指望一个参数包治百病。

7. 谁适合这么配

  • 适合:备份目录、归档、冷数据、磁盘不富裕的机器
  • 不适合:大量小文件的高并发业务、要求秒级同步的场景
  • 记住:挂载成功只是开始,稳定运行要看负载和磁盘的长期曲线

Docker部署免费开源同步工具Syncthing:https://www.hao0564.com/3123.html

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注