Gitea Workflow 实践：通过镜像站加速 JDK 下载

25 Aug, 2025

背景

Gitea Actions 的 actions/setup-java 在执行时，会根据指定的 Java 版本从 Adoptium (Temurin) 的 GitHub Releases 页面下载对应的 JDK。在国内或网络受限的环境下，通常以超时告终。

原理：利用 Runner 缓存

actions/setup-java 的核心机制在于其缓存策略。在执行下载前，它会检查 Runner 的工具缓存目录（默认为 /opt/hostedtoolcache）中是否存在所需版本的 JDK。如果缓存命中，它将直接使用本地文件，完全跳过下载步骤。

利用这一点：通过手动或自动化的方式，预先将指定版本的 JDK 下载、解压并放置到正确的缓存目录中。

方法一：手动预热缓存（命令行）

对于一次性或临时的需求，我们可以直接进入 Runner 所在的容器或主机，手动下载并设置缓存。这种方法简单直接，适合快速验证。

进入 Runner 环境

docker run --rm -it -v act-toolcache:/cache alpine sh

执行下载和缓存脚本

在容器内，执行以下脚本。请将 TARGET_DIR 和 DOWNLOAD_URL 中的版本号和下载链接替换为你需要的 JDK 版本。

# 1. 安装必要的工具
apk add --no-cache wget tar

# 2. 定义目标路径和下载地址（以 Temurin JDK 21.0.8+9 为例）
# 缓存路径格式为：/cache/<工具名>/<版本号>/<架构>
TARGET_DIR="/cache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64"
DOWNLOAD_URL="https://ghfast.top/https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.8%2B9/OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz"

# 3. 创建目录、下载并解压
mkdir -p "${TARGET_DIR}"
cd /tmp

echo "Downloading from ${DOWNLOAD_URL}..."
wget -q -O tool.tar.gz "${DOWNLOAD_URL}"

# --strip-components=1 用于去除压缩包内的顶层目录
tar -xzf tool.tar.gz -C "${TARGET_DIR}" --strip-components=1

# 4. 创建完成标记文件（重要！）
# setup-java 通过检查此文件判断缓存是否完整
touch "${TARGET_DIR}.complete"

# 5. 清理临时文件
rm tool.tar.gz
echo "JDK cache created successfully at ${TARGET_DIR}"

方法二：使用 workflow_dispatch 自动化缓存

手动操作虽然直接，但难以维护和扩展。更优雅的方式是创建一个可手动触发的 Gitea Workflow，让 Runner 自己完成缓存的下载和设置。workflow_dispatch 事件允许我们从 Gitea 界面手动触发工作流，并传入参数（如 JDK 版本），非常适合此类管理任务。

53 collapsed lines
name: Runner Tool Cache Seeder
run-name: Seeding cache for ${{ inputs.tool_type }} version ${{ inputs.tool_version }}

env:
  # 使用镜像站代理，可替换为你自己的代理
  github_proxy: https://ghfast.top/

on:
  workflow_dispatch:
    inputs:
      tool_type:
        description: '要缓存的工具类型 (目前支持 temurin-jdk)'
        required: true
        type: choice
        options:
          - temurin-jdk
      tool_version:
        description: '要缓存的工具确切版本 (例如: 21.0.8+9.0.LTS, 21.0.8+9, 17.0.11+9)'
        required: true
        type: string

jobs:
  seed-cache:
    runs-on: ubuntu-latest # 可以指定你的 Runner 标签
    steps:
      - name: Seed Tool Cache
        shell: bash
        run: |
          set -e # 若有命令失败，立即退出

          GITHUB_PROXY="${{ env.github_proxy }}"
          TOOL_TYPE="${{ inputs.tool_type }}"
          TOOL_VERSION="${{ inputs.tool_version }}"
          TOOL_CACHE_DIR="/opt/hostedtoolcache" # Runner 的工具缓存目录

          echo "Attempting to cache ${TOOL_TYPE} version ${TOOL_VERSION}..."

          # 自动检测系统架构
          ARCH=$(uname -m)
          case "$ARCH" in
            x86_64)   ARCH_NAME="x64" ;;
            aarch64)  ARCH_NAME="aarch64" ;;
            arm64)    ARCH_NAME="aarch64" ;;
            *)
            echo "Unsupported architecture: $ARCH" && exit 1 ;;
          esac

          LTS_SUFFIX=""
          # 根据 Adoptium 的命名规则，LTS 版本有特定后缀
          if [[ "${TOOL_VERSION}" == *".LTS" ]]; then
            LTS_SUFFIX=".0.LTS"
          fi

          # 解析版本号以构建正确的下载链接和缓存路径
          MAIN_VERSION=${TOOL_VERSION%%.*}         # 主版本, e.g., "21"
          VERSION_PART=${TOOL_VERSION%+*}          # 版本部分, e.g., "21.0.8"
          AFTER_PLUS=${TOOL_VERSION#*+}            # `+`号后的部分, e.g., "9" or "9.0.LTS"
          BUILD_PART=${AFTER_PLUS%%.*}              # 构建号, e.g., "9"

          # 拼接缓存目标路径
          TARGET_DIR="${TOOL_CACHE_DIR}/Java_Temurin-Hotspot_jdk/${VERSION_PART}-${BUILD_PART}${LTS_SUFFIX}/${ARCH_NAME}"

          if [ -f "${TARGET_DIR}.complete" ]; then
            echo "Java version ${TOOL_VERSION} for ${ARCH_NAME} is already cached. Skipping."
            exit 0
          fi

          # 拼接下载 URL
          # 示例: https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.8%2B9/OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz

          DOWNLOAD_URL="${GITHUB_PROXY}https://github.com/adoptium/temurin${MAIN_VERSION}-binaries/releases/download/jdk-${VERSION_PART}%2B${BUILD_PART}/OpenJDK${MAIN_VERSION}U-jdk_${ARCH_NAME}_linux_hotspot_${VERSION_PART}_${BUILD_PART}.tar.gz"
18 collapsed lines

          echo "Target cache directory: ${TARGET_DIR}"
          echo "Download URL: ${DOWNLOAD_URL}"

          mkdir -p "${TARGET_DIR}"
          cd /tmp

          echo "Downloading tool..."
          wget -q -O tool.tar.gz "${DOWNLOAD_URL}"

          echo "Extracting tool into cache directory..."
          tar -xzf tool.tar.gz -C "${TARGET_DIR}" --strip-components=1

          echo "Creating completion file..."
          touch "${TARGET_DIR}.complete"

          rm tool.tar.gz
          echo "Successfully cached ${TOOL_TYPE} version ${TOOL_VERSION} for ${ARCH_NAME}."

使用说明

将以上 YAML 文件保存到你的 Gitea 仓库的 .gitea/workflows/ 目录下（例如 cache-seeder.yaml）。
进入 Gitea 项目的 Actions 页面。
在左侧工作流列表中找到 “Runner Tool Cache Seeder”。
点击 Run workflow 按钮。
在弹出的表单中，选择工具类型（temurin-jdk）并输入你想要缓存的确切 JDK 版本（如 21.0.8+9）。
点击绿色的 Run workflow 按钮执行。

#action #study