607 lines
13 KiB
Markdown
607 lines
13 KiB
Markdown
# 🚀 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
|
||
|
||
---
|