用 OCI 镜像同步 把懒猫镜像带回家

Why - 为什么需要 OCI 镜像同步？

它解决的痛点

• 懒猫应用商店的镜像无法直接通过 docker pull 获取，无法满足探索镜像、二次开发的需求。
• dive 等镜像层分析工具无法触达懒猫的私有镜像，开发者无法洞悉镜像内容与风险。
• 想基于懒猫镜像做定制或复刻，却缺少一个稳定的导出流程和可复用的基础镜像。
• 想要同步外部镜像到懒猫微服或个人私库时，缺少统一的图形化入口，流程零散且重复。

对懒猫生态的价值

• 让开发者把镜像同步到本地或可信私有仓库，恢复透明度与掌控力。
• 支持快速构建生产镜像副本，自动化流程与安全审计不必每次都访问应用商店。
• 与懒猫的《Docker 镜像源管理器》搭配，实现镜像发现、同步、管理的闭环。
• 通过同一界面操作任意网络可达的容器镜像，实现懒猫与外部生态之间的镜像流转。

What - OCI 镜像同步是什么？底层依赖如何运作？

服务概览

• OCI Image Sync 运行在懒猫微服之上，为个人用户提供类 Linux 服务器的体验，全程通过图形化流程完成，无需命令行。
• 支持从懒猫应用商店或任何网络可达的镜像仓库同步到本地目录、懒猫自建仓库或外部 registry。
• 通过可视化配置表单与模板，实现备份、环境镜像与多仓协同的自动化与可重复。

Skopeo 的角色

• 工具内部依赖 Skopeo，由 Containers 社区维护，可在无需 Docker 守护进程的情况下直接搬运镜像。
• Skopeo 负责校验 manifest、拉取 OCI 镜像层，并支持多种认证方式（Basic、Bearer）与传输协议。
• 它的无守护进程设计非常适合懒猫微服这类 NAS/Linux 设备，减少依赖与资源占用。

与其它懒猫工具的关系

• OCI 镜像同步 专注镜像的提取与复制；《Docker 镜像源管理器》在此基础上提供仓库级的可视化管理。

• 两者配合使用，个人用户无需企业级工具，即可在自用开发、家庭实验室测试与离线备份场景中重复利用懒猫镜像。

Who - 谁适合使用这套方案？

主要使用者

• 家庭实验室构建者：把懒猫微服当作个人 Linux 服务器，需要简单的方式镜像或归档镜像文件。
• 独立创客：基于懒猫应用做自定义或副项目，希望在自有硬件上获得可编辑的基础镜像。
• 自动化爱好者：把懒猫镜像接入个人 CI/CD、安全扫描或 SBOM 流程，而无需依赖企业基础设施。

前置条件

• 拥有访问懒猫应用商店镜像的账号或授权凭据。
• 具备目标仓库（Harbor、Docker Hub 镜像、企业私服等）的访问权限，或准备好本地文件系统存储。
• 理解需要同步的镜像命名约定与标签策略，以便在界面中快速准确填写表单。

When - 在哪些时刻执行镜像同步？

触发场景

• 基于懒猫镜像发布个性化版本或修复前，先把原镜像同步到可控环境。
• 应用商店更新上游镜像、希望下游环境保持一致时。
• 进行安全审计、使用 dive 分析内容、生成 SBOM 前的预处理步骤。
• 需要为离线、灾备环境提前准备镜像副本时。
• 希望把外部镜像搬入懒猫微服或个人私库，统一管理版本与访问权限时。

运行节奏

• 将同步纳入每次依赖镜像变更时的发布清单。
• 在执行诊断或分析前，可随时发起一次临时同步获取最新层内容。

Where - 在哪里运行？数据存放在哪？

运行环境

• 直接在懒猫微服上执行，利用其内置的 Linux 环境与应用商店组件。
• 在应用商店中安装 OCI 镜像同步 服务即可，无需额外部署步骤。
• 

源与目标位置

• 源端：懒猫应用商店的镜像仓库，或任何网络可达的 OCI/镜像仓库（Docker Hub、GHCR、企业私服等）。
  • 你可以通过 《懒猫应用查看器》了解应用使用的的镜像
  • 
• 目标：本地目录用于离线存储、懒猫本机的《Docker 镜像源管理器》，或 NAS 能访问到的外部 registry。
  • 

How - 如何配置并操作 OCI 镜像同步？

架构流程

1. 在 Web 控制台新建同步任务或套用现有模板，填入源、目标、命名空间与标签规则。
   • 基于前面获取到的信息，在 UI 上配置即可。
   • 
2. 开始同步后，系统后台调用 Skopeo 完成 manifest 校验与镜像层复制。
   • 
3. 控制台实时展示进度与日志，必要时可暂停、重试或调整参数。
4. 同步成功后，可直接在界面中跳转到《Docker 镜像源管理器》或复制目标仓库地址。
   • 
5. 基于同步后的镜像来做分析
   • 通过成功后，镜像就在 《Docker 镜像源管理器》应用中，我们可以使用 dive 或 trivy 或其他工具来获取、分析该镜像。
   • 

基础配置步骤

1. 准备凭据
   • 获取懒猫应用商店的拉取凭据（默认为空）。
   • 如果需要访问外部仓库，准备 Basic 认证信息。
2. 图形化填写配置
   • 打开 OCI 镜像同步 控制台，输入源地址、目标地址、命名空间、标签过滤等参数。
   • 按需开启 TLS 校验、并发控制和完整性验证，并可保存为模板以便后续复用。
   • 在 高级选项 中可以将上述配置保存到后台，下次可以直接使用。
   • 
3. 预检查与验证
   • 使用“查询可用架构”功能确认凭据有效、仓库可达。
   • 
   • 出现异常时，界面会提示具体错误并提供排查建议。
4. 启动同步任务
   • 单击“开始同步”，后台自动执行传输；仪表板展示每个仓库与标签的状态。
   • 同步结束后可一键复制目标镜像地址或导出同步报告。
5. 验收与记录
   • 对同步结果使用 dive 或其他工具进行层级审查。
   • 更新依赖部署脚本或编排文件，指向新的镜像地址或仓库。

常见问题排查

• 认证失败：核对凭据是否过期、编码是否正确，必要时重新申请懒猫访问令牌。
• 证书错误：目标仓库使用自签证书时，为 Skopeo 配置自定义 CA。
• 网络瓶颈：拆分大规模任务或启用层缓存，避免重复传输。
• 标签冲突：按环境添加后缀（如 -lazycat、时间戳）避免覆盖重要镜像。

How Much - 需要投入多少成本？

时间投入

• 首次整理凭据、熟悉界面、完成首个同步模板通常在一小时内。
• 后续复用模板与计划任务后，单次同步仅需数分钟。

资源消耗

• 同步过程主要占用网络带宽，需关注大体积基础镜像的传输窗口。
• 存储压力随保留的镜像副本数量增长，可结合目标仓库的配额策略定期清理。
• CPU 占用较低，Skopeo 以流式方式传输数据，无需频繁解压。

参考资料

• OCI 镜像同步 项目文档：https://github.com/lazycatapps/image-sync/blob/main/CLAUDE.md
• Skopeo 官方仓库：https://github.com/containers/skopeo
• dive 镜像探查工具：https://github.com/wagoodman/dive