通用 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目录。
部署命令因为包含 token 信息，基于数据安全考量，一个部署命令只会在产品端展示一次。每次点击部署时都会生成新的命令。
请将此命令保存在本地，后续 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 在执行相关任务时就会根据设定的任务需求在指定目录下读取文件内容，确保任务完成。
可以按照下表将对应格式与内容的文件放到指定目录下进行使用：
| 使用内容 | 示例目录路径或文件名 |
|---|---|
| 其它编程语言 | /opt/apifox/runner/external-programs/ |
| 数据库连接配置文件 | /opt/apifox/runner/database/database-connections.json |
| SSL 证书列表文件 | /opt/apifox/runner/ssl/ssl-client-cert-list.json |
示例路径中， /opt/apifox/runner 为默认挂载目录，可在部署界面或容器内使用 -v 命令更改。
以下是数据库连接配置文件的内容示例：
{
"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"
}
]