镜像仓库缓存

镜像仓库缓存是一个官方应用，用于在微擎面板中管理镜像拉取加速和镜像仓库缓存能力。它适合处理“如何让集群从远端镜像仓库拉取镜像更稳定、更快，并减少重复回源压力”这类场景。

项目已开源：

• https://github.com/w7panel/w7panel-registrycache

这个应用能做什么

从当前前后端能力看，镜像仓库缓存主要覆盖下面几类事情：

• 配置缓存仓库地址
• 配置源仓库列表
• 配置源仓库认证信息
• 配置镜像缓存规则
• 通过命名空间前缀重写缓存路径
• 通过代理方式拉取远端仓库内容并缓存 manifest / blob
• 根据规则选择源仓库并处理缓存回源

如果你的目标是让镜像拉取更稳定、减少重复回源流量，或者需要在私有环境中统一管理镜像缓存入口，这个应用会更合适。

主要页面怎么理解

根据当前前端路由，这个应用主要围绕两类页面展开：

• 缓存仓库列表页
• 缓存仓库设置页

其中：

• 列表页 更偏缓存仓库的查看、进入和删除
• 设置页 更偏缓存仓库地址、源仓库、缓存规则和代理认证的配置

一、从哪里开始最合适

如果你是第一次使用镜像仓库缓存，建议按下面顺序开始：

1. 先进入缓存仓库列表页
2. 新增一个缓存仓库配置
3. 先配置缓存仓库地址
4. 再配置源仓库列表和认证信息
5. 最后配置镜像缓存规则和命名空间前缀
6. 再让集群按该入口拉取镜像，观察是否命中缓存

这个顺序更符合真实接入过程，也更容易判断问题出在仓库配置、认证、规则还是回源本身。

二、缓存仓库列表页可以做什么

列表页是最基础的入口，当前至少支持：

• 查看已配置的缓存仓库
• 新增缓存仓库
• 进入某个缓存仓库的设置页
• 删除不再使用的缓存仓库

如果你只是想确认当前哪些缓存仓库已经接入，通常先看列表页就够了。

三、设置页里最重要的几块配置

进入某个缓存仓库后，设置页主要围绕这些内容展开：

• 缓存仓库配置
• 源仓库配置
• 镜像缓存规则
• 命名空间前缀
• 代理配置

可以简单理解成：

• 缓存仓库：镜像缓存最终存到哪里
• 源仓库：镜像实际从哪些远端仓库回源
• 缓存规则：哪些镜像要缓存、按什么规则匹配
• 命名空间前缀：缓存后的镜像路径怎么重写
• 代理配置：访问源仓库时是否需要通过代理

四、缓存仓库怎么理解

缓存仓库不是“你真正开发镜像的源仓库”，而是面板里的缓存落点。

当前后端能力里已经明确包含：

• cache_registry
• server_url
• cache_namespace_prefix

这意味着你需要先决定：

• 缓存内容最终落到哪个仓库地址
• 是否需要给缓存内容统一加命名空间前缀

如果缓存仓库本身没配置对，后面的源仓库和缓存规则即使都正确，也无法形成稳定的缓存链路。

五、源仓库和认证怎么理解

源仓库用于告诉系统：镜像真正可以从哪些远端仓库回源。

当前实现中，源仓库配置至少包含：

• 仓库地址
• 用户名
• 密码
• 代理配置

这意味着如果你的源仓库需要认证，或者你的网络环境必须走代理，就必须在这里补齐。

什么时候优先检查源仓库配置

如果你遇到下面这些问题，通常要先回到源仓库配置：

• 镜像始终拉取失败
• manifest 或 blob 一直无法回源
• 某个远端仓库需要认证但没有成功通过
• 代理环境下无法访问目标仓库

六、镜像缓存规则怎么理解

镜像缓存规则用于决定：

• 哪些仓库名要走缓存
• 按什么方式匹配
• 缓存多久
• 是否启用分布式缓存
• 是否强制指定某个源仓库

当前后端已经明确支持这些匹配方式：

• fix
• prefix
• regex
• all

如果你的目标是只缓存一部分镜像，或者不同仓库走不同源站和不同策略，就应该重点配置这里。

七、命名空间前缀什么时候有用

命名空间前缀主要用来重写缓存后的镜像路径。

如果你希望：

• 所有缓存后的镜像统一落到某个命名空间下
• 推送和拉取路径更规整
• 缓存仓库里的镜像路径更容易管理

那就需要配置这部分。

如果命名空间前缀没处理好，常见现象就是：

• 拉取地址看起来不一致
• 鉴权 scope 不匹配
• 缓存路径和预期不同

八、代理什么时候会影响镜像缓存

当前实现里，源仓库支持独立的代理配置。

这意味着在某些网络环境下，你不一定是“直接访问源仓库”，而是通过代理访问。

如果你在受限网络、跨区域网络或需要统一出口的环境里使用镜像缓存，就要优先检查代理配置是否正确。

九、缓存工作流怎么理解

从后端逻辑看，镜像仓库缓存的真实工作流大致是：

1. 用户发起镜像拉取请求
2. 系统先检查缓存仓库里是否已有对应 manifest / blob
3. 如果命中缓存，直接返回缓存内容
4. 如果未命中，则按规则选择源仓库回源
5. 获取内容后，再把结果同步写入缓存仓库

这也是为什么它不仅是一个“配置页”，而是一条完整的回源与缓存链路。

十、常见使用链路

如果你是第一次使用镜像仓库缓存，通常可以按下面顺序操作：

1. 新增一个缓存仓库配置
2. 配置缓存仓库地址
3. 添加一个或多个源仓库
4. 补齐认证和代理信息
5. 配置镜像缓存规则
6. 根据需要设置命名空间前缀
7. 再让集群按该入口拉取镜像，观察是否命中缓存

这条链路更适合实际接入和后续维护，而不是只停留在“把仓库地址填进去”。

十一、什么时候优先检查这个应用本身

如果你遇到下面这些情况，通常要先回到镜像仓库缓存应用里排查：

• 镜像始终没有命中缓存
• 回源仓库访问失败
• 认证信息不正确导致拉取异常
• 命名空间前缀导致镜像路径不符合预期
• 规则已经配置，但仍然没有按预期走缓存

使用建议

• 先把缓存仓库和源仓库配置清楚，再细调缓存规则
• 规则、认证、代理最好分开逐步调整，方便判断是哪一层有问题
• 如果你要管理多个源仓库，尽早规划命名空间和规则结构
• 出现异常时，先区分是“缓存未命中”“回源失败”还是“认证 / 路径问题”

镜像仓库缓存的价值，在于把“缓存仓库、源仓库、认证、规则和回源链路”这些原本分散的工作，整理成一套可在面板里持续维护的镜像拉取加速能力。