多节点文件同步必须依赖外部协调机制，因Go原生API如os.SameFile、filepath.Walk等仅支持单机操作，无法感知跨节点状态；应采用内容哈希命名+版本日志实现最终一致性，并用memberlist实现无中心自动发现与容错重试。
多节点文件同步无法靠本地操作达成一致，必须引入外部协调机制。Go 本身没有跨进程文件状态同步能力，os.SameFile、sync.Map、甚至 fsnotify 都只作用于单机——这是设计使然，不是缺陷。
为什么直接用 os.SameFile 或 filepath.Walk 同步会失败
因为这些 API 完全不感知其他节点的存在。os.SameFile 只比 inode 或 volume+index，两个节点上内容完全相同的文件必然返回 false；filepath.Walk 扫出来的只是本机当前快照，既不包含远程变更，也无法表达“这个文件在节点 A 已删、在节点 B 还存在”的冲突状态。
- 常见错误现象：脚本在节点 A 删除文件后，手动 rsync 到节点 B，但中间有新上传请求写入 B 的 /media，导致瞬间不一致且无审计痕迹
- 大小预筛 + 分块哈希（如首尾 1MB）可加速比对，但仅适用于离线校验，不能作为同步驱动逻辑
- Windows 下
filepath.WalkDir比filepath.Walk更可靠，但仍解决不了跨节点状态收敛问题
用内容哈希 + 版本日志实现最终一致性
核心是放弃“实时同步”，转而构建一个可追溯、可重放的变更流。每个文件由 sha256 命名，每次变更生成一条带单调递增 version 的日志记录，节点间通过拉取版本差完成补全。
- 文件不可变：
a1b2c3/image.jpg一旦写入，禁止覆盖；更新即新哈希 + 新日志项 - 本地日志存储建议用 SQLite 或 WAL 文件，字段至少含
version INTEGER PRIMARY KEY, file_hash TEXT, op TEXT CHECK(op IN ('add', 'delete')) - 同步触发时机：定期（如每 30s）向集群广播自己的
currentVersion，收到邻居更低版本号时发起 HTTP GET 请求拉取缺失条目 - 拉取到
add事件后，先HEAD检查远端文件是否存在且哈希匹配，再GET下载；delete事件则直接os.Remove对应路径
用 memberlist 实现无中心节点自动发现
避免硬编码 IP 列表或依赖 DNS，让节点自己找到彼此。HashiCorp 的 memberlist 库在 Go 生态中稳定、轻量、无外部依赖，适合中小规模集群（≤ 50 节点）。
立即学习“go语言免费学习笔记（深入）”；
- 初始化时传入本机地址和端口，加入同一 gossip cluster 即可自动交换成员状态
- 不要把业务数据塞进 memberlist 的用户数据字段（UserData），它只适合传
version这类轻量元信息 - 监听
MemberEventCh获取上线/下线事件，下线节点的未完成同步任务需标记为 stale，后续由 leader 节点兜底重试 - 注意：默认加密密钥为空，生产环境必须设置
SecretKey，否则 gossip 流量可被中间人窃听或伪造
同步失败时的容错与重试边界
网络分区、磁盘满、临时权限错误都会中断同步，但不能因此卡住整个流程或静默丢弃变更。
- 每次同步操作必须设超时（如
context.WithTimeout(ctx, 30*time.Second)），避免 goroutine 泄漏 - 下载失败的文件哈希应写入本地 retry queue（如内存 map + 定时刷盘），按指数退避重试（首次 1s，最多 5 次）
-
os.Link跨设备会返回syscall.EXDEV，此时必须 fallback 到io.Copy；Windows 上硬链接基本不可用，直接跳过 - 删除目标文件前，先
os.Stat确认存在，再os.Remove，并忽略os.IsNotExist错误——这是并发场景下的正常 race
真正难的从来不是“怎么拷文件”，而是“怎么知道该拷哪个、谁先谁后、失败了找谁要”。版本日志 + 内容寻址 + gossip 发现这三者组合，已经能覆盖绝大多数 CMS、媒体服务、静态资源集群的同步需求。别在同步逻辑里做复杂冲突合并，那是对象存储或分布式文件系统的事。
