tunathu/rubygems-mirror

RubyGems镜像Docker环境

镜像概述

本Docker镜像提供了一个便捷的环境，用于搭建本地或私有RubyGems镜像服务。RubyGems镜像是存储Ruby库（gems）的服务器，可缓存上游RubyGems源的包，实现依赖包的本地存储与快速分发，解决外部网络依赖问题并提升Ruby项目构建效率。

核心功能与特性

• 本地缓存：自动缓存从上游源获取的RubyGems包，避免重复下载
• 访问：通过本地网络提供gems包，显著提升gem install等命令的执行速度
• 离线支持：缓存完成后，即使断开外部网络，仍可通过本地镜像安装已缓存的依赖
• 配置灵活：支持自定义上游源地址、服务端口、缓存路径等关键参数
• 轻量部署：基于精简基础镜像构建，资源占用低，部署流程简单

使用场景

• 企业内网环境：在无法访问公网RubyGems源（如[***]
• 高频构建场景：CI/CD流水线或频繁构建Ruby项目的环境，减少重复下载耗时
• 教学/演示环境：确保培训或演示过程中依赖包可稳定获取，不受网络波动影响
• 私有镜像管理：结合权限控制，搭建企业级私有RubyGems源，管理内部开发的gems包

使用方法

快速启动（docker run）

通过以下命令快速启动RubyGems镜像服务：

bash
docker run -d \
  --name rubygems-mirror \
  -p 8080:8080 \
  -v /path/to/local/cache:/app/cache \
  -e SOURCE_URL=https://rubygems.org \
  docker.xuanyuan.run/rubygems-mirror:latest

参数说明：

• -p 8080:8080：将容器内8080端口映射到主机8080端口（可自定义主机端口）
• -v /path/to/local/cache:/app/cache：挂载本地目录作为缓存卷，持久化存储gems包（避免容器重启后缓存丢失）
• -e SOURCE_URL：指定上游RubyGems源地址（默认值：[***]

Docker Compose配置

创建docker-compose.yml文件简化部署：

yaml
version: '3'
services:
  rubygems-mirror:
    image: docker.xuanyuan.run/rubygems-mirror:latest
    container_name: rubygems-mirror
    ports:
      - "8080:8080"
    volumes:
      - ./gem-cache:/app/cache  # 本地缓存目录
    environment:
      - SOURCE_URL=https://rubygems.org  # 上游源地址
      - PORT=8080  # 服务端口
      - CACHE_TTL=3600  # 缓存过期时间（秒，默认3600）
    restart: unless-stopped  # 容器退出后自动重启

启动服务：

bash
docker-compose up -d

验证服务可用性

服务启动后，可通过以下步骤验证：

1. 访问http://localhost:8080，若返回RubyGems镜像服务页面，说明服务运行正常
2. 在Ruby环境中添加本地镜像源：

   bash
   gem sources --add http://localhost:8080
   gem sources --remove https://rubygems.org  # 可选：移除默认源，仅使用本地镜像
   

3. 测试安装依赖：

   bash
   gem install rails  # 首次安装会从上游源同步并缓存，后续安装直接使用本地缓存
   

配置说明

环境变量

持久化配置

建议通过-v参数挂载本地目录到CACHE_DIR（默认/app/cache），确保容器重建后缓存数据不丢失。对于生产环境，可结合NFS或分布式存储进一步提升可靠性。

注意事项

• 首次启动时，镜像服务需从上游源同步元数据，可能需要几分钟时间（取决于网络速度）
• 若需切换上游源（如使用国内镜像源https://gems.ruby-china.com），修改SOURCE_URL环境变量即可
• 当MAX_CACHE_SIZE达到阈值时，服务会自动清理最旧的缓存文件，释放空间