13 KiB

Raw Permalink Blame History

🚀 Gitea Runner Docker 部署教程

📋 目录

简介
目录结构
版本选择
部署步骤
管理命令
Buildx 多架构构建示例
版本对比
常见问题

💡 简介

Gitea Runner 是 Gitea 的 CI/CD 执行器,类似于 GitLab Runner 或 GitHub Actions Runner,用于执行 Gitea Actions 工作流。

本项目提供了标准版和 Buildx 版两种部署方案,通过预设配置快速部署。

📂 目录结构

docker-runner/
├── common/                    # 通用脚本(所有版本共用)
│   ├── check_crlf.sh         # Windows 换行符检查工具
│   ├── entrypoint.sh         # 容器启动脚本
│   ├── setup.sh              # Runner 安装脚本
│   ├── register.sh           # Runner 注册脚本
│   └── manage.sh             # Runner 管理脚本
│
└── presets/                   # 预设配置(选择一个使用)
    ├── standard-ubuntu-22/    # 标准版 (Ubuntu 22.04)
    │   ├── Dockerfile
    │   └── docker-compose.yml
    ├── buildx-ubuntu-22/      # Buildx 版 (Ubuntu 22.04)
    │   ├── Dockerfile
    │   └── docker-compose.yml
    └── buildx-archlinux/      # Buildx 版 (Arch Linux)
        ├── Dockerfile
        └── docker-compose.yml

说明:

common/ 目录中的脚本由所有版本共享,通过 docker-compose.yml 挂载到容器
presets/ 目录中每个子目录是一个完整的预设配置,包含 Dockerfile 和 docker-compose.yml
数据持久化在 runner-data/ 目录(自动创建),包含 runner 配置、缓存和 act_runner 二进制文件

🎯 版本选择

📦 标准版(推荐)

适合场景:

✅ 大多数日常使用场景
✅ 只需在当前架构上运行应用
✅ 简单的 CI/CD 流程
✅ 不需要构建多架构容器镜像

特点:

🪶 轻量级,镜像体积约 400MB
⚡ 配置简单,启动快速(5-10 秒)
🔒 无需特权模式,更安全
🎯 易于维护

预设: presets/standard-ubuntu-22/

🚀 Buildx 多架构版

适合场景:

✅ 需要构建 arm64 + amd64 双架构镜像
✅ 发布容器镜像到公共仓库
✅ 跨平台应用开发和测试
✅ 高级 CI/CD 需求

特点:

🌐 支持 Docker Buildx 多架构构建
🔧 内置 QEMU 跨架构模拟
🤖 自动配置 Buildx builder
⚠️ 需要特权模式和 Docker socket

预设选择:

presets/buildx-ubuntu-22/ - Ubuntu 22.04 基础(推荐)
presets/buildx-archlinux/ - Arch Linux 滚动更新版本

🚀 部署步骤

标准版部署

1. 进入预设目录

cd docker-runner/presets/standard-ubuntu-22/

2. (可选)检查换行符

如果从 Windows 复制文件,建议检查换行符:

../../common/check_crlf.sh

3. 构建并启动容器

docker-compose build
docker-compose up -d

4. 安装 Runner

docker-compose exec gitea-runner /data/setup.sh

按照提示选择版本(默认 0.2.13)和架构(自动检测)。

5. 注册 Runner

docker-compose exec gitea-runner /data/register.sh

输入你的 Gitea 实例 URL 和注册令牌。

Runner 注册后会自动启动,无需重启容器。

6. 验证运行状态

# 查看容器日志
docker-compose logs -f

# 查看 runner 状态
docker-compose exec gitea-runner /data/manage.sh status

Buildx 版部署

1. 选择并进入预设目录

# Ubuntu 22.04 版本(推荐)
cd docker-runner/presets/buildx-ubuntu-22/

# 或 Arch Linux 版本
cd docker-runner/presets/buildx-archlinux/

2. (可选)配置代理

如果需要代理,编辑 docker-compose.yml 取消注释并修改代理地址:

environment:
  - http_proxy=http://host.docker.internal:20122
  - https_proxy=http://host.docker.internal:20122

3. 构建并启动

docker-compose build
docker-compose up -d

4. 验证 Buildx 初始化

# 查看日志,应该看到:
# ✓ Docker daemon is ready
# ✓ arm64 support verified
# ✓ amd64 support verified
# ✓ Buildx configured successfully!
docker-compose logs -f

# 进入容器验证
docker-compose exec gitea-runner docker buildx ls
# 应该看到 gitea-multiarch builder

5. 安装和注册

docker-compose exec gitea-runner /data/setup.sh
docker-compose exec gitea-runner /data/register.sh

Runner 注册后会自动启动。

🔧 管理命令

所有版本的管理命令相同(脚本位于 common/ 目录):

查看状态

# 列出所有 runners
docker-compose exec gitea-runner /data/manage.sh list

# 查看所有 runners 状态
docker-compose exec gitea-runner /data/manage.sh status

日志管理

# 查看日志(最后 50 行)
docker-compose exec gitea-runner /data/manage.sh logs <runner-name>

# 指定行数
docker-compose exec gitea-runner /data/manage.sh logs <runner-name> 100

# 实时跟踪日志
docker-compose exec gitea-runner /data/manage.sh follow <runner-name>

Runner 控制

# 启动 runner
docker-compose exec gitea-runner /data/manage.sh start <runner-name>

# 停止 runner
docker-compose exec gitea-runner /data/manage.sh stop <runner-name>

# 重启 runner
docker-compose exec gitea-runner /data/manage.sh restart <runner-name>

# 删除 runner
docker-compose exec gitea-runner /data/manage.sh delete <runner-name>

添加多个 Runners

# 注册新的 runner(使用不同名称)
docker-compose exec gitea-runner /data/register.sh

交互式管理

# 运行交互式菜单
docker-compose exec gitea-runner /data/manage.sh

🔧 Buildx 多架构构建示例

示例 1: 基础构建

在 Gitea Actions workflow 中使用:

name: Multi-Arch Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v2

      - name: Set up Buildx
        uses: docker/setup-buildx-action@v2

      - name: Build and Push
        uses: docker/build-push-action@v4
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          tags: myapp:latest
          push: true

示例 2: Go 应用优化构建

使用交叉编译可以大幅提升构建速度:

FROM --platform=$BUILDPLATFORM golang:1.21 AS builder
ARG TARGETOS TARGETARCH
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o app

FROM alpine
COPY --from=builder /app/app /app
CMD ["/app"]

示例 3: 启用构建缓存

- name: Build with cache
  uses: docker/build-push-action@v4
  with:
    context: .
    platforms: linux/amd64,linux/arm64
    cache-from: type=registry,ref=myimage:buildcache
    cache-to: type=registry,ref=myimage:buildcache,mode=max
    tags: myimage:latest
    push: true

⚖️ 版本对比

功能对比表

功能	标准版	Buildx 版
基础 Runner 功能	✅	✅
当前架构原生构建	✅	✅
跨架构模拟构建	❌	✅
多架构镜像	❌	✅
Buildx 支持	❌	✅
QEMU 内置	❌	✅
特权模式要求	❌	✅ 必需
Docker socket	可选	✅ 必需
镜像大小	~400MB	~850MB
启动时间	5-10 秒	15-20 秒
复杂度	简单	中等

性能对比(Buildx 版)

在 ARM64 主机上使用 Buildx 构建不同架构的性能:

项目类型	ARM64(原生)	AMD64(QEMU)	双架构并行
Alpine 镜像	5s	15s	18s
Node.js 应用	2min	8min	9min
Go 应用	1.5min	6min	7min
Go(交叉编译)	1min	1.5min	2min

关键发现:

🏆 原生架构构建最快
🐌 跨架构模拟慢 3-4 倍(QEMU)
⚡ 交叉编译比纯 QEMU 快 4 倍
💾 使用缓存可提速 80-90%

🎯 选择建议

选择标准版

✅ 只需要在当前架构上运行应用
✅ 不需要发布多架构镜像
✅ 追求简单和轻量
✅ 不需要 Docker-in-Docker

选择 Buildx 版

✅ 需要构建多架构镜像(如 amd64 + arm64)
✅ 发布到 Docker Hub 等公共仓库
✅ 跨平台应用开发
✅ CI/CD 需要多架构支持

❓ 常见问题

Q1: 如何更新 Runner 版本?

docker-compose exec gitea-runner /data/setup.sh
# 脚本会检测到已安装并询问是否升级

Q2: 如何添加多个 Runners?

# 多次运行注册脚本,每次使用不同名称
docker-compose exec gitea-runner /data/register.sh

# 查看所有 runners
docker-compose exec gitea-runner /data/manage.sh list

Q3: 容器启动失败 "exec format error"

原因: Windows 换行符问题(CRLF vs LF)

解决:

# 方法 1: 使用提供的检查工具
cd docker-runner/presets/<your-preset>/
../../common/check_crlf.sh

# 方法 2: 手动转换
sed -i 's/\r$//' ../../common/*.sh

# 重新构建
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Q4: 如何完全重置?

# 停止并删除容器和卷
docker-compose down -v

# 删除数据目录
rm -rf runner-data

# 重新构建
docker-compose build --no-cache
docker-compose up -d

Q5: 如何查看日志?

# 容器日志
docker-compose logs -f

# Runner 日志
docker-compose exec gitea-runner /data/manage.sh logs <runner-name>

# 实时跟踪日志
docker-compose exec gitea-runner /data/manage.sh follow <runner-name>

Q6: Buildx 版 - 构建速度慢?

优化方法:

1. 启用缓存

- name: Build with cache
  uses: docker/build-push-action@v4
  with:
    cache-from: type=registry,ref=myimage:buildcache
    cache-to: type=registry,ref=myimage:buildcache,mode=max
    platforms: linux/amd64,linux/arm64

2. 使用交叉编译

对于 Go、Rust 等支持交叉编译的语言,优先使用交叉编译而非 QEMU 模拟:

FROM --platform=$BUILDPLATFORM golang:1.21 AS builder
ARG TARGETOS TARGETARCH
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o app

3. 按需构建

# 开发分支只构建当前架构,生产分支构建双架构
platforms: ${{ github.ref == 'refs/heads/main' && 'linux/amd64,linux/arm64' || 'linux/arm64' }}

Q7: Buildx 版 - 如何验证 Buildx?

# 进入容器
docker-compose exec gitea-runner bash

# 检查 builder
docker buildx ls

# 测试构建
echo 'FROM alpine' | docker buildx build --platform linux/amd64,linux/arm64 -

Q8: 如何清理 Docker 资源?

清理未使用的镜像

# 清理悬空镜像(dangling images)
docker image prune

# 清理所有未使用的镜像
docker image prune -a

# 查看镜像占用空间
docker system df

清理 Buildx 缓存(仅 Buildx 版)

# 进入容器
docker-compose exec gitea-runner bash

# 清理构建缓存(保留 builder)
docker buildx prune

# 清理所有构建缓存
docker buildx prune -a -f

# 删除 builder(会自动清理相关容器和镜像)
docker buildx rm gitea-multiarch

完整清理流程

# 1. 停止所有容器
docker-compose down

# 2. 清理 Buildx(如果使用 Buildx 版)
docker-compose exec gitea-runner docker buildx rm gitea-multiarch

# 3. 清理未使用的镜像
docker image prune -a

# 4. 清理系统(慎用!会清理所有未使用资源)
docker system prune -a --volumes

# 5. 查看清理效果
docker system df

⚠️ 注意: docker system prune -a 会删除所有未使用的镜像,包括其他项目的。

Q9: 数据持久化在哪里?

所有数据持久化在 runner-data/ 目录:

runner-data/
├── bin/
│   └── act_runner        # Runner 可执行文件(持久化)
├── runners/              # Runner 配置目录
│   └── <runner-name>/
│       ├── .runner       # 注册信息
│       ├── config.yaml   # 配置文件
│       └── cache/        # 构建缓存
└── buildx/               # Buildx 配置(仅 Buildx 版)
    └── .configured

容器重启或重建后,数据不会丢失。

Q10: 如何切换不同预设?

# 1. 停止当前容器
cd docker-runner/presets/<current-preset>/
docker-compose down

# 2. 切换到新预设
cd ../buildx-ubuntu-22/

# 3. 复制数据目录(可选,保留旧数据)
cp -r ../standard-ubuntu-22/runner-data .

# 4. 启动新预设
docker-compose build
docker-compose up -d

📚 参考资源

💬 反馈与支持

如果你在使用过程中遇到问题，欢迎：

📝 提交 Issue
💡 分享你的使用经验
🌟 给项目点个 Star

13 KiB Raw Permalink Blame History