Apidog Self-hosted Runner 可以理解为一个可托管在独立服务器上的自动化程序。它可以执行 Apidog 中的任务，例如定时自动化测试、定时 API 文档导入，以及返回模拟响应结果。准备工作#
Docker 最低要求版本为 20.10.0，推荐使用 20.10.13 版本。
快速开始#
本节将指导你如何在服务器上部署 General Runner。1. 部署 General Runner#
导航到 Apidog Home 页面，选择所需团队，然后点击右侧的 Resources。接着点击 Deploy General Runner 开始部署。2. 获取 Runner 部署命令#
点击 Deploy General Runner 后，从弹出窗口复制 General Runner 的部署命令。你可以根据需要自定义命令，支持自定义服务器操作系统、暴露端口、挂载数据目录等。以下是这些设置的详细说明：Server OS：指定 Docker 容器的操作系统。这包括 Linux、macOS 和 Windows。选择正确的操作系统对于确保 Docker 容器正常运行至关重要。
Docker Image：提供三个版本：General、Slim 和 Custom。如果你的“自定义脚本”需要调用外部程序，请根据所需环境选择合适的镜像进行安装：General：包含 Runner 的所有功能，并预装以下语言环境：Node.js 18、Java 21、Python 3 和 PHP 8。
Slim：包含 Runner 的所有功能，但仅预装 Node.js 18。
Custom：包含 Runner 的所有功能，并支持为外部程序自定义语言环境。你可以创建自己的 Dockerfile，根据需要添加或移除环 境。
Exposed Port：默认情况下，Docker 容器不会暴露内部端口以供外部访问。使用 -p 参数，可以将容器的内部端口映射到主机端口，从而允许外部访问容器提供的服务。例如，-p 80:4524 会将容器的内部端口 4524 映射到主机的 80 端口。
Mount Data Directory：-v 参数允许你将主机目录挂载到容器中，使容器能够访问和操作主机上的文件（例如数据库配置或外部程序）。例如，-v "/opt/runner":/opt/runner 会将主机的 /opt/runner 目录挂载到容器的 /opt/runner 目录。
部署命令包含 token 信息，出于数据安全原因只会显示一次。每次点击 Deploy General Runner 都会生成新的命令。请将该命令保存在本地，因为你可以在未来升级 Runner 时使用它。
3. 在服务器上部署 Runner#
将复制的部署命令粘贴到服务器终端中，Runner 安装将自动开始。安装完成后，终端会打印相关信息。如果出现错误，你可以根据错误详情进行排查。如果仍无法解决，请联系我们并提供反馈。4. 在服务器上查看 Runner 状态#
你可以通过 Docker 客户端查看容器的运行状态。你也可以在终端中使用 docker ps 命令查看容器的运行状态。5. 在 Apidog 中查看已部署的 General Runner#
确认服务器上的 Runner 容器已部署并启用后，返回 Apidog。你可以在 Team Resources → General Runner 中看到 Runner 已部署并连接到 Apidog。如果 General Runner 已在服务器上成功部署，但未显示在 Apidog 客户端中，请点击 “General Runner” 右侧的刷新按钮刷新页面并再次检查。
| 状态 | 说明 |
|---|
| 已启动 | Runner 在服务器上的容器中正常启用，与 Apidog 保持通信，并可以处理 Apidog 下发的相关任务。 |
| 已停止 | Runner 在 Apidog 中被手动停止，但仍在服务器上的容器中正常运行并保持通信。它不会处理 Apidog 下发的任务，且新任务无法指定已停止的 Runner 执行。你可以在 Apidog 中手动启用它，使 Runner 恢复为已启动状态。 |
| 离线 | Runner 已与 Apidog 断开连接，无法处理任务。这可能是由于服务器上的 Runner 容器停止，或服务器与 Apidog 之间 存在通信问题。要恢复 Runner，请确保 Runner 容器正在运行，并且与 Apidog 的通信没有问题，使 Runner 恢复为已启动状态。 |
你可以在一个团队中部署多个 General Runner。创建需要自托管 Runner 的任务时，团队成员可以从可用的 Runner 中进行选择。在 Runner 中保存文件#
使用 Runner 执行端点请求、测试场景和定时任务等任务时，可能需要某些本地文件来支持任务执行。示例包括：为此，请将必要文件保存到 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 |
你可以参考此页面，了解如何从 Apidog 客户端导出配置文件。 升级与重新部署 Runner#
升级 Runner#
当 Runner 发布新版本时，桌面端 Runner UI 中会出现升级图标。点击该图标以安装 Apidog 提供的最新版本。点击 Upgrade 会提示你停止当前正在运行的 Runner 容器。请注意，容器停止后，定时任务以及客户端发送到此 Runner 的任何任务都将不再执行。确认升级后，Apidog 会自动停止当前 Runner 容器，并提供用于部署新版本的命令。按照初始部署步骤重新部署 Runner。部署成功后，你将使用最新版本。注意：客户端中现有的定时任务不会受到影响，也无需重新分配。重新部署 Runner#
如果 Runner 遇到问题，而你无法在 Q&A 部分找到解决方案，或相关说明无法帮助解决问题，请考虑重新部署 Runner。为此，请导航到特定 Runner 的 More Actions 部分，然后点击 Redeploy。重新部署流程与上方的升级流程相同。注意：重新部署也会停止 Runner 容器。Q&A#
使用 docker ps 命令定位有问题的 Runner。
步骤 1：收集信息以诊断问题：
打开开发者工具 (Alt+7+8)，向有问题的 Runner 发送一个测试场景，并记录端点详情
如果你可以识别问题，且问题不是由 Apidog bug 引起的，请自行修复
如果你无法定位问题，请联系 Apidog 社区获取进一步帮助
步骤 1：验证任务完成情况：
检查 Apidog 客户端中是否有该定时任务的测试报告
此错误有两个可能原因：
部署命令已重新生成：如果你生成了命令，关闭弹窗，然后再次点击，则新的 token 可能会使之前的 token 失效。要修复此问题：切换到左上角的另一个团队，然后返回需要部署 Runner 的团队
重新生成部署命令，复制并运行它。确保在流程完成之前不要再次点击重新生成。
teamId 变量的 ID 数据错误：这是一个已在最新版本中修复的已知 bug。如果问题仍然存在：切换到左上角的另一个团队，然后返回需要部署 Runner 的团队
重新生成部署命令，复制并运行它。确保在流程完成之前不要再次点击重新生成。
