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

有些团队无法将其流量发送到云端。也许你正处于公司防火墙之后，防火墙阻止了对第三方服务的出站调用。或者合规性规则要求请求和响应数据必须保留在受控的机器上。甚至整个环境是物理隔离（air-gapped）的，任何数据都无法离开内网。在这些情况下，即使 mock 数据本身是伪造的，使用托管在他人基础设施上的 mock URL 也是行不通的。

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

什么是自托管 runner

[Apifox 自托管 runner](https://docs.apifox.com/self-hosted-

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

开始之前

该 runner 以 Docker 容器形式交付，因此托管它的服务端需要安装 Docker。文档要求最低版本为 20.10.0，并推荐使用 20.10.13 或更高版本。请检查你的版本：

docker --version

你还需要一个运行环境：一台 Linux、macOS 或 Windows 机器，且你的团队 Apifox 客户端和 Apifox 服务都能访问到它。在内网环境下，这通常意味着一台具有稳定 IP 或主机名的内部服务器。以上就是全部的前置条件：Docker、主机以及团队管理员权限。其他所有配置都可以在 Apifox 内部完成。

部署通用 runner

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

生成命令

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

服务端操作系统：Linux、macOS 或 Windows，以便生成的命令与你的主机匹配。
Docker 镜像：选择通用型（General）、精简型（Slim）或自定义（Custom）。通用型预装了 Node.js 18、Java 21、Python 3 和 PHP 8。精简型仅包含 Node.js 18，镜像体积更小。自定义模式允许你在测试脚本需要额外运行时环境时提供自己的 Dockerfile。
暴露端口：通过 -p parameter 设置，例如 -p 80:4524，这将主机端口 80 映射到 runner 的内部端口。
挂载数据目录：通过 -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 容器及其端口映射。如果你更倾向于使用 UI 界面，像 Docker Desktop 这样的 Docker 客户端也会显示同样的信息。

确认已注册

回到 Apifox，进入“团队资源”并打开“通用 runner”。点击刷新按钮。此时 runner 应显示为已部署，状态为“已启动”。如果最初没有出现，点击刷新按钮即可；稍等片刻再次点击。

Runner 状态有三种值得注意的情况：

已启动：已启用，正在与 Apifox 通信并处理任务。这是你需要的状态。
已停止：有人在 Apifox 中手动停止了它。它仍处于部署状态，但不会处理任务。
离线：它与 Apifox 失去了连接，因此无法处理任何任务。请检查容器和网络路径。

开启 Runner Mock

部署 runner 后你就拥有了代理。最后一步是将 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 是一个可以提供 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）可以创建和更新项目中的接口和数据模型，从而随着接口规范的演进保持 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 无需部署任何内容，是更简单的路径。当出站流量被拦截或审计、合规性规则要求数据保留在内部基础设施中，或者环境处于物理隔离状态时，请选择 runner。如果您正在对比托管方案与管理方案，Apifox 云端 mock 教程是本指南的最佳补充

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