gsyncd 是 lsyncd 的 Go 重写版:一个单文件静态二进制、零系统依赖的实时目录镜像守护进程。默认后端自己拷贝文件,不依赖 Lua、rsync 或 ssh;也支持可选的 rsync / rsyncssh 后端。
$ gsyncd -version
gsyncd 0.5.2 (1.23.5)
- 递归 inotify 监视(Linux);其它平台使用快照轮询
- 事件聚合、
delay静默窗口(可选 lsyncd 风格的deadline)、max_hold强制刷新、可选close_write - direct 元数据保真:完整 mode、owner(root)、文件/目录 mtime、符号链接策略;可选 xattr/ACL、硬链接、稀疏、特殊文件
- 启动全量同步;
checkpoint断点续扫,重启不重扫目标端 - SIGHUP 优雅重载:排空在途批次后以同一 pid 重新执行,配置变更无需重启
rsyncssh的 move/delete 在远端本地执行(ssh),目录 rename 不重传- 原子替换:临时文件 → fsync(大文件)→ rename
- 删除、重命名、排除规则;目录删除/重建和 rename 语义已加固
- 传输时 SHA-256 内容校验(默认开启);
-verify-tree/-verify-content离线校验 - 目标守卫:目标未挂载/不存在时拒绝写入;运行期目标被移走也拒绝写入
- 特殊文件(FIFO/socket/device)跳过;符号链接仅保留指向同步根内部的链接
- 有界聚合窗口(软上限 + 硬上限)、退避重试、ENOSPC 快速失败
# gsyncd.toml
[global]
log_file = "/var/log/gsyncd.log"
log_level = "info"
status_file = "/var/lib/gsyncd/status.json"
max_processes = 8
[[sync]]
name = "data"
source = "/srv/data"
target = "/backup/data"
mode = "direct"
delay = 15
delete = true
excludes = ["*.tmp", "/cache/"]# 目标盘必须先挂载;首次部署写一次 marker
gsyncd -config gsyncd.toml -init-target
gsyncd -config gsyncd.toml -check
gsyncd -config gsyncd.toml -nodaemon # 前台运行(systemd 推荐)
gsyncd -config gsyncd.toml # 后台运行
gsyncd -config gsyncd.toml -once # 只做一次全量后退出
gsyncd -status /var/lib/gsyncd/status.json| 参数 | 说明 |
|---|---|
-config PATH |
TOML 配置文件(必填,-version/-status 除外) |
-logfile PATH |
覆盖配置里的 log_file |
-loglevel L |
debug | info | warn | error | none |
-pidfile PATH |
覆盖 pid_file |
-statusfile PATH |
覆盖 status_file |
-nodaemon |
前台运行 |
-once |
只做初始全量同步后退出 |
-status PATH |
打印状态文件并退出 |
-check |
校验配置(含不属于当前 mode 的键)、源目录和目标守卫后退出,不启动同步 |
-init-target |
向每个本地目标写入 .gsyncd-target marker 后退出;目标必须已存在 |
-verify-tree |
只读对比源/目标目录树和文件集合;有差异时退出码非 0 |
-verify-content |
对比源/目标文件的 SHA-256、大小、mtime;有差异时退出码非 0 |
-verify-sample N |
配合 -verify-content:按路径确定性抽取 N% 文件(0/100 = 全部) |
-verify-workers N |
配合 -verify-content:并发哈希数(0 = min(CPU,16)) |
-watch-interval D |
非 Linux 轮询间隔 |
-full-resync D |
周期性全量重同步间隔;-1 表示沿用配置 |
-version |
打印版本 |
-verify-content 会临时写一个探测文件判断目标文件系统的时间戳精度,随后删除。
| 键 | 默认 | 说明 |
|---|---|---|
log_file |
""(stderr) |
日志文件 |
log_level |
info |
日志级别 |
log_max_size |
104857600 |
单个日志上限(字节) |
log_max_files |
5 |
日志保留份数 |
pid_file |
"" |
pid 文件 |
status_file |
"" |
JSON 状态文件(原子替换) |
status_interval |
10s |
状态刷新间隔 |
max_processes |
8 |
全局并发传输闸 |
max_pending |
500000 |
聚合窗口软上限;达到即提前发送 |
max_pending_hard |
2000000 |
聚合窗口硬上限;超过后丢弃新事件并全量恢复 |
watch_interval |
30s |
非 Linux 轮询间隔 |
full_resync |
0 |
周期全量间隔;0 表示仅在 watch 装不下时自动启用 |
memory_limit |
0 |
Go 堆软上限,支持 512m/1g |
nice |
0 |
CPU nice 值 |
io_prio |
"" |
idle / best-effort / realtime,可带级别 |
target_guard |
true |
目标必须已存在且在非 / 挂载点或带 marker;否则拒绝启动 |
全局键对所有 [[sync]] 生效;target_guard 对远端目标(rsync 的 host:path、rsyncssh)自动跳过。
| 键 | 默认 | 说明 |
|---|---|---|
name |
源目录 basename | 日志/状态标识 |
source |
— | 被监视的本地目录 |
mode |
direct |
direct | rsync | rsyncssh |
target |
— | 目标写法随 mode 变化,见下方“目标写法” |
delay |
15s |
事件静默多久后传输 |
delay_mode |
"quiet" |
"quiet" 整树静默后刷;"deadline" 最早事件满 delay 即刷(lsyncd 语义) |
max_hold |
15m |
持续写入时最多等多久强制刷新;负值关闭 |
close_write |
false |
等待 writer 关闭后再同步 |
delete |
true |
true/false/"startup"/"running" |
excludes |
[] |
rsync 风格排除模式 |
exclude_from |
[] |
排除规则文件(相对配置文件目录),文件规则在前、内联规则在后 |
symlink_mode |
"safe" |
"safe" 仅根内链接;"all" 原样复制;"skip";三种后端都支持。注意 mode="rsync" 的 safe 使用 --safe-links,会丢弃所有绝对链接(包括解析在源根内的),比 direct 更严格 |
bandwidth_limit |
0 |
direct 复制限速(字节/秒);rsync/rsyncssh 在未设置 rsync_bwlimit 时作为回退 |
full_resync |
0 |
本 sync 的周期全量;0 继承全局 |
max_processes |
0(用全局) | 该 sync 的并发上限 |
mode |
target |
target_dir |
|---|---|---|
direct |
本地目录或已挂载的 NFS 路径 | 不使用 |
rsync |
本地目录,或 host:path / host::module / rsync://... |
不使用 |
rsyncssh |
远端主机(仅 host 或 user@host,不能含路径或冒号) |
远端目标目录 |
以下键只在 mode = "direct" 下生效;配在 rsync/rsyncssh 下会在解析配置时直接报错,进程不会启动(-check 退出码非 0)。
| 键 | 默认 | 说明 |
|---|---|---|
preserve_mode |
"full" |
"full" 保留 setuid/setgid/sticky;"basic" 仅 0777 |
preserve_owner |
"auto" |
"auto" 仅 root 时 chown;true/false |
preserve_xattrs |
false |
Linux xattr(含 POSIX ACL),尽力而为 |
preserve_hardlinks |
false |
单次初始扫描内重建硬链接 |
sparse |
false |
Linux 稀疏文件 |
copy_special |
false |
Linux FIFO/设备节点(设备节点需要 root) |
workers |
min(CPU,16) |
并行拷贝 goroutine 数 |
prefetch |
min(CPU,16) |
初始遍历预读目录的 goroutine 数 |
checkpoint |
"" |
断点续扫记录文件;"auto" 自动选目录。只加速重启,不替代校验:目标端原地篡改(不改变父目录 mtime)不会被发现,需要时定期跑 -verify-content |
fsync |
false |
每个文件 rename 前 fsync |
verify |
true |
传输时 SHA-256 校验 |
verify_retries |
2 |
校验失败后的额外重拷次数 |
source必须本身是真实目录;根路径是 symlink 时直接拒绝,请写解析后的路径(避免 safe 模式被绕过、目标根被清空)。- 同一表内重复键、以及
exclude/excludes、rsync_opts/rsync_extra这类别名同时出现,会报错,不再由 map 顺序决定谁生效。 [[global]]是错误写法,必须是单个[global]。- 时长/大小字符串必须能被完整解析:
"1d"、"2 minutes"、"100MB"会报错(1d曾静默变成 1 秒)。 delete = "true"/"yes"与布尔true语义一致(启动 prune + 运行期删除)。rsyncssh的target只能是 host/user@host;target_dir不接受~。checkpoint记录在整轮遍历结束时统一落盘;超宽平铺目录(数万同级目录)受内存上限影响会只保留部分记录,未保留的目录下次重新核对(只影响重启速度,不影响正确性)。未完整走完的段带不上 seal,下次不会采用。
以下键只在 mode = "rsync" 或 "rsyncssh" 下生效;配在 direct 下会在解析配置时直接报错,进程不会启动。
| 键 | 默认 | 说明 |
|---|---|---|
batch_limit |
10000 |
单次 rsync 调用的最大路径数 |
remote |
自动推断 | 强制把含冒号的目标按 rsync 远端处理(可设 false 强制本地) |
rsync_extra |
[] |
追加给 rsync 的参数(rsyncopts 是兼容别名) |
rsync_binary |
rsync |
本机 rsync 可执行文件路径 |
rsync_bwlimit |
— | rsync 限速(字节/秒;内部换算为 KiB/s) |
rsync_compress |
false |
--compress / -z |
rsync_xattrs |
false |
--xattrs / -X |
rsync_acls |
false |
--acls / -A |
rsync_hard_links |
false |
--hard-links / -H |
rsync_chown |
— | --chown=用户:组,强制目标属主 |
rsync_chmod |
— | --chmod=D755,F644,按规则调整权限 |
rsync_password_file |
— | --password-file,rsync daemon/模块认证 |
rsync_path |
— | --rsync-path,远端 rsync 路径 |
rsync_delete_excluded |
false |
全量启动时同时删除被排除的目标项 |
rsync_* 是 rsync 自身的参数,gsyncd 只负责翻译并传给 rsync;direct 的保真用 preserve_*,两者不要混用。
| 键 | 说明 |
|---|---|
target_dir |
远端目标目录;省略时默认等于源目录绝对路径,启动日志会打印补全后的实际值 |
target 只接受主机名或 user@host。把它写成 host:path、本地目录、rsync://...、host::module 或裸 IPv6 字面量(含冒号)都会在 -check/启动时报错:传输目标由 target:target_dir 拼接,而远端 move/delete 直接使用 target_dir,路径混写会让两者指向不同位置,可能操作远端错误目录。远端路径统一写 target_dir;需要 IPv6 时在 ~/.ssh/config 里起别名,target 写别名。
显式写的相对 target_dir 合法,rsync 会相对远端登录目录解析,启动时记一条 warn;建议使用绝对路径。
[sync.ssh] 支持 binary、port、identity_file、options,仅 rsyncssh 使用。
模式不匹配的键会被拒绝:
direct配rsync_xattrs、rsync配preserve_xattrs、非rsyncssh配target_dir等,都会在解析配置时列出全部非法键、当前模式以及要求的模式并退出,不会被静默忽略。部署前先跑gsyncd -config ... -check,它只校验配置和目标,不启动同步。
- 只想复刻
rsync -avz:mode="rsync"、delete=false、rsync_compress=true;-a已内置,-v不需要。需要保留外部符号链接时加symlink_mode="all"。 - 本地/NFS 备份:
mode="direct"默认即可;需要硬链接/xattr/ACL/稀疏/设备节点时再开preserve_*/sparse/copy_special。 - rsyncssh 远程镜像:
mode="rsyncssh",target写主机,target_dir写远端目录;需要远端 move/delete 优化时保持delete=true。
- 传输时校验(默认开):边拷边算 SHA-256,rename 前读回暂存文件复核;不一致重拷,仍失败则批次报错并记录路径。旧目标在 rename 前不被改动。
- 目录树:
gsyncd -config ... -verify-tree,目标端只 readdir,报告缺失/多余/类型不一致。 - 内容深校验:
gsyncd -config ... -verify-content,可加-verify-sample N;两侧完整读一遍,代价较高,建议低频执行。 - 时间戳精度:自动探测目标文件系统的 mtime 精度;128 字节 inode 的 ext4、FAT、部分 NFSv3 只能存整秒,比较时按该精度截断,避免误报与重复重拷。
rsync/rsyncssh依赖 rsync 自身块校验;逐文件读回校验仅 direct 后端。
target_guard = true(默认)时,启动前要求目标已存在,且解析 symlink 后与根文件系统不是同一设备,或包含 .gsyncd-target marker。首次挂载后执行一次:
gsyncd -config /etc/gsyncd/gsyncd.toml -init-target运行中目标被移走/替换时,批次会拒绝写入并退避重试;目标恢复后自动收敛。目标若被重新挂载为新 inode,需要重启 gsyncd。
迁移前请确认以下差异,它们都是有意设计,不是缺陷:
- 配置:TOML 静态配置,不支持 Lua、Layer1~4、
onCreate/onStartup等任意 hook,也不支持 tunnel / crontab。需要外部编排时,请轮询 JSON 状态文件或由外部脚本触发。 delay:默认是“整棵树静默 delay 后刷”,不是 lsyncd 的“每条事件到期即刷”。持续写入的树请设delay_mode = "deadline";max_hold(默认 15m)是永不静默时的兜底。- 元数据:direct 默认保留完整 mode、owner(仅 root)、文件/目录 mtime、符号链接;xattr/ACL、硬链接、稀疏文件、设备节点需要显式打开。目标根目录本身不 chown/chmod。
preserve_xattrs会禁用 checkpoint 的目录跳过:启动时逐文件核对属性(只写差异),大树上会增加一次元数据遍历。 - 符号链接:默认
safe,指向同步根外部的链接不会被镜像;all才是 lsyncd-l的原样行为。 - 删除:运行期删除由事件驱动,不主动扫描目标端多余项;目标端漂移由 Startup 或
full_resync收敛。delete = "running"/"startup"与 lsyncd 一致。重命名(mv a b)的旧名a总会从目标端移除,即使delete = false/"startup";这是 rename 语义,不是删除策略。 - rsync / rsyncssh:增量传输用
--files-from+ 显式删除,不在增量批次上使用--delete;rsyncssh的 move/delete 通过 ssh 在远端本地执行,ssh 不可用时回退 rsync。mode = "rsync"的远端目标删除走--delete-missing-args。 - 重载:SIGHUP 会先排空在途批次、刷新窗口,再以同一 pid 重新执行自身;配置变更不需要手动重启。TERM/INT 正常退出。
- 平台:macOS/Windows 使用轮询兜底,没有 fsevents;大目录树请以 Linux 为主。
make build # 当前平台
bash scripts/dist.sh # 仅 linux/amd64 与 linux/arm64 到 dist/产物是静态单文件,-buildvcs=false 保证相同工具链下可复现。环境变量 GSYNCD_RSYNC 可覆盖 rsync 可执行文件路径。
go test ./... -count=1
go test -race ./internal/... -count=1
bash scripts/e2e.sh
bash scripts/smoke.sh ./gsyncdexamples/gsyncd.example.toml:带注释的完整配置模板deploy/gsyncd.service:systemd unit(已使用-nodaemon)deploy/gsyncd.tmpfiles.conf:/var/lib/gsyncd、/var/log/gsyncddeploy/99-gsyncd.conf:inotify/脏页/句柄调优
首次部署:挂载目标 → -init-target → -check → 启动服务。
GPL-2.0-or-later。