# 🚀 Gitea Runner Docker 部署教程

## 📋 目录

- [简介](#-简介)
- [目录结构](#-目录结构)
- [版本选择](#-版本选择)
- [部署步骤](#-部署步骤)
- [管理命令](#-管理命令)
- [Buildx 多架构构建示例](#-buildx-多架构构建示例)
- [版本对比](#️-版本对比)
- [常见问题](#-常见问题)

---

## 💡 简介

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

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

---

## 📂 目录结构

```txt
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. 进入预设目录

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

#### 2. (可选)检查换行符

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

```bash
../../common/check_crlf.sh
```

#### 3. 构建并启动容器

```bash
docker-compose build
docker-compose up -d
```

#### 4. 安装 Runner

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

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

#### 5. 注册 Runner

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

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

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

#### 6. 验证运行状态

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

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

---

### Buildx 版部署

#### 1. 选择并进入预设目录

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

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

#### 2. (可选)配置代理

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

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

#### 3. 构建并启动

```bash
docker-compose build
docker-compose up -d
```

#### 4. 验证 Buildx 初始化

```bash
# 查看日志,应该看到:
# ✓ 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. 安装和注册

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

Runner 注册后会自动启动。

---

## 🔧 管理命令

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

### 查看状态

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

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

### 日志管理

```bash
# 查看日志(最后 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 控制

```bash
# 启动 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

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

### 交互式管理

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

---

## 🔧 Buildx 多架构构建示例

### 示例 1: 基础构建

在 Gitea Actions workflow 中使用:

```yaml
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 应用优化构建

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

```dockerfile
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: 启用构建缓存

```yaml
- 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 版本?

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

### Q2: 如何添加多个 Runners?

```bash
# 多次运行注册脚本,每次使用不同名称
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)

**解决:**

```bash
# 方法 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: 如何完全重置?

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

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

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

### Q5: 如何查看日志?

```bash
# 容器日志
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. 启用缓存

```yaml
- 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 模拟:

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

#### 3. 按需构建

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

### Q7: Buildx 版 - 如何验证 Buildx?

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

# 检查 builder
docker buildx ls

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

### Q8: 如何清理 Docker 资源?

#### 清理未使用的镜像

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

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

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

#### 清理 Buildx 缓存(仅 Buildx 版)

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

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

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

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

#### 完整清理流程

```bash
# 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/` 目录:

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

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

### Q10: 如何切换不同预设?

```bash
# 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
```

---

## 📚 参考资源

- 📖 [Gitea Actions 官方文档](https://docs.gitea.com/usage/actions/overview)
- 🚀 [Gitea Runner 下载](https://dl.gitea.com/act_runner/)
- 🐳 [Docker Buildx 文档](https://docs.docker.com/reference/cli/docker/buildx/)
- 🔧 [Act Runner GitHub](https://gitea.com/gitea/act_runner)

---

## 💬 反馈与支持

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

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

---