通用 Runner

Apifox 通用 Runner 可以理解为是一个自动化程序，可以托管在独立服务器上。它能够执行 Apifox 内的自动化测试定时任务、定时导入接口文档、返回 Mock 响应结果等工作。

准备工作

Linux 服务器
服务器已安装 Docker 环境，最低版本号需使用 20.10.0，推荐 20.10.13

快速上手

本章节将为你介绍如何在服务器上部署通用 Runner。

1. 部署通用 Runner

前往 Apifox 的“团队资源”页，点击“部署通用 Runner”按钮。

2. 获取部署 Runner 命令

点击部署通用 Runner 按钮后，在弹出框中复制部署通用 Runner 的命令，你可以根据需要定义命令，支持自定义服务器 OS、暴露端口、挂载数据目录等。以下是对这些设置的详细说明：

说明

服务器 OS：指定了 Docker 容器运行的操作系统。包括 Linux、macOS 和 Windows，选择正确的操作系统是确保 Docker 容器能够正确运行的关键。
Docker 镜像：提供了三种版本，分别是通用版、精简版和自定义版本。若你的「自定义脚本」需要调用外部程序，请根据不同版本所包含的语言环境选择合适的镜像进行安装。
- 通用版：包含 Runner 的所有功能，并内置以下外部程序的语言环境：Node.js 18、Java 21、Python 3、PHP 8。
- 精简版：包含 Runner 的所有功能，仅内置 Node.js 18 语言环境。
- 自定义：包含 Runner 的所有功能，并支持自定义外部程序的语言环境。你可以通过创建自己的 Dockerfile，根据需求添加或移除相关环境。
暴露端口：Docker 容器默认不会将内部端口暴露给外部访问。通过 -p 参数，你可以将容器内部的端口映射到宿主机的端口上，使得外部可以访问容器提供的服务。例如，-p 80:4524表示将容器内部的 4524 端口映射到宿主机的 80 端口。
挂载数据目录：使用-v参数可以将宿主机的目录挂载到容器内部，这样容器就可以访问和操作宿主机上的文件（数据库配置、外部程序等）。例如，-v "/opt/runner":/opt/runner表示将宿主机的/opt/runner目录挂载到容器的/opt/runner目录。

获取部署 Runner 命令

3. 在服务器上部署 Runner

将已复制的部署命令粘贴至服务器的终端上，然后将会自动开始安装 Runner。

提示

你可以通过环境变量来修改部署 Runner 的属性，使得能够更加匹配你的实际使用场景。阅读 Runner 运行环境了解更多信息。

安装完成后，终端将会打印出相关信息。如果报错，可以根据报错详情进行故障排除。如果依然无法解决，请联系我们并进行反馈。

4. 在服务器上查看 Runner 状态

你可以通过 Docker 客户端查看容器的运行状态。

也可以在终端内使用 docker ps 命令，查看容器的运行情况。

5. 在 Apifox 中查看已部署的通用 Runner

确认服务器上的 Runner 容器部署完成并启用后，返回 Apifox。你可以在“团队资源” → “通用 Runner” 页查看到这个 Runner 已部署完成并连接上 Apifox。

如果已在服务器上成功部署通用 Runner，但是在 Apifox 客户端中并没有显示，请点击“通用 Runner”右侧的刷新按钮刷新页面后再次查看。

你可以在 Apifox 中对 Runner 进行改名、添加描述以及删除操作，让你的团队成员能够更好的使用这个 Runner；也可以停用/重启 Runner。已暂停的 Runner 将不会再执行指定的相关定时任务，也无法再新创建相关的任务并指定此 Runner 执行。

关于 Runner 的状态信息见下表说明：

状态	说明
已启动 / Started	Runner 在服务器的容器中正常启用并与 Apifox 保持通信中，可以处理 Apifox 下发的相关任务。
已停用 / Stopped	Runner 在 Apifox 中手动停用，但是在服务器的容器中正常运行并保持通信。此时不会处理 Apifox 下发的各类任务，新的任务也不可指定停用的 Runner 执行。可以在 Apifox 中手动启用来让此 Runner 重新恢复已启动状态。
已离线 / Offline	Runner 与 Apifox 通信中断，无法处理 Apifox 下发的任务。可能原因为 Runner 容器已在服务器中停止运行，服务器与 Apifox 服务端通信异常等。此时可以通过恢复 Runner 容器运行并确保与 Apifox 通信没有问题，来让此 Runner 重新恢复已启动状态。

你可以在一个团队中部署多个通用 Runner，团队成员在创建需要使用自托管 Runner 的任务时，就可以从多个 Runner 中选择一个来执行。

服务器 Host 配置

填写服务器地址以让 Apifox 实现自托管 Mock、Runner 请求等功能，详细配置请参考自托管 Runner Mock 模块。

在 Runner 中保存文件

使用 Runner 执行接口请求、运行测试场景、定时任务等任务时，可能会需要一些本地文件提供数据来支持任务执行。例如：

在自定义脚本中调用其它编程语言
在前后置操作中有用到数据库连接
发起请求时需要使用 SSL 证书等

此时可将需要使用的文件保存在 Docker 容器中的指定目录下。当 Runner 在执行相关任务时就会根据设定的任务需求在指定目录下读取文件内容，确保任务完成。

可以参考下表，将对应格式与内容的文件放到指定目录下进行使用：

使用内容	指定目录路径 (或文件名)	示例 Docker 命令
其它编程语言	/app/external-programs/	-v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms
数据库连接配置文件	/app/database/database-connections.json	-v /Users/xxx/runner/packages/api-test/database/database-connections.json:/app/database/database-connections.json
SSL 证书列表文件	/app/ssl/ssl-client-cert-list.json	-v /Users/xxx/runner/packages/api-test/ssl/ssl-client-cert-list.json:/app/ssl/ssl-client-cert-list.json

以下是数据库连接配置文件的内容示例：

{
  "19731": {
    "configs": {
      "default": {
        "username": "accountname",
        "password": "123456",
        "host": "192.168.0.0"
      }
    },
    "id": 19731,
    "name": "Database Name",
    "type": "mysql",
    "projectId": 1320441,
    "description": "Dummy data.",
    "createdAt": "2022-09-27T07:51:09.000Z",
    "updatedAt": "2024-05-09T11:38:07.000Z",
    "deletedAt": null
  }
}

你可以参考此处查看从 Apifox 客户端中导出配置文件的方法。

SSL 证书列表文件的内容示例：

[
  {
    "name": "domain1",
    "matches": ["https://test.domain1.com/*", "https://www.domain1/*"],
    "key": {"src": "./client.domain1.key"},
    "cert": {"src": "./client.domain1.crt"},
    "passphrase": "changeme"
  },
  {
    "name": "domain2",
    "matches": ["https://domain2.com/*"],
    "key": {"src": "./client.domain2.key"},
    "cert": {"src": "./client.domain2.crt"},
    "passphrase": "changeme"
  }
]

通用 Runner

准备工作​

快速上手​

1. 部署通用 Runner​

2. 获取部署 Runner 命令​

3. 在服务器上部署 Runner​

4. 在服务器上查看 Runner 状态​

5. 在 Apifox 中查看已部署的通用 Runner​

服务器 Host 配置​

在 Runner 中保存文件​