如何用 Apifox 自托管 Runner 定时跑 API 测试

API 测试套件只有在你能信任的时间表上跑起来，才真正有用。靠人手点一次集合，只能在你想起来的时候抓到 bug。一台你自己控制的机器在凌晨 2 点跑 nightly，才能赶在用户之前发现问题。这就是 Apifox Runner 的工作：一项部署在你自己服务器上、用 Docker 安装的自托管服务，执行你在 Apifox 里编排的定时测试场景，再把报告推回项目。

三种定时跑测试的方式，我们在「如何在 Apifox 中安排自动化 API 测试」里做过对比：云端执行、Runner 和 CLI。本文是 Runner 这条路径的深挖：什么时候需要它、怎么部署、如何把定时任务指到它上面，以及它和另外两条路怎么选。

何时需要自托管测试 Runner

云端执行很方便，但有三种情况会把团队推向自托管测试 Runner。

你的 API 在私有网络里。 像 https://orders.staging.internal:8443 这样的 staging 环境，公网解析不到。任何云服务都打不进去。部署在 VPC 或办公网内部的 Runner 可以，因为它从自己所在的位置发请求。这和在内网跑自托管 mock 服务是同一套逻辑：工作负载必须待在有网络权限的地方。

合规要求流量不出域。 如果安全团队禁止带真实客户数据的测试 payload 离开基础设施，云端执行就出局了。用 Runner 时，请求从你的服务器发出、直接打到你的 API。只有测试报告会回到 Apifox。

你要一份不依赖任何笔记本的稳定时间表。 桌面版里排的测试，应用一关就停。接到 CI 的测试，只有有人推代码才会跑。两者都给不了「每 6 小时跑一次，一直跑，不管有没有人在」。一台常开服务器上的 Runner 正好做这件事。

如果以上都不成立，你多半不需要 Runner。应用里的手动运行，或 CI 里的 CLI，就够用。

Apifox Runner 是什么

自托管 Runner 是一项你部署在独立服务器上的自动化服务。连上团队之后，它可以：

• 按排期执行由 Apifox 测试场景组成的自动化测试任务
• 按周期导入接口文档
• 提供自托管 mock 响应

它有两种范围。团队级通用 runner 属于某一个团队。组织级 runner 可以在组织下所有团队的项目之间共享。两边的部署方式相同。

关键心智模型：Runner 是 worker，不是项目的一份拷贝。测试场景、环境、断言都还在 Apifox 里。Runner 接收任务，对着它能到达的网络执行，再上传结果。团队成员从不需要 SSH 进去看发生了什么；他们在应用里打开运行历史即可。

前置条件

部署前先核对这些项。它们直接来自 Runner 部署环境文档。

硬件。 最低 2 核 CPU、4 GB 内存；如果要跑并发任务或团队更大，建议 4 核以上、8 GB。磁盘至少预留 30 GB 给日志和测试产物，50 GB 更从容。

Docker。 宿主机需要 Docker 20.10.0 或更高，推荐 20.10.13。新机器先按发行版走一遍 官方 Docker Engine 安装指南。

网络。 Runner 通过 443 端口的 HTTPS 与 Apifox 服务器通信，并维持一条 WebSocket（WSS）连接做实时任务下发。它还需要出站访问用于上传报告的 AWS 域名，以及——显而易见——测试所针对的每一套 API。注意方向：是 Runner 主动拨出。你不需要为了让 Apifox 连上它而开放入站端口，跟运维谈防火墙会短很多。

权限和套餐。 部署 Runner 是团队资源操作，需要相应的团队角色。定时任务能跑多少次取决于订阅档位，当前各套餐限额见 Apifox 定价页。

步骤 1：从 Apifox 获取部署命令

Apifox 会为你生成 Docker 部署命令，里面已经带好 auth token。不要从博客文章（包括这篇）里抄一条；这个 token 才是把容器绑到你团队上的东西。

1. 打开 Apifox，进入 Apifox 首页。还没有账号的话，可以先免费 下载 Apifox 跟着做。
2. 选择 Runner 要归属的团队。
3. 点击右侧的 Resources。
4. 点击 Deploy General Runner。

弹窗会给出完整部署命令。马上复制：里面有敏感 token，而且只展示一次。把它当 CI secret 对待，不要贴进团队 wiki。

复制前，对话框允许你定制命令：

• Server OS：Linux、macOS 或 Windows。
• Image variant：General 自带 Node.js 18、Java 21、Python 3 和 PHP 8，这些语言的前置/后置脚本不用额外装环境。Slim 只含 Node.js 18，拉取更快。Custom 允许你提供自己的 Dockerfile，适合测试依赖内网 CA 证书或不常见库的情况。
• Exposed port：如果还要用 Runner 做自托管 mock，用 -p 映射端口（例如 -p 80:4524）。
• Mounted data directory：测试场景要读本地数据文件（比如数据驱动用的 CSV）时，加 -v 挂载卷。

通用 runner 文档 对每一项都有更细的说明。

步骤 2：运行容器并确认已连接

SSH 到目标服务器，粘贴命令，让 Docker 拉镜像并启动容器。第一天就值得设上的两条运维注意：

• 用环境变量传入 TZ（例如 TZ=Asia/Singapore），这样「每天 02:00」才是你的 02:00，而不是容器默认时区。
• 从 runner 2.2.5 起，镜像内置非 root 的 runner 用户（UID/GID 10001）。如果平台强制 runAsNonRoot，把 security context 配好，并预先处理好卷权限，因为非 root 模式下 entrypoint 无法 chown 目录。

回到 Apifox，WebSocket 握手完成后，Runner 会出现在团队的 Resources 下，成员创建任务时就能选它。一分钟内没出现，就用 docker logs 看容器日志，并确认宿主机能在 443 端口到达 Apifox 服务器；公司网络锁得比较死时，通常是 WSS 被挡住了。

一个团队可以部署多台 Runner。常见做法是 staging VPC 里放一台、生产只读权限再放一台，然后按任务挑选。

步骤 3：创建指向该 Runner 的定时任务

Runner 在线之后，排期就是填表，不是写脚本。

1. 在项目里打开 Tests 模块，点击 Scheduled Tasks。任务放在目录结构里，列表变长后按服务或环境分组。
2. 创建任务，起一个六个月后同事还能看懂的名字：「Orders 服务冒烟，staging，每 6 小时」远好过「test1」。
3. 选择一个或多个测试场景。每个场景可以单独设环境、测试数据、迭代次数、请求间隔，以及是否保存请求/响应 body。
4. 设置环境和变量作用域。推荐把变量应用到任务内全部场景，这是比较稳的中间档；目录级作用域很强，但也容易踩坑。
5. 设置 Run Cycle：每周日晚 11 点、每 6 小时，按你需要多快知道出事来选。
6. 在 Runs on 下按名称选择你的自托管 Runner。
7. 配置通知。可以每次运行都提醒，也可以只在失败时提醒。只失败通知是更清醒的默认；频道里全是绿勾，大家很快就学会无视。

保存。从此这份排期会在你的服务器上执行，不管有没有人开着 Apifox 应用。

步骤 4：在 Apifox 中查看运行报告

每次跑完，Runner 会自动把结果上传到 Apifox 服务器。在应用里打开 Scheduled Tasks → Run History，就能看到每一次执行：通过/失败状态、按场景的结果、断言失败，以及耗时。

这是 Runner 相对「自己写 cron + 脚本」最安静的优势。执行发生在你的基础设施上，报告却落在定义测试的同一个共享工作区。周二凌晨 02:00 那次失败时，去排查的 QA 能直接看到哪一步的哪条断言挂了，而且就在上下文里，不用去服务器里 grep 日志。

把失败通知和运行历史配对，就形成监控闭环：告警响起，打开报告，在应用里对着同一环境手动复现失败步骤，修好，等下一次变绿。

Runner、CLI 与云端：怎么选执行路径

除了在应用里手动点一次，Apifox 还提供三种执行测试的方式，解决的是不同问题。CI 这条路径我们在「Apifox CLI 的 GitHub Actions 指南」里写过完整走法，下面这张表用来对照各自适合什么。

这几条路是组合关系，不是互斥。常见做法：CLI 在流水线里卡住每一次发布，Runner 则对 staging 跑每小时冒烟、夜间全量回归，抓住的是基础设施漂移和过期凭证，而不是代码变更。

时间上有一条要注意：按 定时任务文档，定时任务是按自托管 Runner 来设计的，Apifox Cloud 会随可用性逐步可选。如果今天就需要定时执行、又等不了你套餐上的云端可用性，Runner 是靠得住的那条路。

FAQ

已经在 CI 里用 Apifox CLI 了，还需要 Runner 吗？

它们回答的是不同问题。CI 告诉你「这次改动有没有把 API 搞坏？」发生在推代码的时刻。Runner 告诉你「API 现在健不健康？」按固定周期跑，抓住的是过期 token、挂掉的依赖、没有对应提交的基础设施漂移。很多团队两条都跑；CI 排期那一半，见「夜间 API 测试怎么接到 CI」。

Runner 能访问内网 API 吗？

能，这也是它存在的主要理由。Runner 从部署它的那台机器发请求。把它放进 VPC 或办公网，就能测 *.internal 这类云服务解析不到的主机。它只需要出站 HTTPS 和 WebSocket 访问 Apifox 服务器，用来接收任务和上传报告。

服务器最低配置是什么？

2 核 CPU、4 GB 内存、30 GB 磁盘，以及 Docker 20.10.0 或更高。团队要跑并发定时任务时，升到 4 核以上、8 GB。一台小虚拟机或机架上闲置的盒子都行；约束是在线时间，不是算力。

在自托管 Runner 上跑定时任务需要什么套餐？

定时任务运行配额随订阅档位变化，规划高频排期前先看 Apifox 定价页 的当前限额。如果要横向对比各工具的执行能力，「Apifox CLI vs Postman CLI」那篇会讲到两边测试 runner 各自包含什么。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名