Gitea Actions Runner 搭建指南：为 Gitea 添加 CI/CD 自动化执行器

Gitea 是一个轻量的自托管 Git 服务，许多团队用它替代 GitHub 或 GitLab 来管理私有代码。从 Gitea 1.19 版本起，官方加入了 Gitea Actions 支持，语法兼容 GitHub Actions，可以直接复用大量已有的 workflow 配置文件。

但 Gitea Actions 本身只是调度系统，真正执行 CI/CD 任务的是 Actions Runner------一个独立运行的执行器程序，监听 Gitea 下发的任务，在本地环境执行构建、测试、部署等步骤，执行完毕把日志和结果反馈给 Gitea。

本文介绍如何用 Docker Compose + Caddy 搭建 Gitea Actions Runner，让你的私有 Gitea 拥有完整的 CI/CD 能力。

服务器配置

Runner 的资源消耗取决于 CI 任务的负载。如果需要运行编译构建、Docker 镜像构建等任务，建议配置稍高。

项目	规格
CPU	2 核
内存	4GB
硬盘	40GB（存储构建缓存和 Docker 镜像）
系统	Ubuntu 22.04 / Debian 12

推荐用 雨云服务器 rainyun-com 的 2 核 4GB 机型来运行 Gitea Actions Runner，兼顾 CI 构建性能和价格。注册填 2026off 领 5 折。

准备工作

本教程假设你已有一个运行中的 Gitea 实例（版本 >= 1.19）。如果还没有，先搭建 Gitea，可以参考其他 Gitea 部署教程。

在 Gitea 中启用 Actions 功能

编辑 Gitea 的配置文件 app.ini，在 [actions] 段落中启用：

ini 复制代码

[actions]
ENABLED = true

重启 Gitea 后，仓库设置中会出现"Actions"选项。

获取 Runner 注册 Token

有三种级别的 Runner，对应不同的注册入口：

实例级 Runner：站点管理员 → 管理面板 → Actions → Runner → 创建 Runner
组织级 Runner：组织设置 → Actions → Runner
仓库级 Runner：仓库设置 → Actions → Runner

记下注册时显示的 Token，格式类似 ATXXXXXXXXXXXXXXXXXXXXXXXX。

确保服务器已安装 Docker：

bash 复制代码

curl -fsSL https://get.docker.com | sh
docker --version
docker compose version

docker-compose.yml

创建部署目录：

bash 复制代码

mkdir -p /opt/gitea-runner
cd /opt/gitea-runner

创建 docker-compose.yml：

yaml 复制代码

version: "3.8"

services:
  gitea-runner:
    image: gitea/act_runner:latest
    container_name: gitea-runner
    environment:
      - GITEA_INSTANCE_URL=https://git.example.com   # 你的 Gitea 地址
      - GITEA_RUNNER_REGISTRATION_TOKEN=ATXXXXXXXXXXXXXXXXXXXXXXXX  # 注册 Token
      - GITEA_RUNNER_NAME=my-runner
      - GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye,ubuntu-22.04:docker://node:20-bullseye
      - CONFIG_FILE=/config/config.yaml
    volumes:
      - ./config:/config
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock  # 允许 Runner 启动 Docker 容器
    restart: unless-stopped

创建 Runner 配置文件：

bash 复制代码

mkdir -p /opt/gitea-runner/config

创建 /opt/gitea-runner/config/config.yaml：

yaml 复制代码

log:
  level: info

runner:
  file: /data/.runner
  capacity: 2          # 同时执行的最大任务数
  timeout: 3h          # 单个任务最长执行时间
  insecure: false
  fetch_timeout: 5s
  fetch_interval: 2s

cache:
  enabled: true
  dir: /data/cache
  host: ""
  port: 0
  external_server: ""

container:
  network: bridge
  privileged: false
  options:
  workdir_parent: /data/workdir
  valid_volumes: []
  docker_host: ""

host:
  workdir_parent: ""

启动 Runner：

bash 复制代码

docker compose up -d

配置说明

验证 Runner 注册成功

启动后查看日志，确认连接到 Gitea 实例：

bash 复制代码

docker compose logs -f gitea-runner

成功时会看到类似输出：

复制代码

INFO[0000] Starting runner...
INFO[0001] Runner registered successfully with Gitea instance
INFO[0001] Listening for tasks...

在 Gitea 管理后台 → Actions → Runner 列表中，也会看到 Runner 状态变为"Online"。

Runner Labels 说明

Labels 决定了 workflow 中 runs-on 指定的运行环境如何映射到实际执行器：

yaml 复制代码

# workflow 文件中
jobs:
  build:
    runs-on: ubuntu-latest   # 对应 Runner 的 label

默认 label 格式为 标签名:执行方式：

复制代码

ubuntu-latest:docker://node:20-bullseye   # 使用 Docker 容器，基于 node:20-bullseye 镜像
ubuntu-latest:host                         # 直接在宿主机执行（不推荐，安全隔离差）

并发任务数调整

capacity 参数控制同时运行的任务数量。2 核 4GB 内存建议设置为 2，避免内存不足。如果 CI 任务较轻（脚本为主，无大型编译），可以适当提高。

Docker-in-Docker（DinD）支持

如果 CI 任务需要构建 Docker 镜像，已通过挂载 /var/run/docker.sock 支持。但需要注意：

任务容器内的 Docker 命令操作的是宿主机的 Docker 守护进程
构建产生的镜像和容器会留在宿主机，需要定期清理
如需更强隔离，可以改用 DinD 模式（在容器内启动独立 Docker daemon）

使用方法

编写 Workflow 文件

在仓库根目录创建 .gitea/workflows/ci.yml（也可以用 .github/workflows/ci.yml，Gitea Actions 同样识别）：

yaml 复制代码

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 设置 Node.js 环境
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: 安装依赖
        run: npm ci

      - name: 运行测试
        run: npm test

      - name: 构建
        run: npm run build

  deploy:
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'

    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 部署到服务器
        run: |
          echo "部署步骤..."

使用 Secrets

在仓库设置 → Actions → Secrets 中添加敏感信息：

yaml 复制代码

steps:
  - name: 部署
    env:
      DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
      SERVER_HOST: ${{ secrets.SERVER_HOST }}
    run: |
      echo "$DEPLOY_KEY" > /tmp/deploy.pem
      chmod 600 /tmp/deploy.pem
      ssh -i /tmp/deploy.pem user@$SERVER_HOST "cd /app && git pull && docker compose up -d"

Docker 镜像构建示例

yaml 复制代码

name: Build and Push Docker Image

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: 构建 Docker 镜像
        run: |
          docker build -t myapp:${{ github.ref_name }} .
          docker tag myapp:${{ github.ref_name }} registry.example.com/myapp:${{ github.ref_name }}

      - name: 推送到私有 Registry
        run: |
          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.example.com -u ${{ secrets.REGISTRY_USERNAME }} --password-stdin
          docker push registry.example.com/myapp:${{ github.ref_name }}

常见问题

Q：Runner 已注册但任务一直排队，不执行？

检查 Runner 的 label 是否与 workflow 中 runs-on 的值匹配。如果 workflow 写的是 runs-on: ubuntu-latest，但 Runner 没有 ubuntu-latest 这个 label，任务会一直等待。

查看并更新 Runner 的 label：在 Gitea 管理后台找到对应 Runner，编辑 label 列表。

Q：任务执行时提示 Docker 权限错误？

检查 /var/run/docker.sock 的权限，确保 Runner 容器可以访问：

bash 复制代码

ls -la /var/run/docker.sock
# 如果权限不够，将当前用户加入 docker 组
sudo usermod -aG docker $USER

Q：构建缓存如何利用？

Gitea Actions 支持 actions/cache Action，可以缓存 npm、Maven、pip 等依赖目录，加速后续构建：

yaml 复制代码

- name: 缓存 npm 依赖
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

Q：如何清理积累的 Docker 镜像和容器？

添加定时清理任务：

bash 复制代码

# 编辑 crontab
crontab -e

# 每周日凌晨清理未使用的 Docker 资源
0 3 * * 0 docker system prune -f

Gitea Actions Runner 搭建完成后，你的私有 Git 服务就拥有了完整的 CI/CD 流水线能力，workflow 文件语法与 GitHub Actions 高度兼容，迁移成本极低。