从一次凌晨的发布事故说起我决定不再用rsync硬扛镜像同步了。当时我们有两个内网镜像仓库主节点在上海灾备节点在贵州每次大版本发布前都要把几百GB的容器镜像和静态资源包推到备节点。最初用rsync加crontab看似没毛病但真正跑起来之后才发现噩梦才刚刚开始同步到一半网络抖动全部重来、源目录删除文件后备份节点被连带删除、几十个小文件并发时rsync的session开销大得离谱。连续两次凌晨被on-call电话叫醒之后我把“搞一个真正适合镜像仓库场景的同步工具”写进了迭代计划这就是MiroFish的由来。MiroFish定位很明确一个面向容器镜像仓库和静态资源目录的增量同步CLI工具核心能力包括分块级校验、断点续传、并发传输、安全删除保护以及一套简单但够用的任务编排机制。它不追求替代rsync的全部功能而是把“镜像仓库同步”这一件事做透。项目从设计到上线大概用了三周目前在我们内部承担着跨地域全量仓库同步和每日增量巡检的任务。这篇文章会把整个工具的选型逻辑、核心实现、部署实践和踩坑过程完整拆开来讲适合正在被镜像同步问题折磨的运维和平台开发同学参考。1. MiroFish到底解决了什么问题从一次凌晨的发布事故说起1.1 rsync同步镜像仓库的四个死穴先说那次事故。我们有一个预发布流程每周五晚上把构建产物和镜像同步到灾备节点。某个周五网络恰好出现间歇性丢包rsync跑到37%的时候连接断了。因为没有断点续传机制第二天重新执行的时候rsync会把已经传完的部分重新扫一遍、重新传一遍。更麻烦的是镜像仓库里有很多几百MB到几个GB的大层文件chunk一旦传了一半断掉整个文件就要作废重来。那次从凌晨两点重试到早上六点最后人盯在那儿手动调参数才赶在发布前勉强同步完。这暴露了rsync在镜像同步场景里的四个死穴无分块级断点续传rsync虽然能跳过已同步的块但前提是文件完整地存在于目标端而且它自己的临时文件机制在大文件场景下很不友好。删除操作没有保护--delete一把梭源端误删或者同步目录绑错目标端直接跟着删镜像仓库的数据安全完全没保障。小文件并发能力弱单线程rsync同步几十万个manifest文件时速度可以慢到让你怀疑人生。校验粒度过粗默认只做文件大小和mtime校验对于仓库里大量“内容变了但mtime被刻意保留”的文件rsync会直接跳过。那次事故之后我意识到与其反复给rsync打补丁不如写一个专门为镜像同步场景设计的工具。MiroFish就是在这个背景下立项的。1.2 MiroFish的命名和核心设计目标MiroFish这个名字有两层含义Miro取自Mirror的前四个字母代表镜像仓库Fish则是取“像鱼群一样并发行动”的意思。整个工具的核心设计目标从一开始就很清楚分块级增量同步把每个大文件切成固定大小的chunk记录每个chunk的哈希只传输目标端缺失或损坏的chunk。断点续传落地在目标端落地.mf_partial文件同步中断后恢复时从记录文件里读取已完成chunk列表而不是重新扫全量。安全删除保护引入“软删除”机制目标端多出的文件不直接删而是移入一个可配置的隔离目录保留N天后才清理。并发调度内部化不再依赖外部-P参数和手动调优工具根据CPU核数、文件大小和网络带宽自动决定并发度。后续所有代码实现和部署方案都是围绕这四个目标展开的。2. 设计取舍与核心机制为什么我不用rsync直接硬同步2.1 全量扫描 增量传输的底层模型MiroFish的同步模型可以拆成三个阶段扫描Scan、计划Plan、传输Transfer。扫描阶段做的事情是对源端和目标端分别做一次目录遍历把每个文件的相对路径、大小、mtime和分块哈希列表记录下来。这里有一个关键取舍MiroFish不采用“先扫源端再连目标端比对”的流式方案而是把两端的清单都先落盘缓存再进行离线比对。这么设计的原因很实际——镜像仓库的目录树动辄几十万条记录网络往返一次获取单个文件状态的代价很高离线比对一次生成全量差异列表后续传输阶段只需按照差异列表执行不再回源判断。差异比对的核心逻辑伪代码如下def build_diff(source_manifest, target_manifest): diff [] for rel_path, src_meta in source_manifest.items(): tgt_meta target_manifest.get(rel_path) if tgt_meta is None: diff.append((CREATE, rel_path, src_meta)) elif src_meta.size ! tgt_meta.size: diff.append((REPLACE, rel_path, src_meta)) else: src_chunks src_meta.chunk_hashes tgt_chunks tgt_meta.chunk_hashes missing_chunks [ (i, h) for i, h in enumerate(src_chunks) if i len(tgt_chunks) or tgt_chunks[i] ! h ] if missing_chunks: diff.append((PATCH, rel_path, src_meta, missing_chunks)) return diffPATCH类型是MiroFish和普通同步工具拉开差距的地方。当文件大小一致但chunk哈希不一致时不需要整文件重传只需要传变化的chunk块。这在镜像仓库场景收益很大因为很多情况下只是OCI manifest里的某个字段变了或者配置文件被修改后又改回来基础层文件完全没有变化。2.2 分块大小和哈希算法怎么定分块大小是MiroFish的第一个关键参数。我最终定的是4MB这个值不是拍脑袋定的而是基于两个约束镜像层文件普遍在几十MB到2GB之间4MB的分块可以把大文件切成几百个块粒度足够细断点续传时损失可控TCP窗口和磁盘IO在4MB块下能跑出比较理想的吞吐。我实测过1MB和8MB分块的传输效率1MB块在网络良好时同步速度只有4MB方案的约七成因为块头校验和状态记录的额外开销占比太高8MB块虽然大文件传输效率略有提升但遇到文件局部修改时多传的数据太多PATCH收益急剧下降。哈希算法选择了BLAKE3。和MD5、SHA256相比BLAKE3在x86_64上的计算速度大约是SHA256的4到6倍在多线程环境下还能并行处理多块数据。镜像仓库同步是典型的IO密集CPU敏感任务扫描阶段要计算几十万个文件的哈希用BLAKE3能把扫描时间从“小时级”降到“分钟级”。虽然BLAKE3不是加密安全哈希的最保守选择但镜像同步场景不涉及对抗性攻击性能优先完全成立。2.3 为什么并发模型从多进程改成了协程第一版MiroFish用的是Python multiprocessing进程池思路很简单每个worker进程负责一个文件的全量传输。跑了一次全量同步之后发现进程模型在断点续传场景下非常笨重。一个worker进程挂掉之后它持有的继续传输状态就丢了其他worker无法接管进程间的内存共享又需要引入multiprocessing.Manager复杂度上去了性能反而下来了。第二版改成asyncio协程模型后几个长期困扰的问题迎刃而解状态集中管理一个全局状态对象resume_state在协程间共享每个chunk传完就更新进程崩溃或任务取消后新的协程能直接从状态对象里恢复进度连接复用所有chunk传输复用同一个aiohttp TCP连接池避免了进程模型下每个进程单独建立连接的开销动态调度可以精确控制某个大文件的未完成chunk数剩余chunk少的时候自动降低它的调度优先级避免“一个大文件占满所有连接”的情况。协程模型的关键实现是靠一个ChunkScheduler类完成的class ChunkScheduler: def __init__(self, concurrency16): self.semaphore asyncio.Semaphore(concurrency) self.pending asyncio.PriorityQueue() async def schedule(self, file_queue): while not file_queue.empty(): file_task await file_queue.get() for chunk_id, chunk_hash in file_task.missing_chunks: await self.pending.put((file_task.priority, chunk_id, chunk_hash)) while not self.pending.empty(): _, chunk_id, chunk_hash await self.pending.get() async with self.semaphore: await self._transfer_chunk(file_task, chunk_id, chunk_hash)由于每个文件缺失的chunk数量不同调度器根据不同文件的剩余chunk数量和文件优先级动态调整调度顺序最终实现“小文件快速终结大文件稳定推进”的效果。3. 关键模块实现详解分块校验、断点续传和并发调度的落地细节3.1 清单文件与断点状态记录MiroFish的清单文件格式设计为JSON Lines.jsonl每行一个JSON对象记录一个文件的元信息。选择JSON Lines而不是一张大CSV或者单一JSON数组主要考虑到两点一是扫描是大批量追加写操作JSON Lines可以一行行地append不需要把整个清单load进内存再写二是后续做流式读取时可以逐行处理不会因为单个大文件导致内存爆炸。一个典型文件记录如下{rel_path: mirror/library/nginx/1.25.3/layer.bin, size: 536870912, mtime: 1707753600, chunk_size: 4194304, chunk_count: 128, chunk_hashes: [6b3f4c..., 9d1e2f...]}断点状态文件则是另一个.mf_state文件记录每个文件已经成功传输的chunk序号以及最后更新时间。它的更新是异步批量落盘的每传完N个chunk或者每间隔5秒做一次flush而不是每个chunk都写一次否则高频小文件同步时磁盘IO会成为新瓶颈。3.2 PATCH传输协议设计MiroFish在目标端部署了一个轻量agent监听一个TCP端口接收两类请求PUSH_CHUNK和APPLY_PATCH。PUSH_CHUNK请求负责把某个缺失的chunk以二进制流的形式写到临时文件.mf_partial对应的偏移位置。这里必须强调一个细节chunk在文件中的偏移位置由chunk_id * chunk_size计算agent端写入时使用随机写pwrite而不是顺序拼接。好处是并发传输同一个文件的多个chunk时各chunk之间完全不需要锁天然支持乱序到达。当所有chunk都到达后客户端发送APPLY_PATCH请求agent会把.mf_partial文件重命名为目标文件并记录新的文件哈希。如果在rename之前发现缺失了某个chunkagent会返回缺失清单客户端自动重新调度缺失chunk的传输。整个PATCH流程是幂等的。重复发送同序号chunk不会导致数据损坏因为agent会先校验chunk哈希再写入不匹配就直接拒绝。这是分布式传输里“at least once”语义的正确使用姿势——接收端通过校验消化重复请求。3.3 并发数自适应从固定值到动态反馈收敛最初版本里并发数是用户在配置里写死的。后来在生产环境发现一个问题并发数设得高千兆网络上跑得欢但到了跨地域的低带宽链路上反而会引发TCP重传风暴。后来我加入了一个简单的拥塞控制机制核心思路是借鉴TCP慢启动启动时并发数从4开始每成功传输20个chunk如果平均传输时延低于上次周期的80%则并发数加1上限不超过配置的最大值如果出现连续3个chunk传输超时或失败并发数立即减半并进入30秒的“冷静期”。这个机制上线后跨地域同步的稳定性提升非常明显。贵州节点同步3.2TB数据的时间从原先的平均9小时缩短到了5小时左右网络抖动触发的重试次数下降了约70%。当然这个数据依赖于具体网络环境但机制本身的思路值得参考固定并发数永远无法适配复杂网络必须让工具自己根据反馈动态调整。4. 生产环境部署实录从配置文件到监控告警的完整落地方案4.1 目录规划和配置结构MiroFish采用客户端-服务端模式客户端负责扫描和调度服务端agent负责chunk写入和patch应用。两端共用一套Toml配置文件结构如下[server] listen 0.0.0.0 port 9653 data_dir /data/mirror quarantine_dir /data/quarantine auth_token xxxx [client] source_root /data/repos target_root /data/mirror target_endpoint 10.20.30.40:9653 scan_threads 8 chunk_size 4194304 max_concurrency 32 soft_delete true soft_delete_retention 7ddata_dir和target_root必须对应。quarantine_dir是软删除隔离目录所有目标端多余文件先移到这里而不是物理删除。soft_delete_retention控制隔离文件保留时间到期后由单独的清理任务物理删除。4.2 定期全量同步 每日增量巡检的双层调度MiroFish设计了两种运行模式full-sync和incremental-check。full-sync跑全量扫描和全量差异比对适用于初次迁移和灾备节点从零恢复。incremental-check则会读取上次同步生成的清单文件作为基准只扫描相对路径在基准清单中出现过的文件增量同步新出现的文件或元信息变化的文件。注意增量巡检不会处理源端已删除的文件这步交给软删除机制去做避免增量扫描时误删。我们目前的调度策略是每天凌晨2点执行incremental-check把当天的镜像变更推到备节点每周日凌晨4点执行一次full-sync修正可能累积的清单偏移和异常状态。完整跑一次全量3.2TB同步大约需要5小时增量巡检基本控制在30分钟以内。4.3 监控指标与告警配置MiroFish在客户端暴露了一个--metrics参数监听/metrics路径输出Prometheus格式的指标。重点监控以下指标mirofish_scan_total扫描过的文件数量观察是否存在目录挂载异常导致扫描量骤降mirofish_transfer_bytes传输总字节数和仓库变更量联动如果长期为0但上游有推送需要检查排队任务是否卡死mirofish_chunk_retry_totalchunk重试次数正常波动应该在万分之一以下超过则说明网络质量问题mirofish_soft_deleted_total软删除文件数量这个指标突然暴涨通常意味着源端目录配置错误。告警规则我们设置了三条传输任务超过2小时没有新chunk完成、chunk重试率超过0.1%、软删除文件数量超过100。这三条规则一出基本能在故障影响扩大前发现异常。4.4 权限最小化和密钥管理agent端的auth_token本质上是共享密钥但我在生产环境没有采用静态token而是接了内部Vault服务每24小时轮换一次。agent启动时先向Vault获取当前有效token缓存到内存token轮换后客户端会自动重连。这样即使某个agent的配置散落到日志里有效期也只有24小时风险面可控。由于MiroFish有物理删除能力agent进程运行用户做了严格限制只拥有data_dir和quarantine_dir的读写权限其余系统路径均不可写。安全审计时这个设计是重点加分项。5. 上线半年踩过的坑三个让我改代码的真实故障5.1 大文件PATCH时的“隐形丢块”问题上线第三周我们接到反馈某个服务的镜像在灾备节点启动异常疑似文件不完整。排查后发现问题出在PATCH协议的一个并发漏洞上。当一个文件缺失大量chunk时客户端会并发发送多个chunk到agent。但agent写入pwrite后返回OK给客户端客户端立即更新状态记录。问题在于agent返回OK只代表chunk写入.mf_partial成功不代表最终rename成功。如果某个chunk在写入后、rename前因为agent进程重启而丢失客户端状态却已经标记为“已完成”后续不会重推最终文件就缺了一块。修复方案是增加APPLY_PATCH阶段的最终校验rename前agent需要重新计算.mf_partial的完整BLAKE3哈希和客户端清单文件里的完整文件哈希比对不一致则返回缺失chunk列表。这个校验只在最后一个chunk到达时触发一次开销可控但彻底堵住了“隐形丢块”。提示任何涉及文件完整性的同步工具最终校验必须放在文件关闭、rename之前而不是放在每个chunk写入之后。中间的窗口期就是数据损坏的高发区。5.2 软删除误伤事件源端目录绑定错误另一个印象深刻的事故是软删除机制被自己人坑了一次。源端某台构建机的磁盘满了运维哥们在清理时不小心把/data/repos误挂载成了另一个分区镜像。MiroFish扫描后发现这个分区只有几个残留文件于是生成了大量软删除任务把灾备节点上几千个镜像文件全部移到了隔离目录。幸运的是启用了软删除而不是硬删除数据没有真正丢失但从隔离目录恢复就花了一个多小时。这个事件之后我加了两道保险在配置里增加min_file_count参数当目标端软删除次数超过源端扫描文件数的5%时任务直接失败并触发告警不执行任何删除操作全量同步任务执行前要求先手动确认总文件数变化波动不超过10%否则任务拒绝启动。这两条规则本质上是“防呆设计”防止自动化工具在异常输入下做出破坏性操作。任何涉及删除的工具都应该默认带上这层保险。5.3 扫描阶段CPU跑满导致同步延迟有次用户反馈增量巡检明明跑了很久传输速率却非常低。看监控发现scan_threads配置成8后扫描过程中8个线程同时计算BLAKE3哈希把机器CPU全部吃满导致agent网络线程响应延迟传输带宽上不去。这里又是一个并发度设计问题扫描和传输不应该共享CPU并发度预算。我后来把扫描线程池和传输协程池做了物理隔离配置项拆成scan_threads和transfer_concurrency并且扫描线程池默认只使用CPU核数减2的并发度确保传输线程始终有CPU可用。修复后全量扫描时间从1小时50分缩短到40分钟整体同步时间反而更短了。6. 和主流同步方案的对比什么场景才值得自己造轮子6.1 MiroFish vs rsync vs skopeo vs dist很多朋友会问同步镜像为什么不用现成的skopeo copy或者rsync非要自己折腾。这里我整理了一个对比表可以直观看清各自适合的场景工具分块级增量断点续传删除保护多仓库并发适用场景rsync无文件级弱临时文件机制简陋无保护--delete一把梭单进程为主简单目录同步、日志归档skopeo镜像层级依赖registry实现无支持单镜像多路并发镜像跨registry复制dist镜像层级依赖registry实现无支持批量Linux基金会下的镜像分发工具MiroFish4MB chunk级支持状态落盘软删除隔离机制支持协程调度大型镜像仓库整体同步和灾备rsync最大的问题是文件级同步镜像仓库中一个几百MB的层文件里有几KB变化它也得整文件重传。skopeo和dist解决的是“镜像从registry A复制到registry B”但对于“整个仓库目录如何随时间保持一致并且有删除保护、断点续传、状态可视”这个需求它们并没有直接答案。MiroFish反而更像一个“镜像仓库的文件系统同步层”它不关心镜像内部格式只关心文件如何保持一致这正是很多平台团队需要的抽象层。6.2 什么情况下不建议自己造轮子说了半天MiroFish的优势也必须泼点冷水。如果你的需求是单次迁移几个镜像或者仓库体量在100GB以下直接rsync或者skopeo就够了自己造工具的时间和运维成本完全不划算。MiroFish的价值在下面几个条件同时满足时才成立仓库体量大TB级以上跨地域同步频率高有灾备恢复诉求需要随时保持两套库数据一致对删除安全有严格要求不能接受rsync一把梭的风险现有工具无法满足断点续传和细粒度增量。如果团队技术栈完全偏向Go且已有成熟的对象存储也可以考虑用rclone配合--fast-list实现类似效果。工具选型永远是场景驱动的不要为了造轮子而造轮子。7. 后续扩展从单点到联邦同步MiroFish第一版解决的是“单源到单目标”的同步问题但实际使用中很快出现了新的需求多套环境之间互为镜像或者一个源同步到多个目标。我目前正在做的是联邦同步模式——支持多源多目标的镜像拓扑核心改动是引入“同步任务”的概念每个任务定义自己的源、目标、同步策略和调度周期用一张任务表在数据库里编排。联邦模式下的冲突处理比单源复杂很多目前的设计是每个文件记录一个origin_id同步时只允许origin_id匹配的任务覆盖该文件其他任务只能新增不能覆盖。这个约束可以避免两个源同时修改同一个文件导致的状态抖动。另外还在做的一个增强是“事件驱动同步”不再完全依赖定时任务扫描而是对接代码仓库的webhook上游推送完成后立即触发增量同步。扫描开销比定时任务小很多同时能显著缩短数据延迟。这块还在迭代中等稳定后会单独写一篇实践记录。从我个人的经验来看镜像仓库同步工具最核心的价值不只是快而是“可控”。你清楚每一个chunk的状态清楚删除操作什么时候会发生清楚网络抖动后从哪里恢复。有了这种可控性跨地域灾备才不是一句空话。MiroFish也是在这几次事故和迭代中一点点变得可靠起来的。