如何使用 Apifox 在内网运行自托管 Mock 服务端

一些团队无法将他们的流量发送到云端。也许您处于企业防火墙之后，该防火墙阻止了对第三方服务的出站调用。也许合规性规则规定请求和响应数据必须保留在您控制的机器上。也许整个环境是物理隔离的，任何数据都根本无法离开内网。在上述任何一种情况下，即使 mock 数据本身是虚假的，使用托管在他人基础设施上的 mock URL 也是不可行的。

Apifox 通过自托管 runner 解决了这个问题。您的请求无需发送到 Apifox 的云端 mock，而是通过在您拥有的服务端上部署一个小程序，由该程序在您自己的网络内部返回 mock 响应。设计依然像往常一样保存在您的 Apifox 项目中；只有服务运行转移到了您的硬件上。本指南将介绍什么是 runner、何时选择它而不是云端 mock、如何根据文档进行设置，以及一个容易让人混淆的区别：runner 并不是 CLI。如果您想更全面地了解为什么团队要在自己的设备上运行 mock，关于自托管 API mock 服务端的指南介绍了通用情况，而 OpenAPI Initiative 解释了生成这些 mock 所依据的规范。想要跟着一起操作吗？请先下载 Apifox。

什么是自托管 runner

Apifox 自托管 Runner 是一个由您托管在独立服务端上的自动化程序。它的官方名称是通用 runner，主要负责三项工作：运行定时自动化测试、导入 API 文档以及返回 mock 响应。本文主要讨论的是第三项工作。

核心思路如下：一旦您部署了通用 runner 并设置了其服务端主机（Server Host），您的项目中就会自动出现一个名为 Runner Mock 的新环境。您通过该环境发送的任何请求，都将从您的自托管 runner 获取其 mock 响应，而不是从 Apifox 的云端 mock 获取。相同的 mock 设计，生成相同的数据，只是提供服务的机器不同。您的流量绝不会离开您的网络。

这是云端 mock 的自托管替代方案。如果您的团队可以访问互联网并且没有相关禁令，使用 Apifox 云端 mock 会更简单，因为无需部署任何内容。当满足以下条件之一时，请选择使用 runner：

指向外部主机的出站流量被阻止或受到严格审查。
合规性政策要求请求数据必须保留在内部基础设施上。
环境是物理隔离的，完全无法访问云端接口。
您希望在自己的局域网（LAN）内测量 mock 延迟，而不是跨越公共互联网。

如果以上情况都不适用，那么额外的 Docker 主机就是您不需要的额外开销。在配置服务端之前，请务必明确您的实际需求。

关于套餐和权限的说明。Apifox 文档并未明确指出通用 runner 或自托管 mock 的免费与付费限制，也没有列出其价格，因此本指南在此不作臆测。但该配置确实需要团队或项目管理员权限，因为部署 runner 是在团队资源中进行的，只有管理员才能打开这些设置。如果您看不到“资源”面板，这就是原因所在。

开始之前的准备工作

Runner 以 Docker 容器形式交付，因此托管它的服务端需要安装 Docker。文档要求的最低版本为 20.10.0，推荐使用 20.10.13 或更新版本。检查您当前的版本：

docker --version

您还需要一个运行它的环境：一台您的团队 Apifox 客户端和 Apifox 服务都能访问的 Linux、macOS 或 Windows 机器。在内网中，这通常意味着一台具有固定 IP 或主机名的内部服务端。这就是全部的准备工作清单：Docker、主机以及团队的管理员权限。其他所有内容都可以在 Apifox 内部进行配置。

部署通用 runner

部署命令会在 Apifox 内部为您自动生成，并且包含一个 Token，因此您无需手动编写。以下是具体流程。

生成命令

打开 Apifox 主页，选择您的团队，然后点击右侧边栏中的“资源”，并选择“部署通用 runner”。此时会弹出一个窗口，您可以在其中进行以下配置：

操作系统 (Server OS)：Linux、macOS 或 Windows，以便生成的命令与您的主机匹配。
Docker 镜像 (Docker Image)：选择 General、Slim 或 Custom。General 预装了 Node.js 18、Java 21、Python 3 和 PHP 8。Slim 仅包含 Node.js 18，镜像体积更小。Custom 允许您在测试脚本需要额外的运行时环境时提供自己的 Dockerfile。
暴露端口 (Exposed Port)：通过 -p parameter 进行设置，例如 -p 80:4524，将主机端口 80 映射到 runner 的内部端口。
挂载数据目录 (Mounted Data Directory)：通过 -v parameter 进行设置，以便 runner 的数据在重启后仍能在主机上保留。

完成后，复制生成的命令。请注意：出于数据安全考虑，该命令只会显示一次，因为它嵌入了您的 Token。如果您丢失了该命令，需要重新生成一个新命令，而无法找回旧命令。请立即将其记录下来。

在服务端运行

将命令粘贴到服务端的终端中。安装将自动开始并拉取镜像。完成后的命令大致如下所示（您的命令会有所不同，且会包含真实的 Token）：

docker run -d \
  --name apifox-runner \
  -p 80:4524 \
  -v /opt/apifox-runner/data:/app/data \
  apifox/runner:latest \
  --token <YOUR_GENERATED_TOKEN>

确认容器已启动：

docker ps

您应该会看到列出的 runner 容器及其端口映射。如果您更倾向于查看图形界面，像 Docker Desktop 这样的 Docker 客户端也会显示相同的内容。

确认已注册

返回 Apifox，前往“团队资源”并打开“通用 runner”。点击刷新按钮。此时 runner 应显示为已部署，状态为“Started”。如果起初没有显示，点击刷新按钮即可解决；请稍等片刻并再次点击。

Runner 状态有以下三种，值得特别关注：

Started：已启用，正在与 Apifox 通信并处理任务。这是您期望的状态。
Stopped：有人在 Apifox 中手动停止了它。它保持已部署状态，但不会处理任务。
Offline：已失去与 Apifox 的连接，因此无法处理任何内容。请检查容器和网络路径。

开启 Runner Mock

部署 runner 后，您就拥有了 Agent。接下来还需要一步操作，将您的 mock 流量指向它。

在“团队资源”中，打开“通用 runner”并找到“Server Host”字段。输入您的 runner 可达的地址。在纯 HTTP 设置中，这是您暴露的主机和端口，例如用于本地测试的 http://127.0.0.1:80，或者用于共享内网主机的 http://runner.internal.example.com:80。如果在 TLS 终止代理之后，它看起来类似于 https://runner.example.com:443。稍后我们将详细介绍 HTTPS。

设置 Server Host 后，Apifox 会自动为您的项目配置 Runner Mock 环境。验证方法：打开项目，前往“环境管理”，确认 Runner Mock 现在已显示在环境列表中。您不需要手动创建它；设置 Server Host 就会使其自动出现。

通过自托管 mock 发送请求

现在开始使用它。假设您的项目中有一个用于内部订单管理 API 的接口 GET /orders/{orderId}。打开该接口，然后在顶部的环境下拉菜单中选择 Runner Mock，而不是云端环境。发送请求。

响应将从您的 runner 返回。由于 Apifox 会根据您的数据模型生成 mock 数据，因此定义良好的 Order 数据模型将返回真实的数值，而不是空的占位符：

curl http://runner.internal.example.com:80/orders/10583

{
  "orderId": 10583,
  "customerEmail": "amelia.turner@example.com",
  "status": "shipped",
  "total": 148.5,
  "currency": "USD",
  "createdAt": "2026-07-14T09:32:11Z"
}

该 JSON 从未经过公共互联网。Runner 根据您接口的数据模型构建了它，并从您的内网中提供服务。如上文中的 customerEmail 值这类能够感知字段的生成，源于 Apifox 读取了您数据模型的类型和字段名称，这与配套文章中介绍的使用智能 mock 自动生成真实 mock 数据所用的引擎相同。如果您想精确控制某个请求返回的内容，可以在接口上添加一个 mock 期望，接下来 runner 就会像云端 mock 那样提供该期望的响应。无论服务端是 Apifox 的还是您自己的，构建优秀 mock 响应的机制都是相同的；改变的只是主机地址。API mock 背后的通用概念同样适用，没有任何改变。

HTTPS、数据挂载及其他实际细节

在 http://127.0.0.1 上进行测试运行非常简单。但在将其推广到团队之前，共享的内网部署有一些值得了解的注意事项。

HTTPS 需要反向代理

runner 没有内置的 HTTPS 证书支持，也不支持自动配置证书。它不会为您获取或管理 TLS 证书。如果您需要 https://，请在 runner 前面的反向代理处终止 TLS，例如由 Nginx 持有您的证书，然后将 Server Host 指向代理的 HTTPS URL。如果没有代理，请坚持使用 http://host:port。不要将 Server Host 设置为 https:// 并期望 runner 直接响应 TLS；它无法做到这一点。

一个在端口 4524 上代理 runner 的最小 Nginx 配置块如下所示：

server {
    listen 443 ssl;
    server_name runner.example.com;

    ssl_certificate     /etc/ssl/certs/runner.example.com.pem;
    ssl_certificate_key /etc/ssl/private/runner.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4524;
        proxy_set_header Host $host;
    }
}

此时 Server Host 将变为 https://runner.example.com:443。如果您的团队对 TLS 终止还不熟悉，MDN 的 HTTPS 指南是一个很好的温习资料。

文件挂载需指定特定路径

如果您的 mock 或测试需要额外文件，runner 会期望它们存放在容器内的固定路径中，因此请将它们挂载到那里：

外部程序存放在 /app/external-programs/。
数据库连接配置存放在 /app/database/database-connections.json。
SSL 客户端证书存放在 /app/ssl/ssl-client-cert-list.json。

通过 -v 挂载来映射这些路径，以便在重启后保留数据。

重新部署和升级行为

当有新的 runner 版本发布时，您会看到一个“升级”选项，并且在“更多操作”下可以进行“重新部署”。这两者都会在启动新容器时停止当前运行的容器。令人放心的是：Apifox 客户端中现有的定时任务不会受到重新部署或升级的影响，因此您只需在容器重启的瞬间中断实时服务，而不会丢失配置。

使用 Apifox CLI 实现工作流自动化

这是一个可以避免混淆的区别：runner 是一个长期运行的 Agent，可以提供 mock 服务并运行定时任务，而 Apifox CLI 是一个用于 CI 的一次性测试运行器。它们是不同的工具。CLI 无法提供、启动或托管 mock 服务器。没有 apifox run mock，也没有 apifox mock serve。CLI 的 apifox run 执行测试场景、测试场景目录和测试套件，其 mock 命令组仅对作为数据的 mock 期望进行 CRUD 操作。提供 mock 服务是 runner 的工作，而不是 CLI 的。

因此，这两者可以完美结合。CLI 和 AI 编程助手（如 Cursor、Claude Code 和 Codex）可以创建和更新项目中的接口和数据模型，从而在 API 规范演进时保持 mock 输出的准确性。一旦自托管 mock 解决了前端开发的阻塞问题，该项目的测试场景就可以通过单条命令在 CI 中以无头模式运行，从而根据 mock 所描述的契约来验证真实的服务端：

apifox run -t <scenario_id> -e <env_id> -r html,cli

该命令会针对实际运行的服务端执行您的测试场景，并生成 HTML 和 CLI 报告。在 Node.js v16 或更高版本上，安装命令为 npm install -g apifox-cli；Apifox CLI 安装指南涵盖了 apifox login 和 Token 设置。要在每次推送时都运行该测试，请参考 Apifox CLI CI/CD 指南将其整合到您的流水线中。关于从 CLI 进行 API mock 的章节详细解释了为什么终端只负责管理 mock 定义而不提供托管服务。

FAQ

如果我的团队可以访问互联网，我还需要自托管 runner 吗？

大概率不需要。云端 mock 不需要部署任何内容，是更简单的方式。当出站流量被阻止或审计、合规策略要求将数据保存在内部基础设施中，或者环境处于物理隔离（air-gapped）状态时，请选择 runner。如果您首先要对比托管方案与管理方案，那么 Apifox 云端 mock 的使用指南将是本文的绝佳补充。

Apifox CLI 可以启动自托管 mock 服务端吗？

不能。CLI 使用 apifox run 运行测试，并通过其 mock 命令组将 mock 期望作为数据进行管理。提供 mock 流量服务是由通用 runner 或云端 mock 完成的，绝非通过 CLI。如果您希望在终端中输入一条命令就能在某个端口上启动并运行 mock，这是 runner 的工作，需要按照上文所述通过 GUI 进行设置。

runner 本身支持 HTTPS 吗？

它本身不附带证书，也不支持自动配置证书。可以在前端部署一个像 Nginx 这样的反向代理来终止 TLS，然后将 Server Host 指向代理的 https:// URL。如果没有代理，请使用 http://host:port。

为什么运行命令后我的 runner 没有显示出来？

打开“团队资源”，进入“通用 runner”，然后点击刷新按钮。注册可能会有短暂的延迟。如果仍然没有显示，请使用 docker ps 确认容器正在运行，并确保从 Apifox 可以访问该主机。状态显示为 Offline 表示连接已断开，您需要看到的状态是 Started。

多个团队可以共享一个 runner 以提供全局 mock 服务吗？

runner 会注册到您部署它的团队中，并且其 Runner Mock 环境会在每个项目中显示。如果您的分布式团队需要共享 mock 环境，那么全球团队共享 mock 环境指南中的模式将帮助您决定需要建立多少个 runner 以及部署在何处。

总结

使用通用 runner 进行自托管 mock，可以将您的请求数据保留在您自己控制的基础设施中，而您的 mock 设计仍像往常一样保留在您的 Apifox 项目中。您只需部署一个 Docker 容器，设置 Server Host，Runner Mock 环境就会自动处理其余工作。当云端受限时，您可以使用它；在不受限时，则可以继续使用云端 mock。准备好在您自己的网络中运行 mock 了吗？下载 Apifox，部署一个 runner，即可在没有任何数据包离开内网的情况下提供您的第一个 Runner Mock 响应。