Gitea Action Runner升级

  • ~6.45K 字
  1. 1. 升级说明
    1. 1.1. 运行环境及依赖
  2. 2. 升级脚本
  3. 3. 执行升级
  4. 4. 升级后验证
  5. 5. 手动回滚
  6. 6. 常见问题
    1. 6.1. 1. wget 下载失败或返回 404
    2. 6.2. 2. SHA256 校验失败
    3. 6.3. 3. 服务无法启动
    4. 6.4. 4. 版本升级与配置兼容性
    5. 6.5. 5. Docker 部署不适用
  7. 7. 七、参考资料

gitea runner 从 1.0.0 版本开始修改仓库名称和软件名称,现脚本同步全部修改

适用环境:Linux(AMD64 / ARM64)、systemd 管理的原生二进制部署。
默认目标版本:5.4.1
可执行文件:/usr/local/bin/gitea-runner
服务名称:gitea-runner

升级说明

本文用于升级通过 systemd 运行的 Gitea Actions Runner,不是 Docker 容器中的 Runner。升级脚本会自动识别 CPU 架构,下载官方二进制压缩包及 SHA256 文件,完成校验后才停止服务并替换程序。安装或启动检查失败时尝试恢复旧版可执行文件,成功后保留 .old 备份。

升级之前应确认 Runner 没有正在执行的 CI 作业,避免中断任务。本方案仅替换程序文件,不主动修改工作目录下的 .runner 注册信息或 config.yaml 配置。

运行环境及依赖

  • 支持 x86_64 / amd64、aarch64 / arm64。
  • 使用 root 运行;需要 bash、wget、xz、sha256sum、systemctl、install。
  • 默认 gitea-runner.service 的 ExecStart 指向 /usr/local/bin/gitea-runner。
  • 目标版本使用 Gitea 官方下载源 https://dl.gitea.com/gitea-runner/。

升级脚本

保存为 upgrade-gitea-runner.sh:

#!/usr/bin/env bash
set -Eeuo pipefail

# ================= 配置 =================
VERSION="${1:-5.4.1}"
SERVICE_NAME="gitea-runner"
INSTALL_PATH="/usr/local/bin/gitea-runner"
BACKUP_PATH="${INSTALL_PATH}.old"
DOWNLOAD_BASE="https://dl.gitea.com/gitea-runner"

# ================= 基础检查 =================
if [[ $EUID -ne 0 ]]; then
    echo "错误:请使用 root 运行"
    exit 1
fi

for cmd in wget xz sha256sum systemctl install mktemp sort; do
    if ! command -v "$cmd" >/dev/null 2>&1; then
        echo "错误:缺少命令 $cmd"
        exit 1
    fi
done

case "$(uname -m)" in
    x86_64|amd64) ARCH="amd64" ;;
    aarch64|arm64) ARCH="arm64" ;;
    *) echo "错误:不支持的架构 $(uname -m)"; exit 1 ;;
esac

if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
    echo "错误:版本号必须是 x.y.z 格式"
    exit 1
fi

# 1.0.0 之前的可执行文件名为 act_runner;
# 1.0.0 及之后使用 gitea-runner。
if [[ "$(printf '%s\n' "$VERSION" '1.0.0' | sort -V | head -n 1)" == "$VERSION" && "$VERSION" != '1.0.0' ]]; then
    BINARY_NAME="act_runner-${VERSION}-linux-${ARCH}"
else
    BINARY_NAME="gitea-runner-${VERSION}-linux-${ARCH}"
fi

DOWNLOAD_URL="${DOWNLOAD_BASE}/${VERSION}/${BINARY_NAME}.xz"
CHECKSUM_URL="${DOWNLOAD_URL}.sha256"

printf '版本:%s\n架构:%s\n下载:%s\n' "$VERSION" "$ARCH" "$DOWNLOAD_URL"

TMP_DIR="$(mktemp -d)"
SERVICE_STOPPED=false
BACKUP_CREATED=false
INSTALLED_NEW=false

cleanup() {
    rm -rf -- "$TMP_DIR"
}

rollback() {
    local code=$?
    trap - ERR
    if [[ "$SERVICE_STOPPED" == true ]]; then
        echo "升级失败,开始恢复旧版本……"
        if [[ "$BACKUP_CREATED" == true && -f "$BACKUP_PATH" ]]; then
            systemctl stop "$SERVICE_NAME" || true
            cp -a -- "$BACKUP_PATH" "$INSTALL_PATH"
            if systemctl start "$SERVICE_NAME"; then
                echo "旧版本已恢复并发起启动,请继续检查日志。"
            else
                echo "错误:旧版本恢复后服务仍未启动,请手动检查。" >&2
            fi
        else
            echo "错误:没有可用的备份,请手动恢复。" >&2
        fi
    fi
    exit "$code"
}

trap cleanup EXIT
trap rollback ERR

cd "$TMP_DIR"

echo '[1/6] 下载程序及 SHA256 校验文件'
wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz" "$DOWNLOAD_URL"
wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz.sha256" "$CHECKSUM_URL"

echo '[2/6] 检查 SHA256'
sha256sum -c "${BINARY_NAME}.xz.sha256"

echo '[3/6] 解压并确认可执行文件'
xz -d "${BINARY_NAME}.xz"
chmod 0755 "$BINARY_NAME"
"./${BINARY_NAME}" --version

echo '[4/6] 停止服务并备份旧版本'
# 必须先确认服务存在、安装目标文件存在。
systemctl cat "$SERVICE_NAME" >/dev/null
[[ -f "$INSTALL_PATH" ]] || { echo "错误:找不到旧程序 $INSTALL_PATH"; exit 1; }
systemctl stop "$SERVICE_NAME"
SERVICE_STOPPED=true
cp -a -- "$INSTALL_PATH" "$BACKUP_PATH"
BACKUP_CREATED=true

echo '[5/6] 安装新版本'
install -m 0755 "$BINARY_NAME" "$INSTALL_PATH"
INSTALLED_NEW=true
"$INSTALL_PATH" --version

echo '[6/6] 启动并检查服务'
systemctl start "$SERVICE_NAME"
sleep 3
systemctl is-active --quiet "$SERVICE_NAME"

SERVICE_STOPPED=false
echo '========================================'
echo 'Gitea Runner 升级成功'
"$INSTALL_PATH" --version
echo "服务状态:$(systemctl is-active "$SERVICE_NAME")"
echo "旧版备份:$BACKUP_PATH"
echo '========================================'
systemctl --no-pager status "$SERVICE_NAME"

注意: .old 是单份备份;下一次运行该脚本会覆盖它。自动回滚仅处理脚本执行期间检测到的失败,无法保证发现启动数分钟后才发生的问题。若原程序不在上述路径,需同步修改 INSTALL_PATH 并检查 systemd 服务。

执行升级

# 授予执行权限
chmod +x upgrade-gitea-runner.sh

# 默认升级到 5.4.1
sudo ./upgrade-gitea-runner.sh

# 或显式指定版本
sudo ./upgrade-gitea-runner.sh 5.4.1

升级前可检查服务和现有版本:

systemctl cat gitea-runner
/usr/local/bin/gitea-runner --version
systemctl status gitea-runner

升级后验证

# 检查程序版本
/usr/local/bin/gitea-runner --version

# 检查服务状态
systemctl is-active gitea-runner
systemctl status gitea-runner --no-pager

# 查看最近 50 条日志
journalctl -u gitea-runner -n 50 --no-pager

# 持续观察日志
journalctl -u gitea-runner -f

除服务处于 active 外,还应在 Gitea 管理界面确认 Runner 在线,并运行一个简单的 Actions 工作流,核对作业拉取、执行和日志回传均正常。

手动回滚

升级成功后如发现兼容性问题,可恢复旧版本:

sudo systemctl stop gitea-runner
sudo cp -a /usr/local/bin/gitea-runner.old /usr/local/bin/gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner --no-pager
/usr/local/bin/gitea-runner --version

确认不再需要旧版本时,才删除备份:

sudo rm -f /usr/local/bin/gitea-runner.old

常见问题

1. wget 下载失败或返回 404

检查版本号和架构是否有对应发行文件:

5.4.1 的 Linux AMD64 / ARM64 都提供 .xz 压缩包和 .xz.sha256 校验文件。

2. SHA256 校验失败

不要继续安装;优先删除临时下载文件后重新下载。检查代理、镜像缓存或传输链路是否使压缩包与校验文件不一致。脚本默认遇错停止。

3. 服务无法启动

systemctl cat gitea-runner
journalctl -xeu gitea-runner --no-pager
systemctl status gitea-runner --no-pager

重点核对 ExecStart、WorkingDirectory、服务用户权限及配置文件路径。

4. 版本升级与配置兼容性

不同大版本可能存在配置或工作流兼容性变化。升级到 6.x 之前请阅读官方升级说明。本文以 5.4.1 为默认版本,不会自动选择最新版本。

5. Docker 部署不适用

如果 Runner 是通过 Docker Compose 运行,应更新镜像版本并重新创建容器,而不是在宿主机上替换 /usr/local/bin/gitea-runner。

七、参考资料