regbot Docker镜像文档

镜像概述和主要用途

regbot 是一款基于 Lua 的脚本工具，专为 OCI 兼容的容器注册表设计。它允许用户通过 Lua 脚本自动化容器镜像的管理操作，如镜像同步、标签清理、版本筛选等，适用于私有注册表维护、跨注册表镜像同步及自动化运维场景。

核心功能和特性

• Lua 脚本支持：通过 Lua 脚本实现灵活的镜像管理逻辑，支持条件判断、循环、函数定义等编程特性。
• OCI 兼容性：兼容 OCI（开放容器倡议）标准容器注册表，如 Docker Hub、Harbor、AWS ECR 等。
• 多注册表凭据管理：支持配置不同注册表的访问凭据（用户名/密码、TLS 配置、环境变量/文件读取凭据等）。
• 定时任务调度：支持设置脚本执行间隔，实现周期性镜像同步或清理。
• 镜像操作能力：提供镜像复制、标签删除、速率限制等待等核心操作，满足镜像生命周期管理需求。
• 并行执行与超时控制：可配置并行任务数及脚本超时时间，优化执行效率并避免资源耗尽。
• 干运行模式：支持无实际操作的测试运行，验证脚本逻辑正确性。
• 多基础镜像支持：提供基于 scratch（轻量，无额外依赖）和 alpine（含 AWS/GCP 凭据助手）的镜像标签。

使用场景和适用范围

• 私有注册表维护：同步公共镜像到私有注册表，确保内网环境可用。
• 跨注册表镜像同步：在不同环境（开发/测试/生产）的注册表间同步指定镜像及标签。
• 旧镜像自动清理：根据标签规则（如日期戳、版本号）或镜像创建时间，自动删除过期镜像。
• CI/CD 流程集成：作为流水线环节，在构建完成后同步镜像至目标注册表或清理构建产物。
• 镜像版本管理：筛选并保留指定数量的最新版本标签，避免注册表存储膨胀。

可用标签

注意：scratch 基础镜像不含 shell 及凭据助手，仅包含 regbot 可执行文件；alpine 基础镜像基于发布时的最新 Alpine 版本，预安装 AWS 和 Google Cloud 凭据助手。

环境准备

部署本地注册表（可选）

若需测试 regbot 功能，可先部署一个本地 OCI 注册表（以 Docker Registry 2 为例）：

shell
# 创建专用网络
docker network create registry

# 启动注册表容器（支持删除操作，禁用验证）
docker run -d --restart=unless-stopped --name registry --net registry \
  -e "REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry" \
  -e "REGISTRY_STORAGE_DELETE_ENABLED=true" \
  -e "REGISTRY_VALIDATION_DISABLED=true" \
  -v "registry-data:/var/lib/registry" \
  -p "127.0.0.1:5000:5000" \
  registry:2

注册表数据存储在 registry-data 卷中，端口映射至本地 5000 端口，仅允许本地访问。

配置说明

regbot 通过 YAML 配置文件定义凭据、默认参数及脚本逻辑。核心配置文件为 regbot.yml，结构如下：

配置文件结构（regbot.yml）

yaml
version: 1  # 配置文件版本（当前仅支持 1）
creds:  # 注册表凭据配置（可配置多个）
  - registry: registry:5000  # 注册表地址
    tls: disabled  # TLS 配置（enabled/disabled）
    scheme: http  # 协议（http/https）
  - registry: docker.io  # Docker Hub 注册表
    user: "{{env \"HUB_USER\"}}"  # 从环境变量读取用户名
    pass: "{{file \"/var/run/secrets/hub_token\"}}"  # 从文件读取密码/令牌
defaults:  # 全局默认参数（可被脚本级参数覆盖）
  parallel: 2  # 并行任务数
  interval: 60m  # 脚本执行间隔（定时模式）
  timeout: 600s  # 脚本超时时间
scripts:  # 脚本列表（按顺序执行）
  - name: 镜像同步示例  # 脚本名称
    timeout: 59m  # 脚本级超时（覆盖默认）
    script: |  # Lua 脚本内容
      # 镜像同步逻辑（详见下文示例）

关键配置项说明

• creds：定义访问各注册表的凭据，支持字段：

  • registry：注册表域名或地址（如 docker.io、registry:5000）。
  • tls：是否启用 TLS（enabled 或 disabled）。
  • scheme：协议（http 或 https）。
  • user：登录用户名（支持 {{env "VAR"}} 从环境变量读取，{{file "path"}} 从文件读取）。
  • pass：登录密码/令牌（同 user 支持动态读取）。

• defaults：全局默认参数，作用于所有脚本（脚本级配置可覆盖）：

  • parallel：并行执行的任务数（如同时同步多个镜像）。
  • interval：定时模式下的脚本执行间隔（如 30m、1h）。
  • timeout：脚本执行超时时间（如 600s）。

• scripts：脚本列表，每个脚本包含：

  • name：脚本名称（标识用途）。
  • timeout：脚本超时时间（覆盖 defaults.timeout）。
  • script：Lua 脚本内容，实现具体逻辑（如镜像复制、标签删除）。

示例配置（regbot.yml）

以下为包含镜像同步、旧标签清理的完整配置示例：

yaml
version: 1
creds:
  - registry: registry:5000  # 本地注册表（上文部署的 registry:2）
    tls: disabled
    scheme: http
  - registry: docker.io  # Docker Hub
    user: "{{env \"HUB_USER\"}}"  # 从环境变量 HUB_USER 获取用户名
    pass: "{{file \"/var/run/secrets/hub_token\"}}"  # 从挂载文件获取密码
defaults:
  parallel: 2
  interval: 60m
  timeout: 600s
scripts:
  - name: 同步最新 minor 版本镜像
    timeout: 59m
    script: |
      imageList = {"library/alpine", "library/debian"}  # 待同步镜像列表
      localReg = "registry:5000"  # 目标本地注册表
      tagExp = "^%d+%.%d+$"  # 匹配 minor 版本标签（如 3.18、12.4）
      maxKeep = 3  # 保留最新 3 个版本

      # Lua 脚本逻辑：筛选上游标签 → 排序 → 复制至本地注册表
      for k, imageName in ipairs(imageList) do
        upstreamRef = reference.new(imageName)  # 上游镜像引用
        localRef = reference.new(localReg .. "/" .. imageName)  # 本地镜像引用
        tags = tag.ls(upstreamRef)  # 获取上游镜像标签列表
        matchTags = {}
        for _, t in pairs(tags) do
          if string.match(t, tagExp) then  # 筛选符合规则的标签
            table.insert(matchTags, t)
          end
        end
        table.sort(matchTags)  # 排序标签
        if #matchTags > maxKeep then
          matchTags = {unpack(matchTags, #matchTags - maxKeep + 1)}  # 保留最新 3 个
        end
        for _, t in ipairs(matchTags) do
          upstreamRef:tag(t)  # 设置上游标签
          localRef:tag(t)  # 设置本地标签
          image.copy(upstreamRef, localRef)  # 复制镜像
        end
      end

  - name: 清理旧 CI 镜像
    script: |
      imageName = "registry:5000/regclient/example"  # 本地示例镜像
      tagExp = "^ci%-%d+$"  # 匹配 CI 标签（如 ci-001）
      maxDays = 30  # 保留 30 天内的镜像
      imageLabel = "org.opencontainers.image.created"  # 创建时间标签

      # 计算过期时间阈值
      timeRef = os.time() - (86400*maxDays)
      cutoff = os.date("!%Y-%m-%dT%H:%M:%SZ", timeRef)
      ref = reference.new(imageName)
      tags = tag.ls(ref)  # 获取本地镜像标签
      for _, t in pairs(tags) do
        if string.match(t, tagExp) then
          ref:tag(t)
          ic = image.config(ref)  # 获取镜像配置
          if ic.Config.Labels[imageLabel] < cutoff then  # 检查创建时间
            tag.delete(ref)  # 删除过期标签
          end
        end
      end

使用方法

1. 工具准备（regctl）

regctl 是 regclient 工具集的一部分，用于与注册表交互（如查看标签、复制镜像）。可通过 Docker 快速部署：

shell
cat >regctl <<EOF
#!/bin/sh
docker container run -it --rm --net host \
  -u "\$(id -u):\$(id -g)" -e HOME -v \$HOME:\$HOME \
  -v /etc/docker/certs.d:/etc/docker/certs.d:ro \
  regclient/regctl:latest "\$@"
EOF
chmod 755 regctl

# 配置本地注册表（registry:5000）支持 HTTP
./regctl registry set --scheme http --tls disabled localhost:5000

2. 加载示例镜像（可选）

为测试清理逻辑，可向本地注册表推送示例镜像：

shell
# 复制 regctl 镜像至本地注册表
./regctl image copy regclient/regctl:v0.0.1 localhost:5000/regclient/example:latest && \
# 创建多个 CI 标签镜像（模拟历史构建）
./regctl image copy localhost:5000/regclient/example:latest localhost:5000/regclient/example:ci-001 && \
./regctl image copy localhost:5000/regclient/example:latest localhost:5000/regclient/example:ci-002 && \
./regctl image copy localhost:5000/regclient/example:latest localhost:5000/regclient/example:ci-003

3. 运行模式

regbot 支持三种运行模式：干运行（测试逻辑）、立即执行（单次运行）、定时任务（周期性执行）。

3.1 干运行（测试脚本）

验证脚本逻辑，不执行实际镜像操作：

shell
export HUB_USER="你的 Docker Hub 用户名"
echo "你的 Docker Hub 密码或 PAT" > hub_token  # 创建密码文件
docker run -it --rm --net registry \
  -e "HUB_USER" \
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \
  -v "$(pwd)/regbot.yml:/home/appuser/regbot.yml" \
  regclient/regbot:latest -c /home/appuser/regbot.yml once --dry-run

输出将显示脚本计划执行的操作（如“复制镜像 library/alpine:3.18 至 registry:5000”），但不会实际执行。

3.2 立即执行（单次运行）

执行脚本并实际操作镜像（需确保凭据正确）：

shell
docker run -it --rm --net registry \
  -e "HUB_USER" \
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \
  -v "$(pwd)/regbot.yml:/home/appuser/regbot.yml" \
  regclient/regbot:latest -c /home/appuser/regbot.yml once

3.3 定时任务（后台运行）

以守护进程模式运行，按 defaults.interval 周期性执行脚本：

shell
docker run -d --restart=unless-stopped --name regbot --net registry \
  -e "HUB_USER" \
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \
  -v "$(pwd)/regbot.yml:/home/appuser/regbot.yml" \
  regclient/regbot:latest -c /home/appuser/regbot.yml server -v debug

日志级别通过 -v debug 设置（可选：info/warn/error），容器重启策略为 unless-stopped（异常退出后自动重启）。

4. 验证结果

使用 regctl 检查镜像同步及清理效果：

shell
# 查看本地注册表镜像列表
./regctl repo ls localhost:5000

# 查看指定镜像标签（如同步的 alpine 镜像）
./regctl tag ls localhost:5000/library/alpine

# 查看清理后的 CI 镜像标签（应保留最新 3 个）
./regctl tag ls localhost:5000/regclient/example

部署示例

docker-compose 配置（定时任务模式）

创建 docker-compose.yml，简化 regbot 部署：

yaml
version: "3.8"
services:
  regbot:
    image: regclient/regbot:latest
    container_name: regbot
    restart: unless-stopped
    networks:
      - registry
    environment:
      - HUB_USER=你的 Docker Hub 用户名
    volumes:
      - ./regbot.yml:/home/appuser/regbot.yml:ro
      - ./hub_token:/var/run/secrets/hub_token:ro
    command: -c /home/appuser/regbot.yml server -v info

networks:
  registry:
    external: true  # 使用前文创建的 registry 网络

启动服务：

shell
docker-compose up -d

重要链接

• 项目官网：regclient.org
• 安装指南：regclient.org/install/
• 命令行参考：regclient.org/cli/regbot/
• 源码仓库：github.com/regclient/regclient
• 发布版本：github.com/regclient/regclient/releases
• 贡献指南：CONTRIBUTING.md