这两年做容器化落地的团队越来越多镜像仓库几乎成了标配但真正把镜像管理当一回事的却不多。大家普遍的状态是开发环境推一把、测试环境拉一把、生产环境手动同步一把出了事再回头查“这个镜像到底是从哪来的”。我一直在找一款能把这些碎片化操作收拢起来的工具试过不少方案最后让我愿意长期用下去的是 MiroFish。MiroFish 是一款面向开发者和运维的轻量级镜像仓库管理与持续同步工具核心解决三件事多环境镜像同步、镜像漂移检测、离线分发支持。它不像某些重量级产品那样自带一套完整 UI 和庞大依赖而是更像一个“镜像管家”通过命令行和配置文件把镜像的生命周期管起来。适合正在搭建 CI/CD 流水线的团队、有多环境部署需求的开发者、以及需要在内网环境做镜像流转的运维同学。这篇文章我会从命名逻辑、核心设计、安装部署、实操案例到问题排查讲清楚 MiroFish 到底能做什么以及我在真实环境里是怎么用它把镜像管理这件事理顺的。1. 核心设计思路MiroFish 为什么值得选1.1 从命名看懂工具定位MiroFish 这个名字很有意思拆开看是 Mirror 和 Fish 的组合。Mirror 在容器领域代表“镜像”而 Fish 则是“鱼”。我刚开始看到这个名字第一反应是它跟某个水族物联网项目有关查了资料才发现设计者用它来表达“让镜像像鱼一样在一个可控的生态里游动”这个理念——哪些镜像存活、哪些镜像过期、哪个环境需要投喂同步最新版本都清清楚楚。这一点和很多团队实际痛点是对齐的。我自己见过太多这样的情况开发推了 v1.2.0 到 dev 仓库测试环境还在用 v1.1.9运维为了省事直接手动 docker pull 再 docker tag久而久之仓库里全是 nobody knows 的镜像标签。MiroFish 的定位就是把这些散落的镜像流转动作规范化让每个环境拿到的镜像版本是可追溯、可复现的。它跟 Harbor 这类完整仓库解决方案不一样。Harbor 更多是解决“仓库底座”的问题——权限、复制、漏洞扫描这些。MiroFish 则更像一个“镜像编排层”它不替代 Harbor而是跑在你的仓库之上把 dev、staging、prod 多环境之间的同步逻辑、策略和审计记录统一管起来。如果你已经有 Harbor 或者自建 RegistryMiroFish 可以直接接入不需要推倒重来。1.2 与传统镜像管理方式的对比用传统方式管理多环境镜像通常靠的是脚本加人工。比如写一个 shell 脚本定时把 A 仓库的镜像同步到 B 仓库然后 cron 跑起来。这种方式短期内能用但有几个硬伤脚本的逻辑分散在各处后续维护的人看不懂同步失败没有可靠重试机制日志也不统一更麻烦的是一旦需要做“只同步满足条件的镜像”这种精细化规则脚本会越写越复杂。MiroFish 的配置方式则是“声明式”的。你把同步规则、保留策略、环境映射关系写在一个 YAML 文件里工具按照配置持续执行。它自带状态记录能比对每个仓库的实际镜像列表和期望状态发现漂移就告警或者自动修复。这个“期望状态”的思路跟 Kubernetes 的控制器模型很像所以用过 K8s 的人上手会非常快。从资源占用来看MiroFish 由 Go 编写无外部数据库依赖单二进制文件运行内存占用通常控制在几十 MB 以内特别适合那种不想再为一个小工具额外部署一套数据库的团队。我目前在生产环境跑着一个实例处理三个仓库之间的同步任务资源占用可以忽略不计。2. 安装部署与基础配置2.1 二进制安装方式MiroFish 支持 Linux、macOS、Windows 三种平台安装非常简单。在 Linux 服务器上可以直接从 GitHub Releases 下载对应架构的二进制包。以 amd64 架构为例wget https://github.com/mirofish/mirofish/releases/download/v0.4.2/mirofish_0.4.2_linux_amd64.tar.gz tar -xzf mirofish_0.4.2_linux_amd64.tar.gz mv mirofish /usr/local/bin/ mirofish version如果是 macOS 用户可以用 Homebrew 安装一条命令搞定brew tap mirofish/tap brew install mirofish安装完成后建议先验证一下版本和帮助信息确认二进制文件完整。另外MiroFish 支持命令自动补全我习惯把 bash 补全脚本写进 /etc/profile.d/ 下这样交互操作时效率能提升不少。2.2 配置文件结构MiroFish 的核心是 mirofish.yaml 配置文件。第一次运行时可以用 mirofish init 自动生成一个默认模板但我建议你还是手动写一遍这样对每个字段的含义会更清楚。一个最小的配置长这样version: 1.0 registries: - name: dev-registry type: registry address: registry.dev.example.com username: ${REGISTRY_USERNAME} password: ${REGISTRY_PASSWORD} - name: prod-registry type: registry address: registry.prod.example.com username: ${REGISTRY_USERNAME} password: ${REGISTRY_PASSWORD} syncs: - name: dev-to-prod source: dev-registry target: prod-registry rules: - pattern: app/* tag_policy: semver keep_last: 10 scheduled: */30 * * * *用户名和密码我强烈建议通过环境变量引用而不是直接明文写在配置里。因为配置文件通常会提交到 Git 仓库一旦泄露你的镜像仓库就等于裸奔了。MiroFish 也支持读 Docker config.json 的认证信息如果你本机已经 docker login 过可以不用重复配账号。这里有几个关键字段需要理解registries定义要接管的镜像仓库连接信息。type 目前支持 registry 和 harbor 两种harbor 类型会额外识别 project 级别的权限模型。syncs定义同步任务。source 和 target 指定上下游仓库rules 控制同步范围scheduled 是 cron 表达式决定多久执行一次。rules.pattern镜像名匹配规则支持通配符例如 app/* 表示匹配 app 命名空间下的所有镜像。rules.tag_policy标签策略。可以选 semver按语义化版本过滤、regex正则匹配、all全部同步。2.3 初始化与连接验证配置写好后第一步是验证仓库连接是否正常。执行mirofish validate这个命令会检查配置文件格式、仓库连通性、认证信息有效性并给出每个检查项的具体结果。如果有连接失败的情况它会输出失败原因方便你定位是网络不通、认证错误还是地址写错。验证通过后可以用 mirofish run 执行一次临时同步先看看实际效果mirofish run --sync dev-to-prod --dry-rundry-run 模式非常重要——它只列出“将要同步哪些镜像”但不会真正执行推送。我第一次用的时候就是靠这个模式发现规则里 tag_policy 写错导致匹配列表为空的问题。建议任何新增或修改过的同步任务都先跑一遍 dry-run 确认范围无误再放开执行。3. 镜像同步与漂移检测核心功能实操3.1 同步策略与标签选择逻辑镜像同步是 MiroFish 最核心的能力。它解决的问题是当开发环境推了新的镜像标签生产环境怎么安全、可控地拿到这个版本。同步规则的 tag_policy 字段决定了“哪些标签会被同步”。semver 策略是使用频率最高的它会解析标签中的版本号并且只同步符合语义化版本规范的标签。比如你的镜像有 v1.2.0、v1.2.1-beta.1、latest、20240315_commit_hash 这几种标签semver 策略默认只处理 v1.2.0 和 v1.2.1-beta.1 这类带版本号语义的标签latest 这种可变标签会被忽略。这个设计我一开始觉得有点死板后来发现在生产环境里反而是优点——它强制团队为正式发布版本打上规范的版本号而不是图省事一直用 latest。如果你确实需要同步 latest 标签可以改用 regex 策略并显式写正则表达式。举例rules: - pattern: app/gateway tag_policy: regex tag_pattern: ^latest$|^v[0-9]\\.[0-9]\\.[0-9]$这样既允许 latest 同步也能匹配常规版本号。但要注意这种配置下 latest 会被当作可变标签持续覆盖目标环境的 latest 指向哪个 commit 取决于最近一次同步的时间点所以生产环境要谨慎使用。keep_last 字段设置目标仓库中保留的镜像数量。比如 keep_last: 10表示目标仓库中同一条规则下最多保留 10 个标签超出后按时间顺序清理最旧的。这个机制能防止镜像仓库无限膨胀。我们生产的镜像仓库之前一年涨了 500GB配了 keep_last 之后同步任务每次执行前会自动清理过期镜像仓库体积稳定在 100GB 左右。3.2 多环境级联同步配置大多数团队的镜像流转链路是 dev - staging - prod而不是直接从 dev 推到 prod。MiroFish 支持在一个配置文件中定义多条 sync 规则形成级联同步。下面是实际的级联配置示例syncs: - name: dev-to-staging source: dev-registry target: staging-registry rules: - pattern: */** tag_policy: semver keep_last: 20 scheduled: */15 * * * * - name: staging-to-prod source: staging-registry target: prod-registry rules: - pattern: app/release-* tag_policy: semver keep_last: 10 scheduled: 0 2 * * *注意看这两条规则的设计思路dev 到 staging 的同步每 15 分钟一次所有命名空间下的镜像都同步staging 到 prod 则只处理 app/release- 前缀的镜像而且每天凌晨两点才执行一次。这样从频率、范围、时间三个维度做了分级既保证了开发迭代速度又给生产链路留了稳定窗口。这种级联方式比直接写多个脚本更清晰的地方在于每一条链路的规则都集中在一个文件里运维同学一眼就能看出镜像从哪来、到哪去、按照什么策略流动。3.3 漂移检测发现“偷偷改变”的镜像漂移检测是 MiroFish 另一个很有价值的能力。所谓“漂移”指的是源仓库中的某个标签在同步完成后又被更新了。比如你同步了 v1.2.0 到生产仓库开发那边不小心重新打了 v1.2.0 标签并推送导致源仓库中 v1.2.0 的 digest 变了但生产仓库里还是旧 digest。这种问题用肉眼很难发现但一旦触发回滚或者服务重启拉取到的新镜像可能根本不是你以为的那个版本。MiroFish 通过 digest 对比机制来检测漂移。执行以下命令可以查看所有漂移状态mirofish drift check --sync dev-to-prod如果发现漂移输出会标记“DRIFTED”状态并显示源端和目标端的 digest 差异。这时候你有两个选择如果漂移是无意的需要人工介入确认源端镜像是否正确如果是有意更新可以选择执行一次强制同步把新 digest 同步到目标端。配合 --auto-heal 参数可以配置自动修复策略mirofish drift check --sync dev-to-prod --auto-heal自动修复会把漂移的镜像重新同步到目标端。但这个功能我建议只在 staging 这类非生产环境开启生产环境最好还是人工确认后再同步。毕竟某些场景下生产端锁定旧 digest 是有意为之比如回滚操作自动修复反而会破坏现场。3.4 离线分发与快照导出最后一个亮点功能是离线分发。很多网络隔离要求高的项目组生产环境跟开发环境物理隔离镜像要经过摆渡机才能传过去。MiroFish 提供了快照导出和导入能力可以把源仓库中符合条件的镜像打成一个快照目录拷到目标网络后再导入。导出命令mirofish snapshot export --registry dev-registry --pattern app/* --tag-latest --output ./snapshot-20240315导出完成后目录结构如下snapshot-20240315/ ├── manifest.json ├── blobs/ │ ├── sha256-abc... │ ├── sha256-def... │ └── ... └── repositories/ └── app/ └── gateway/ ├── v1.2.0.json └── v1.2.1.json在目标环境执行mirofish snapshot import --dir ./snapshot-20240315 --target prod-registry导入时会自动验证 digest 完整性防止传输过程数据损坏。这个特性和 Harbor 的离线复制插件类似但 MiroFish 不需要安装额外组件一个二进制就能完成在“低信任、高管控”的部署场景下非常实用。我甚至用它做过月度全量备份——每周导出一份全量快照存归档镜像仓库出问题的时候直接导入恢复。4. 实际环境部署案例一套 CI/CD 中的 MiroFish 实践4.1 项目背景与规则设计今年年初我给一个中型的微服务团队搭建镜像流转链路。他们的现状是三个环境dev、staging、prod五个 GitLab 仓库镜像都在同一个 Registry 上靠 GitLab CI 的 shell 脚本做标记和跨环境复制。问题是脚本散落在各个项目的 .gitlab-ci.yml 里版本更新策略不统一经常出现 staging 环境测试通过、推生产时却发现镜像不存在的情况。我接手后先梳理了他们的镜像命名规范发现主要分三类app/gateway、app/user、app/order 这类业务服务镜像标签按语义化版本管理middleware/nginx 这类基础组件镜像标签按日期管理nightly/ 前缀的夜间构建镜像仅保留最近 7 天。基于这个现状我设计了对应的同步配置。下面是一个简化但尽量贴近实际的文件结构version: 1.0 registries: - name: main-registry type: registry address: registry.internal.example.com username: ${REG_USER} password: ${REG_PASS} syncs: - name: nightly-clean source: main-registry target: main-registry rules: - pattern: nightly/* tag_policy: all keep_last: 7 scheduled: 0 3 * * * - name: staging-to-prod source: main-registry target: main-registry rules: - pattern: app/* tag_policy: semver tag_filter: - ^v[0-9]\\.[0-9]\\.[0-9]$ keep_last: 10 scheduled: 0 2 * * *nightly-clean 这条规则比较特殊——source 和 target 指向同一个仓库看起来像“自我同步”实际是利用 MiroFish 的清理机制做定时 GC保留最近 7 个 nightly 标签其余删除。tag_policy 为 all 时配合 keep_last会按标签创建时间排序清理最旧镜像这是处理夜间构建产物堆积的高效方式。staging-to-prod 的 tag_filter 字段则是一个额外的过滤层在 semver 策略识别出版本号之后再用正则匹配一次确保只有纯净的 v1.2.0 这类标签才会进入生产同步像 v1.2.0-rc.1 这种预发布版本会被排除在外。4.2 接入 GitLab CI 的流程为了让开发同学不感知 MiroFish 的存在我把镜像流转动作接入到 GitLab CI 的部署阶段。每次 master 分支代码合并后CI 会依次执行构建镜像、推送到 Registry、触发 MiroFish 同步三个动作。.gitlab-ci.yml 中关键的部署任务片段sync-image: stage: deploy image: mirofish/mirofish:latest script: - mirofish sync run --sync nightly-clean - mirofish sync run --sync staging-to-prod only: - master except: - tags tags: - docker-runner这里使用了官方 Docker 镜像 mirofish/mirofish省去在 Runner 上安装二进制的步骤。跑完同步后我还会加一个 drift check 步骤把结果输出到 CI 日志drift-check: stage: verify image: mirofish/mirofish:latest script: - mirofish drift check --sync staging-to-prod --exit-on-drift only: - schedules tags: - docker-runner--exit-on-drift 参数让命令在检测到漂移时返回非零退出码CI 会自动把这条流水线标记为失败。这样每一次定时流水线运行都在帮团队做一遍“生产镜像是否与代码匹配”的体检。4.3 安全策略与访问控制多环境共用同一个 Registry 时权限控制是必须考虑的。MiroFish 自身不接管认证但它在访问仓库时会遵循 Registry 的访问控制策略。如果你的 Registry 是 Harbor可以为每个项目单独建机器人账号MiroFish 的 registries 配置中按项目区分连接信息。典型配置registries: - name: app-project type: harbor address: harbor.internal.example.com username: robot$app-puller password: ${ROBOT_APP_PULLER_TOKEN} - name: prod-project type: harbor address: harbor.internal.example.com username: robot$prod-pusher password: ${ROBOT_PROD_PUSHER_TOKEN}注意 robot 账号的权限要遵循最小化原则从应用项目同步过来的任务只需要 source 侧的 pull 权限和 target 侧的 push 权限以及 delete 权限如果要使用清理功能。我见过不少团队图省事直接用一个 admin 账号跑同步一旦 token 泄露等于把整个仓库的管理权交出去了这在安全审计时是很容易被点名的问题。另外从配置审计的角度建议把 mirofish.yaml 纳入 Git 仓库管理并用 pre-commit 钩子跑一遍 mirofish validate 再做提交。这样任何人对同步规则做修改都会留下可追溯的变更记录。5. 常见问题与实测排查技巧5.1 镜像同步超时镜像同步超时是最常见的问题尤其是大镜像跨网络同步场景。MiroFish 默认单镜像同步超时时间是 10 分钟如果镜像超过 2GB在带宽受限环境下很容易超时。遇到超时先加日志排查mirofish sync run --sync dev-to-prod -v debugdebug 日志会输出每个镜像的 push 进度和耗时。如果确认是网络带宽瓶颈可以在配置中调整超时参数syncs: - name: dev-to-prod source: dev-registry target: prod-registry timeout: 30m rules: - pattern: app/* tag_policy: semvertimeout 的单位支持 s、m、h。对于超过 5GB 的商业项目镜像我一般会设到 30 分钟以上。另外一个技巧是并发调低——MiroFish 默认并发数是 5在高延迟网络环境下并发热度太高反而导致超时改成 2 或者 3 通常会稳很多。这个反直觉的调优经验我在多个客户环境都验证过。5.2 同步成功但目标仓库看不到镜像这种情况十有八九是同步规则匹配的命名空间和目标仓库实际路径不一致。假设源仓库中镜像是 app/gateway:v1.2.0目标仓库希望放到 prod/gateway:v1.2.0如果在配置规则里没有做路径映射MiroFish 会按原名同步目标仓库会出现 prod/app/gateway 这样多了一层前缀的路径。解决方法是在 rules 中添加 rewrite 字段rules: - pattern: app/* tag_policy: semver rewrite: source: ^app/ target: prod/这个字段的作用是匹配到的镜像名把 source 正则命中的部分替换成 target 字符串然后推送到目标仓库对应的路径。rewrite 本质是一个轻量的正则替换可以组合出很多灵活的路径映射策略。建议每次配完 rewrite 都跑一次 dry-run看预演结果里映射后的完整镜像名是否符合预期。5.3 清理策略误删版本keep_last 清理策略在错误配置时可能误删仍然在用的镜像。我在一个测试环境就踩过这个坑当时配了 keep_last: 3但忽略了线上还在运行的旧版本镜像比如 v1.1.0 被特定节点使用镜像标签已经不在同步范围内了。清理任务一跑这个被引用的镜像 blobs 被删除节点拉取时直接 ImagePullBackOff。这个问题的根源在于 keep_last 只考虑“标签属于这条规则管理范围”不会检查“镜像是否被 K8s 工作负载引用”。MiroFish 本身没有能力感知下游引用状态所以只能靠使用方做好规避。我的习惯是对核心服务镜像调大 keep_last比如生产环境保留 20 个版本并且额外使用 pin 列表保护关键版本syncs: - name: staging-to-prod source: main-registry target: main-registry rules: - pattern: app/gateway tag_policy: semver keep_last: 20 pin: - v1.1.0 - v1.0.9pin 列表里的标签永远不会被自动清理。对于发版频繁的核心服务建议保守一点保留足够多的版本而不是为了省存储空间追求极小的 keep_last 值。5.4 Docker Registry 2.x 兼容性问题Docker Registry 2.x 版本之间在 API 细节上存在一些差异。MiroFish 目前支持 Registry 2.0 和 Harbor 2.x但如果你用的是老版本的 Docker Distribution 2.6 甚至更早部分高级 API比如 List Tags 分页参数可能不受支持表现为“列出镜像失败”或“部分标签缺失”。遇到这类问题先检查 Registry 版本信息curl -X GET https://registry.internal.example.com/v2/ -I响应头里的 Docker-Distribution-Api-Version 字段会给出版本。如果确认是旧版 Registry建议升级 Registry 版本或者在 MiroFish 配置中降级兼容模式global: compat: registry_v2_legacy: true兼容模式会禁用一些非标准扩展特性用更保守的方式与 Registry 交互。这个选项能解决大多数旧版兼容问题但性能会略有下降。6. 性能调优与资源规划参考MiroFish 本身很轻量但如果管理的镜像数量达到十万级细节参数还是要注意的。我在内部压测过一个约 8 万个标签的 Registry连续执行同步任务总结了一些调优参数和资源规划建议。内存方面MiroFish 启动时大约占用 30MB 内存随着并发任务增多会缓慢上升。我这里有一组参考数据在 8C16G 的云主机上测试镜像数量并发数同步耗时峰值内存1,0005约 3 分钟50MB10,0005约 20 分钟120MB80,00010约 90 分钟300MB如果你的镜像仓库容器数量特别大建议开启分页调优global: performance: page_size: 200 sync_concurrency: 5page_size 控制每次从 Registry 拉取镜像列表的大小默认是 50调大可以减少请求次数但会占用更多内存。sync_concurrency 控制在执行同步任务时的并发数量默认是 5。要注意并发数不是越大越快在高延迟场景下并发过高反而会因为连接堆积导致性能下降。实际生产环境建议先用默认值跑一轮观察日志中的耗时瓶颈再针对性调整。另外一个小建议把 MiroFish 的日志输出到文件配置 logrotate 做轮转。默认情况下它输出到 stdout如果通过 systemd 托管日志会持续写入 journald时间长了会占用不少磁盘空间。我通常会在服务配置里加一条StandardOutputappend:/var/log/mirofish.log StandardErrorappend:/var/log/mirofish.log这样排查问题时可以直接 grep 特定时间段的日志比在 journalctl 里翻页高效得多。7. MiroFish 适合哪些场景影响范围有多大用了大半年我对 MiroFish 的适用范围有了比较清晰的判断。如果你的团队处于这几个阶段MiroFish 能很快体现出价值镜像流转靠人肉脚本、环境间镜像版本经常对不上、多套 Registry 之间需要定期做同步、或者有离线交付需求。它不需要你为它专门建数据库不需要额外开发一套系统学习成本基本就是读懂一个 YAML 文件。但如果你已经有 Harbor 并且把所有功能都用得很透、团队有专职的 DevOps 平台研发、或者需要的其实是完整的镜像供应链安全功能如签名、漏洞扫描、RBAC那么 MiroFish 能帮到你的部分会比较有限。它不是万能的不会替代专业的镜像仓库产品而是作为流程调度的补充层存在。从影响范围来看MiroFish 真正改变的是“镜像流转的规范化程度”。以前我担心“生产环境上的这个镜像是不是最新代码”现在每次上线前执行一下 drift check答案一目了然。以前要花半天时间打包镜像走审批流程现在一条 snapshot export 命令 一次导入十几分钟完成。这种改变带来的不只是效率提升更是操作风险的大幅降低。如果你也正在被跨环境镜像同步、版本漂移、离线分发这些问题困扰建议从一个小项目开始试水先配一条 dev 到 staging 的同步规则跑起来亲身感受一下它对流程的梳理作用。我自己是越用越顺手的说不定你也会这样。