rename act runner to runner (#390)

Depends on gitea/runner#850 --------- Co-authored-by: Nicolas <bircni@icloud.com> Co-authored-by: silverwind <me@silverwind.io> Reviewed-on: https://gitea.com/gitea/docs/pulls/390 Reviewed-by: techknowlogick <9+techknowlogick@noreply.gitea.com> Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com> Reviewed-by: Nicolas <bircni@icloud.com>
2026-07-22 02:37:42 +00:00 · 2026-05-07 17:18:58 +00:00
parent b6b8dbcc64
commit 54af905d63
25 changed files with 226 additions and 294 deletions
--- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/design.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/design.md
@@ -8,35 +8,11 @@ sidebar_position: 40

 Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。

-## Act
+## Gitea Runner

-[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。
-我们受到了它的启发，并思考它是否可能为Gitea运行Actions。
+Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支。

-然而，尽管[nektos/act](https://github.com/nektos/act)被设计为一个命令行工具，但我们实际上需要的是一个专为Gitea修改的Go库。
-因此，我们在[gitea/act](https://gitea.com/gitea/act)基础上进行了分叉。
-
-这是一个软分叉，将定期跟进上游。
-虽然添加了一些自定义提交，但我们会尽力避免对原始代码进行太多更改。
-
-分叉的 act 只是Gitea特定用途的桥接或适配器。
-还添加了一些额外的提交，例如：
-
- 将执行日志输出到日志记录器钩子，以便报告给Gitea
- 禁用 GraphQL URL，因为Gitea不支持它
- 每个Job启动一个新的容器，而不是重复使用，以确保隔离性。
-
-这些修改没有理由合并到上游。
-如果用户只想在本地运行可信的Actions，它们是没有意义的。
-
-然而，将来可能会出现重叠，例如两个项目都需要的必要错误修复或新功能。
-在这些情况下，我们将向上游仓库贡献变更。
-
-## act runner
-
-Gitea的Runner被称为act runner，因为它基于act。
-
-与其他CIRunner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
+与其他CI Runner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。

 为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。
 此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。
@@ -47,7 +23,7 @@ Gitea的Runner被称为act runner，因为它基于act。
 这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。

 然而，Docker不是唯一的选择。
-act 也支持直接在主机上运行Job。
+Runner 也支持直接在主机上运行Job。
 这是通过像`linux_arm:host`这样的标签实现的。
 这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。

@@ -63,7 +39,7 @@ act 也支持直接在主机上运行Job。

 ## 通信协议

-由于act runner是Gitea的独立部分，我们需要一种协议让Runner与Gitea实例进行通信。
+由于 runner 是 Gitea 的独立部分，我们需要一种协议让 Runner 与 Gitea 实例进行通信。
 然而，我们不认为让Gitea监听一个新端口是个好主意。
 相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
 因此，我们选择使用基于HTTP的gRPC。
@@ -74,17 +50,17 @@ act 也支持直接在主机上运行Job。
 ## 网络架构

 让我们来看一下整体的网络架构。
-这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。
+这将帮助您解决一些问题，并解释为什么使用回环地址注册 Runner 是个不好的主意。

 ![network](/images/usage/actions/network.png)

 图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。

-### 连接 1，act runner到Gitea实例
+### 连接 1，runner 到 Gitea 实例

-act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
+Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。

-### 连接 2，Job容器到Gitea实例
+### 连接 2，Job 容器到 Gitea 实例

 即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
 举个例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要连接到Gitea来获取代码。
@@ -93,9 +69,9 @@ act runner 必须能够连接到Gitea以接收任务并发送执行结果回来
 如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
 然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。

-### 连接 3，act runner到互联网
+### 连接 3，runner 到互联网

-当您使用诸如 `actions/checkout@v4` 的一些Actions时，act runner下载的是脚本，而不是Job容器。
+当您使用诸如 `actions/checkout@v4` 的一些Actions时， runner下载的是脚本，而不是Job容器。
 默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
 那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
 它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
--- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/faq.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/faq.md
@@ -73,7 +73,7 @@ Runner仅具有连接到您的Gitea实例的权限。
 - 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
 - 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。

-## act runner支持哪些操作系统？
+## Runner 支持哪些操作系统？

 它在Linux、macOS和Windows上运行良好。
 虽然理论上支持其他操作系统，但需要进一步测试。
@@ -101,7 +101,7 @@ defaults:

 这是有效的语法。
 它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
-不幸的是，act runner 并不支持这种方式。
+不幸的是，runner 并不支持这种方式。
 如上所述，我们将标签映射到环境：

 - `ubuntu` → `ubuntu:22.04`
@@ -117,31 +117,31 @@ defaults:
 具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
 因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
 这不是一个技术问题，只是在早期设计中被忽视了。
-参见[runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
+参见[runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。

-目前，act runner尝试匹配标签中的每一个，并使用找到的第一个匹配项。
+目前，runner 尝试匹配标签中的每一个，并使用找到的第一个匹配项。

 ## 代理标签和自定义标签对于Runner有什么区别？

 ![labels](/images/usage/actions/labels.png)

-代理标签是由Runner在注册过程中向Gitea实例报告的。
+代理标签是由 Runner 在注册过程中向 Gitea 实例报告的。
 而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。

 然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
 您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
 然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
 这个默认值可能与用户的期望不符。
-参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
+参见[runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。

 与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。

 ## Gitea Actions runner会有更多的实现吗？

-虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。
-然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
+虽然我们希望提供更多的选择，但由于我们有限的人力资源，runner 将是唯一受支持的官方 Runner。
+然而，无论您如何决定，Gitea 和 runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
 我们支持您的选择，无论您如何决定。
-如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
+如果您选择分支 runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。

 ## Gitea 支持哪些工作流触发事件？

--- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/overview.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/overview.md
@@ -21,8 +21,8 @@ Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且
 ## Runner

 和其他CI/CD解决方案一样，Gitea不会自己运行Job，而是将Job委托给Runner。
-Gitea Actions的Runner被称为[act runner](https://gitea.com/gitea/act_runner)，它是一个独立的程序，也是用Go语言编写的。
-它是基于[nektos/act](http://github.com/nektos/act)的一个[分支](https://gitea.com/gitea/act) 。
+Gitea Actions的Runner被称为[Gitea Runner](https://gitea.com/gitea/runner)，它是一个独立的程序，也是用Go语言编写的。
+它的重要部分来自[nektos/act](http://github.com/nektos/act)的一个硬分支。

 由于Runner是独立部署的，可能存在潜在的安全问题。
 为了避免这些问题，请遵循两个简单的规则：
--- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/quickstart.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/quickstart.md
@@ -25,10 +25,10 @@ ENABLED=true

 ### 设置Runner

-Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
+Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
 为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。

-您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
+您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。

 在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
 如果出现问题，这样调试起来会更容易。
@@ -40,7 +40,7 @@ Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job
 在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：

 ```bash
-./act_runner register --no-interactive --instance <instance> --token <token>
+./runner register --no-interactive --instance <instance> --token <token>
 ```

 需要两个必需的参数：`instance` 和 `token`。
@@ -68,14 +68,14 @@ Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
 最后，是时候启动Runner了：

 ```bash
-./act_runner daemon
+./runner daemon
 ```

 您可以在管理页面上看到新的Runner：

 ![view runner](/images/usage/actions/view-runner.png)

-您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
+您可以通过访问[Gitea Runner](runner) 获取更多信息。

 ### 使用Actions

--- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/act-runner.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/act-runner.md
@@ -1,12 +1,14 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
-slug: "act-runner"
+slug: "runner"
 sidebar_position: 20
+aliases:
+  - /zh-cn/act-runner
 ---

-# Act Runner
+# Runner

-本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)，这是Gitea Actions的Runner。
+本页面将详细介绍[Gitea Runner](https://gitea.com/gitea/runner)，这是Gitea Actions的Runner。

 ## 要求

@@ -19,31 +21,31 @@ sidebar_position: 20

 ## 安装

-有多种安装Act Runner的方法。
+有多种安装 Runner 的方法。

 ### 下载二进制文件

-您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
-然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
+您可以从[发布页面](https://gitea.com/gitea/runner/releases)下载二进制文件。
+然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/gitea-runner/)下载。

 下载二进制文件时，请确保您已经下载了适用于您的平台的正确版本。
 您可以通过运行以下命令进行检查：

 ```bash
-chmod +x act_runner
-./act_runner --version
+chmod +x runner
+./runner --version
 ```

 如果看到版本信息，则表示您已经下载了正确的二进制文件。

 ### 使用 Docker 镜像

-您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
+您可以使用[docker hub](https://hub.docker.com/r/gitea/runner/tags)上的Docker镜像。
 与二进制文件类似，您可以使用`nightly`标签使用最新的夜间构建版本，而`latest`标签是最新的稳定版本。

 ```bash
-docker pull docker.io/gitea/act_runner:latest # for the latest stable release
-docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
+docker pull docker.io/gitea/runner:latest # for the latest stable release
+docker pull docker.io/gitea/runner:nightly # for the latest nightly build
 ```

 ## 配置
@@ -53,20 +55,20 @@ docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
 您可以通过运行以下命令生成配置文件：

 ```bash
-./act_runner generate-config
+./runner generate-config
 ```

 默认配置是安全的，可以直接使用。

 ```bash
-./act_runner generate-config > config.yaml
-./act_runner --config config.yaml [command]
+./runner generate-config > config.yaml
+./runner --config config.yaml [command]
 ```

 您亦可以如下使用 docker 创建配置文件：

 ```bash
-docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
+docker run --entrypoint="" --rm -it docker.io/gitea/runner:latest runner generate-config > config.yaml
 ```

 当使用Docker镜像时，可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中：
@@ -75,12 +77,12 @@ docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner
 docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
 ```

-您可能注意到上面的命令都是不完整的，因为现在还不是运行Act Runner的时候。
-在运行Act Runner之前，我们需要首先将其注册到您的Gitea实例中。
+您可能注意到上面的命令都是不完整的，因为现在还不是运行 Runner 的时候。
+在运行 Runner 之前，我们需要首先将其注册到您的Gitea实例中。

 ## 注册

-在运行Act Runner之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。
+在运行 Runner 之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。

 ### Runner级别

@@ -124,16 +126,16 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token

 ### 注册Runner

-可以通过运行以下命令来注册Act Runner：
+可以通过运行以下命令来注册 Runner：

 ```bash
-./act_runner register
+./runner register
 ```

 或者，您可以使用 `--config` 选项来指定前面部分提到的配置文件。

 ```bash
-./act_runner --config config.yaml register
+./runner --config config.yaml register
 ```

 您将逐步输入注册信息，包括：
@@ -148,7 +150,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
 如果您想以非交互方式注册Runner，可以使用参数执行以下操作。

 ```bash
-./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+./runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
 ```

 注册Runner后，您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
@@ -159,7 +161,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token

 ### 使用Docker注册Runner

-如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行Act Runner时指定注册信息。
+如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行 Runner 时指定注册信息。

 ```bash
 docker run \
@@ -172,13 +174,13 @@ docker run \
    -e GITEA_RUNNER_NAME=<runner_name> \
    -e GITEA_RUNNER_LABELS=<runner_labels> \
    --name my_runner \
-    -d gitea/act_runner:nightly
+    -d gitea/runner:nightly
 ```

 您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
-这是因为Act Runner将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
+这是因为 Runner 将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
 如前所述，如果要在主机上直接运行Job，可以将其移除。
-需要明确的是，这里的 "主机" 实际上指的是当前运行 Act Runner的容器，而不是主机机器本身。
+需要明确的是，这里的 "主机" 实际上指的是当前运行 Runner 的容器，而不是主机机器本身。

 ### 使用 Docker compose 运行 Runner

@@ -188,7 +190,7 @@ docker run \
 version: "3.8"
 services:
  runner:
-    image: gitea/act_runner:nightly
+    image: gitea/runner:nightly
    environment:
      CONFIG_FILE: /config.yaml
      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
@@ -231,14 +233,14 @@ cache:
 docker run \
  --name gitea-docker-runner \
  -p 8088:8088 \
-  -d gitea/act_runner:nightly
+  -d gitea/runner:nightly
 ```

 ### 标签

 ```mermaid
 flowchart TD
-    A[Workflow: runs-on: ubuntu-22.04] --> B[Act Runner 收到 Job 请求]
+    A[Workflow: runs-on: ubuntu-22.04] --> B[Runner 收到 Job 请求]
    B --> C[匹配标签: ubuntu-22.04:docker://node:16-bullseye]
    C --> D[启动 Docker 容器: node:16-bullseye]
    D --> E[在容器中运行 Job 步骤]
@@ -259,18 +261,16 @@ Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们
 如果您想直接在主机上运行Job，您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04`，`:host`是可选的。
 然而，我们建议您使用类似`linux_amd64:host`或`windows:host`的特殊名称，以避免误用。

-从 Gitea 1.21 开始，您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签（如果没有配置文件，请参考 [配置教程](#配置)），通过执行 `./act_runner daemon --config config.yaml` 命令重启 runner 之后，这些新定义的标签就会生效。
+从 Gitea 1.21 开始，您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签（如果没有配置文件，请参考 [配置教程](#配置)），通过执行 `./runner daemon --config config.yaml` 命令重启 runner 之后，这些新定义的标签就会生效。

 ## 运行

 注册完Runner后，您可以通过运行以下命令来运行它：

 ```bash
-./act_runner daemon
+./runner daemon
 # or
-./act_runner daemon --config config.yaml
+./runner daemon --config config.yaml
 ```

 Runner将从Gitea实例获取Job并自动运行它们。
-
-由于Act Runner仍处于开发中，建议定期检查最新版本并进行升级。
--- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.25/usage/actions/quickstart.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.25/usage/actions/quickstart.md
@@ -75,7 +75,7 @@ Runner和Job容器（由Runner启动以执行Job）将连接到此地址。

 ![view runner](/images/usage/actions/view-runner.png)

-您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
+您可以通过访问[act runner](act-runner) 获取更多信息。

 ### 使用Actions

--- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.26/usage/actions/quickstart.md
+++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.26/usage/actions/quickstart.md
@@ -75,7 +75,7 @@ Runner和Job容器（由Runner启动以执行Job）将连接到此地址。

 ![view runner](/images/usage/actions/view-runner.png)

-您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
+您可以通过访问[act runner](act-runner) 获取更多信息。

 ### 使用Actions