Forgejo Runner 配置：标签、执行环境、IPv6 与缓存-未完纪

Forgejo 在发现需要运行的作业时，会检查该作业的 runs-on 字段，判断哪些 Forgejo Runner 实例有能力执行。runs-on 通常是 ubuntu-latest 这样的单值，也可以在复杂配置中包含多个值。Runner 的标签既参与作业匹配，也指定具体执行环境。

选择标签

配置 Forgejo Runner 时，需要在配置文件中定义标签，说明该 Runner 应执行哪些作业。例如：

# ... the rest of the config file ...

runner:
  # ... other runner options ...
  labels:
    - debian:docker://docker.io/library/node:lts
    - ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04
# ... the rest of the config file ...

作业设置为 runs-on: debian 时，可以被这个 Runner 接收，并在标签指定的 docker.io/library/node:lts 容器镜像中运行。

标签的结构为：

<label-name>:<label-type>://<default-image>

label-name 是标识标签的字符串，也是工作流 runs-on 选择 Runner 时使用的部分。label-type 决定容器化方式，有三种选择：docker 对应 Docker 或 Podman，lxc 对应 LXC，host 对应直接在主机上执行。

Docker 或 Podman

标签类型为 docker 时，其余部分被解释为默认容器镜像。Runner 会创建相应容器，并以容器中的 root 用户执行各个步骤。

要特别注意镜像更新：官方文档说明，Runner 启动容器的行为相当于 docker run <image>；已经下载到本地的镜像不会因此自动更新。更改远端标签指向，不代表本地下一次执行就取得新内容。

标签示例：

node20:docker://node:20-bookworm：标签 node20 对应 Docker Hub 上的 node:20-bookworm 镜像。
node20:docker://docker.io/node:20-bookworm：显式写出镜像仓库主机，行为与上一项相同。
docker:docker://data.forgejo.org/oci/alpine:3.20：标签 docker 对应 data.forgejo.org 上的 alpine:3.20 镜像。

为了使作业可复现，官方文档建议用镜像摘要固定内容，而不是只依赖可移动的标签。例如，使用 debian:docker://node@sha256:91447bc57243b852a21e0ff3553f531f0d4b66257a564b106c79d9e00f3aa14e，而不是 debian:docker://node:lts。这里的摘要是原文示例，本文没有核验它现在能否被拉取。

可以用 ubuntu-latest:docker://node:lts 这样的标签响应面向 GitHub Runner 编写的 runs-on: ubuntu-latest。但它实际使用的是 node:lts 镜像，并不自动拥有 GitHub 托管 Runner 的全部工具。许多常用 Action，例如 uses: actions/checkout@v6，要求镜像中有 Node.js。工作流也可通过 jobs.<job_id>.container覆盖标签指定的容器镜像。

LXC

标签类型为 lxc 时，其余部分解释为 template[:release[:lxc-helper config]]：

template[:release] 指定要使用的模板与发行版本。
lxc-helper config 指定创建容器时传给 lxc-helper 的 --config 选项值。

Runner 在对应 LXC 容器中，以 root 用户运行所有步骤。原文给出的默认模板是 debian，默认发行版本是 bullseye，并说明会安装 Node.js 20；这些默认值应与实际 Runner 版本及模板配套核对。

标签示例：

bookworm:lxc://debian:bookworm:lxc docker：创建 Debian GNU/Linux bookworm 容器，具备运行嵌套 LXC 容器与 Docker 引擎所需的能力。
bookworm:lxc://debian:bookworm：创建 Debian GNU/Linux bookworm 容器，具备运行嵌套 LXC 容器、KVM 虚拟机与 Docker 引擎所需的能力。

Host

标签类型为 host 时，Runner 会派生一个 Shell，直接在主机执行各个步骤。

这种执行方式没有容器隔离。 一个作业可能永久破坏主机。self-hosted:host 就表示使用 runs-on: self-hosted 的作业直接在主机上运行。它不是给容器换一个名称，而是改变了执行边界。

特殊能力与多标签

Runner 标签也可表示硬件或其他能力。假设有三个 Runner 都能运行 docker 作业，但只有一个有 GPU，那么需要 GPU 的作业应同时要求两个标签：

on: pull_request
jobs:
  my-job:
    runs-on: [docker, gpu]
    # ...

相应 Runner 中定义两个标签：

runner:
  labels:
    - docker:docker://ghcr.io/catthehacker/ubuntu:act-22.04
    - gpu:docker://ghcr.io/catthehacker/ubuntu:act-22.04

只有同时具备 docker 与 gpu 标签的 Runner 才能执行该作业。执行时采用 runs-on 数组中第一个标签所列的容器化平台。标签只负责匹配，不会凭空为机器安装 GPU、驱动或其他硬件能力。

为 Docker 与 Podman 网络启用 IPv6

Runner 自行创建 Docker 或 Podman 网络时，IPv6 默认不启用，需要在 Runner 配置中显式开启。

Docker 守护进程配置

Docker 还需要额外的守护进程配置。原文要求 /etc/docker/daemon.json 至少包含以下配置键：

{
  "ipv6": true,
  "experimental": true,
  "ip6tables": true,
  "fixed-cidr-v6": "fd00:d0ca:1::/64",
  "default-address-pools": [
    { "base": "172.17.0.0/16", "size": 24 },
    { "base": "fd00:d0ca:2::/104", "size": 112 }
  ]
}

之后，原文使用 systemctl restart docker.service 重启 Docker 守护进程。这是会影响主机容器服务的管理步骤，本文仅保留文档操作，没有执行。

上述地址池都是示例值，需要按网络规划调整。原文提示读者进一步查阅 Docker 关于启用 IPv6和动态分配 IPv6 子网的说明，不能把示例直接视为适合所有机器的配置。

用工作流检查 IPv6 连通性

Docker 和 Podman 都可以用一个小型工作流检查 Runner 所建网络的 IPv6 连通性：

---
on: push
jobs:
  ipv6:
    runs-on: docker
    steps:
      - run: |
          apt update; apt install --yes curl
          curl -s -o /dev/null http://ipv6.google.com

这里的镜像环境需要支持 apt。只配置 Docker 侧而没有启用 Runner 网络的 IPv6 时，官方示例用 forgejo-runner exec 得到如下失败输出。以下两段日志均来自官方文档，不是本任务运行记录：

$ forgejo-runner exec
...
| curl: (7) Couldn't connect to server
[ipv6.yml/ipv6]   ❌  Failure - apt update; apt install --yes curl
curl -s -o /dev/null http://ipv6.google.com
[ipv6.yml/ipv6] exitcode '7': failure
[ipv6.yml/ipv6] Cleaning up services for job ipv6
[ipv6.yml/ipv6] Cleaning up container for job ipv6
[ipv6.yml/ipv6] Cleaning up network for job ipv6, and network name is: FORGEJO-ACTIONS-TASK-push_WORKFLOW-ipv6-yml_JOB-ipv6-network
[ipv6.yml/ipv6] 🏁  Job failed

本地执行时，需要提供 --enable-ipv6 选项。原文对照示例使用 forgejo-runner exec --enable-ipv6，显示以下成功输出：

$ forgejo-runner exec --enable-ipv6
...
[ipv6.yml/ipv6]   ✅  Success - Main apt update; apt install --yes curl
curl -s -o /dev/null http://ipv6.google.com
[ipv6.yml/ipv6] Cleaning up services for job ipv6
[ipv6.yml/ipv6] Cleaning up container for job ipv6
[ipv6.yml/ipv6] Cleaning up network for job ipv6, and network name is: FORGEJO-ACTIONS-TASK-push_WORKFLOW-ipv6-yml_JOB-ipv6-network
[ipv6.yml/ipv6] 🏁  Job succeeded

实际成功还取决于主机具有可用的 IPv6 路由、网络与远端服务。本文没有运行工作流，也不据此保证你的主机能够连通。

验证成功之后，原文要求在 Runner 守护进程使用的 runner-config.yml 中启用 IPv6，并重启 Runner：

container:
  enable_ipv6: true

启用后，Runner 创建的网络会请求启用 IPv6，工作流容器可从 Docker 守护进程所配置的池中分配地址。

Rootless Podman 的 IPv6 条件

普通用户不能像 root 一样创建真实网络；rootless Podman 为此使用带有自身限制的替代网络机制。原文记录，在编写该段文档时，只有 Podman 5.3 及以后版本被观察到能够正确支持 rootless bridge 网络中的 IPv6。Podman 5 将 rootless 网络切换到 passt，5.3 包含主机服务可达性等修复。

更早版本可能在 Runner 创建的 bridge 网络中出现 “host unreachable” 或 “network unreachable”。这是文档记载的版本观察，不是本文对所有版本和后端完成了重新测试；排查时应核对实际 Podman 版本、网络后端与主机路由。

缓存配置

某些 Action，例如 https://data.forgejo.org/actions/cache 和 https://data.forgejo.org/actions/setup-go，可以与 Runner 通信，保存和恢复编译依赖等常用文件。缓存以压缩的 tar 归档保存，作业开始时读取，完成时保存。

在磁盘足够快的机器上，复用这些缓存可能减少重新下载和重建依赖的带宽消耗。具体效果仍取决于缓存命中、归档大小和读取成本。更多选项见 Runner 配置文件的 cache 部分。

配置文件参考

Runner 的安装说明会介绍如何生成默认配置文件。推荐按二进制安装或Docker Compose 安装的对应步骤生成，这样可以让配置格式和可选项与正在安装的 Runner 版本一致。

所有配置项都在默认配置文件的 YAML 注释中说明。最新版文件可在 Forgejo Runner 仓库中查看；实际部署时应优先使用与你的 Runner 版本对应的文件，而不是假定 latest 里的每一项都能被旧版识别。

来源、修改与许可

本文完整汉化 Forgejo 文档贡献者的《Forgejo Runner Configuration》，核对日期为 2026-10-03。虽然 URL 位于管理员文档的 admin/actions 路径中，访问时的实际标题与正文均讨论 Runner 标签、执行环境、IPv6、缓存与配置文件，本文按该实际范围处理。

原页面直接声明内容适用 CC BY-SA 4.0，页脚署名为 Copyright © 2026 Forgejo authors。本文及所作汉化、整理以同一 CC BY-SA 4.0 许可共享。修改包括中文汉化、排版，明确日志是官方示例，补充运行条件与版本边界，并按实际 YAML 配置说明标签结构；原文叙述中出现的 docker::docker://... 双冒号写法没有被当作新的有效配置形式。缓存段按原文的读取与保存流程整理措辞。本文没有执行工作流、重启守护进程、修改网络或证明性能结果，也不表示获得 Forgejo 官方认可。

文章版权归作者所有，未经允许请勿转载。

THE END