KuzuDB 镜像迁移至 GitHub Container Registry 的技术实践

背景与挑战

随着主流容器镜像仓库在 2025 年 4 月 1 日开始实施未认证用户每小时 10 次镜像拉取的限制，KuzuDB 项目面临着用户拉取 Explorer、MCP server 和 API server 镜像可能受限的问题。这一变更不仅影响终端用户的使用体验，也对项目内部运维造成了挑战，特别是托管在公共容器仓库上的扩展服务器和开发文档服务。

解决方案

项目团队决定采取双管齐下的策略：

1. 内部镜像迁移：将项目内部使用的镜像（如扩展服务器和开发文档服务）完全迁移至 GitHub Container Registry (ghcr.io)
2. 用户镜像镜像：对用户直接使用的镜像（如 Explorer、MCP server 和 API server）实施双向镜像策略，同时在主流容器仓库和 ghcr.io 上提供

实施过程

迁移工作分为两个主要阶段：

第一阶段：内部服务迁移

项目成员 mewim 首先完成了对扩展仓库和开发文档的迁移工作，作为 Web 服务器重新分配的一部分。这一阶段主要涉及：

• 更新 CI/CD 流水线中的镜像推送目标
• 修改相关部署配置以指向新的镜像仓库
• 验证服务在新仓库下的可用性和性能

第二阶段：用户镜像镜像

在确认内部服务迁移成功后，团队开始处理用户直接使用的镜像：

1. MCP Server 镜像：

   • 更新构建脚本支持多仓库推送
   • 配置自动镜像同步机制
   • 测试不同区域的拉取速度

2. API Server 镜像：

   • 实现构建后自动推送到双仓库
   • 更新文档中的镜像引用说明
   • 确保版本标签在两个仓库中保持同步

技术细节

在实施过程中，团队解决了几个关键技术问题：

1. 认证机制：配置 GitHub Actions 使用适当的权限访问 ghcr.io
2. 存储优化：利用 GitHub Packages 的存储特性优化镜像层存储
3. 回退方案：保留主流容器仓库作为备份，确保服务连续性
4. 监控机制：建立对两个仓库可用性的监控

成果与收益

完成迁移后，KuzuDB 项目获得了以下优势：

1. 可靠性提升：通过多仓库部署，降低了单点故障风险
2. 性能改善：ghcr.io 的全球 CDN 加速了部分地区用户的拉取速度
3. 成本优化：GitHub Packages 为开源项目提供更慷慨的配额
4. 用户体验：用户可以根据网络状况选择最优的镜像源

最佳实践总结

基于此次迁移经验，我们总结出以下容器镜像管理的最佳实践：

1. 多仓库策略：关键镜像应在至少两个主要仓库中保持同步
2. 自动化同步：建立自动化的镜像同步机制，减少人工干预
3. 文档透明：清晰告知用户可用的镜像源及其差异
4. 定期验证：建立定期验证机制，确保各仓库的镜像一致性

此次迁移不仅解决了主流容器仓库限制带来的直接问题，还为 KuzuDB 项目的长期发展建立了更健壮的镜像分发基础设施。