Act Runner Gitea CI 配置

Act Runner 是 Gitea Actions 的官方执行引擎，负责接收 Gitea 分配的 CI/CD 任务并在 Docker 容器中执行。它基于 nektos/act 项目，能够解析和运行兼容 GitHub Actions 语法的 Workflow 文件。本教程将详细介绍如何在搬瓦工 VPS 上安装、配置和优化 Act Runner，让你的 Gitea 实例拥有完整的 CI/CD 能力。

一、安装 Act Runner

1.1 二进制安装

apt update && apt upgrade -y

# 下载最新版本
wget https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-linux-amd64 -O /usr/local/bin/act_runner
chmod +x /usr/local/bin/act_runner
act_runner --version

1.2 Docker 安装

docker pull gitea/act_runner:latest

二、获取注册令牌

注册令牌可以在三个级别获取：

实例级别：在 Gitea 站点管理 -> Runners 中获取，Runner 可为所有仓库服务。
组织级别：在组织设置 -> Runners 中获取，Runner 仅为该组织的仓库服务。
仓库级别：在仓库设置 -> Runners 中获取，Runner 仅为该仓库服务。

也可以通过命令行获取：

# 使用 Gitea 管理员 Token
curl -X GET "https://git.your-domain.com/api/v1/admin/runners/registration-token" \
  -H "Authorization: token YOUR_ADMIN_TOKEN"

三、生成配置文件

mkdir -p /opt/act-runner && cd /opt/act-runner
act_runner generate-config > config.yaml

编辑 config.yaml 关键配置：

log:
  level: info

runner:
  file: .runner
  capacity: 2
  timeout: 3h
  insecure: false
  fetch_timeout: 5s
  fetch_interval: 2s
  labels:
    - "ubuntu-latest:docker://node:20-bookworm"
    - "ubuntu-22.04:docker://ubuntu:22.04"
    - "python:docker://python:3.12"
    - "golang:docker://golang:1.22"

container:
  network: ""
  privileged: false
  options:
  workdir_parent: /workspace
  valid_volumes:
    - /opt/runner-cache/**
  docker_host: ""
  force_pull: false

host:
  workdir_parent: /opt/act-runner/workspace

四、注册 Runner

cd /opt/act-runner
act_runner register \
  --config config.yaml \
  --instance https://git.your-domain.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name vps-runner-01 \
  --no-interactive

五、启动 Runner

5.1 使用 systemd 管理

cat > /etc/systemd/system/act-runner.service <<'EOF'
[Unit]
Description=Gitea Act Runner
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/act-runner
ExecStart=/usr/local/bin/act_runner daemon --config config.yaml
Restart=always
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable act-runner
systemctl start act-runner
systemctl status act-runner

5.2 Docker 方式运行

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  act-runner:
    image: gitea/act_runner:latest
    container_name: act-runner
    restart: always
    volumes:
      - ./config.yaml:/config.yaml
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CONFIG_FILE=/config.yaml
      - GITEA_INSTANCE_URL=https://git.your-domain.com
      - GITEA_RUNNER_REGISTRATION_TOKEN=YOUR_TOKEN
      - GITEA_RUNNER_NAME=docker-runner
    command: daemon --config /config.yaml
EOF

docker compose up -d

六、标签管理

标签（Labels）决定了 Workflow 中 runs-on 使用哪个 Docker 镜像运行任务：

# 配置文件中的标签格式
labels:
  - "label-name:docker://image:tag"

常用标签配置：

labels:
  - "ubuntu-latest:docker://catthehacker/ubuntu:act-latest"
  - "ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04"
  - "node-20:docker://node:20"
  - "python-3.12:docker://python:3.12-slim"
  - "golang-1.22:docker://golang:1.22"
  - "rust:docker://rust:latest"

七、缓存优化

为了加速构建，可以配置缓存目录：

# 在 config.yaml 中配置有效的挂载卷
container:
  valid_volumes:
    - /opt/runner-cache/**

# 创建缓存目录
mkdir -p /opt/runner-cache/npm
mkdir -p /opt/runner-cache/pip
mkdir -p /opt/runner-cache/go

在 Workflow 中使用缓存：

steps:
  - uses: actions/checkout@v4
  - uses: actions/cache@v4
    with:
      path: ~/.npm
      key: npm-${{ hashFiles('package-lock.json') }}
  - run: npm ci

八、多 Runner 部署

在同一台 VPS 上可以运行多个 Runner 实例，分别服务不同的任务类型：

# Runner 1：通用任务
act_runner register --name runner-general \
  --labels "ubuntu-latest:docker://ubuntu:22.04"

# Runner 2：Node.js 任务
act_runner register --name runner-node \
  --labels "node:docker://node:20"

# Runner 3：Go 任务
act_runner register --name runner-go \
  --labels "golang:docker://golang:1.22"

九、日志和监控

# 查看 Runner 日志
journalctl -u act-runner -f

# 查看 Runner 状态
act_runner list

# 在 Gitea 管理界面查看
# 站点管理 -> Runners 可以看到所有已注册的 Runner 及其状态

十、常见问题

Docker 镜像拉取失败

检查 VPS 的网络连接，必要时配置 Docker 镜像加速。

Runner 离线

# 检查 Runner 进程
systemctl status act-runner

# 检查 .runner 文件是否存在
ls -la /opt/act-runner/.runner

# 重新注册
act_runner register --config config.yaml --instance https://git.your-domain.com --token NEW_TOKEN

磁盘空间不足

定期清理 Docker 构建缓存：

docker system prune -a --volumes

总结

Act Runner 是 Gitea Actions 的核心组件，正确配置后可以在搬瓦工 VPS 上实现高效的 CI/CD 流水线。建议根据项目需求配置合适的标签和缓存策略以加速构建。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 折扣。相关教程：Gitea Actions 教程、Woodpecker CI 集成。