企业官网建设流程全解析

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 镜像构建等任务，建议配置稍高。

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

准备工作

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

在 Gitea 中启用 Actions 功能

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

[actions] ENABLED = true

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

获取 Runner 注册 Token

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

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

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

确保服务器已安装 Docker：

curl-fsSLhttps://get.docker.com|shdocker--versiondockercompose version

docker-compose.yml

创建部署目录：

mkdir-p/opt/gitea-runnercd/opt/gitea-runner

创建docker-compose.yml：

version:"3.8"services:gitea-runner:image:gitea/act_runner:latestcontainer_name:gitea-runnerenvironment:-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.yamlvolumes:-./config:/config-./data:/data-/var/run/docker.sock:/var/run/docker.sock# 允许 Runner 启动 Docker 容器restart:unless-stopped

创建 Runner 配置文件：

mkdir-p/opt/gitea-runner/config

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

log:level:inforunner:file:/data/.runnercapacity:2# 同时执行的最大任务数timeout:3h# 单个任务最长执行时间insecure:falsefetch_timeout:5sfetch_interval:2scache:enabled:truedir:/data/cachehost:""port:0external_server:""container:network:bridgeprivileged:falseoptions:workdir_parent:/data/workdirvalid_volumes:[]docker_host:""host:workdir_parent:""

启动 Runner：

dockercompose up-d

配置说明

验证 Runner 注册成功

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

dockercompose logs-fgitea-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指定的运行环境如何映射到实际执行器：

# 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 同样识别）：

name:CIon:push:branches:[main,develop]pull_request:branches:[main]jobs:test:runs-on:ubuntu-lateststeps:-name:检出代码uses:actions/checkout@v4-name:设置 Node.js 环境uses:actions/setup-node@v4with:node-version:'20'cache:'npm'-name:安装依赖run:npm ci-name:运行测试run:npm test-name:构建run:npm run builddeploy:runs-on:ubuntu-latestneeds:testif:github.ref == 'refs/heads/main'steps:-name:检出代码uses:actions/checkout@v4-name:部署到服务器run:|echo "部署步骤..."

使用 Secrets

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

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 镜像构建示例

name:Build and Push Docker Imageon:push:tags:-'v*'jobs:build:runs-on:ubuntu-lateststeps:-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:推送到私有 Registryrun:|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 容器可以访问：

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

Q：构建缓存如何利用？

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

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

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

添加定时清理任务：

# 编辑 crontabcrontab-e# 每周日凌晨清理未使用的 Docker 资源03* *0dockersystem prune-f

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