我的知识库

Appearance

ngrok 是一个功能强大的反向代理工具，广泛用于内网穿透（即将本地网络中的服务暴露到公网上），方便开发人员在本地开发和测试时进行远程访问、演示或调试。本文将详细介绍 ngrok 的概念、功能、安装与配置步骤，以及实际应用案例，帮助您全面了解并有效使用 ngrok 进行内网穿透。

目录 ​

  1. 什么是 ngrok
  2. ngrok 的主要功能
  3. 安装 ngrok
  4. 基本使用方法
  5. 高级配置与使用
  6. 安全性与鉴权
  7. 常见问题及解决方法
  8. 实际应用案例
  9. ngrok 的替代方案
  10. 总结

什么是 ngrok ​

ngrok 是一个开源的反向代理工具，允许开发者将本地运行的服务（如 Web 服务器、API 接口等）通过 ngrok 的服务器生成一个公网可访问的 URL，从而实现内网穿透。这样，无需进行复杂的路由器配置或公网 IP 管理，便可让外部网络访问本地服务，极大地方便了开发、测试和演示工作。

ngrok 的工作原理 ​

  1. 客户端和服务器通信：ngrok 客户端运行在本地，向 ngrok 的云服务器（tunnel servers）发起一个持久的加密连接（通常是 TLS）。
  2. 生成公网地址：云服务器为每一个隧道生成一个唯一的子域名（或域名），如 https://abcd1234.ngrok.io。
  3. 请求转发：当外部用户访问这个公网地址时，ngrok 云服务器会将请求通过已建立的加密连接转发到本地的指定服务端口。
  4. 响应返回：本地服务处理请求后，响应通过同一路径返回给外部用户。

ngrok 的主要功能 ​

  • 快速内网穿透：无需复杂的网络配置，便可快速将本地服务暴露到公网。
  • 多协议支持：支持 HTTP、HTTPS、TCP 等多种协议的隧道。
  • 自定义子域名：付费用户可使用自定义子域名，便于记忆和访问。
  • 访问控制：支持基本的身份验证和 IP 白名单，增强安全性。
  • 请求检视和调试：提供 Web 控制台，可实时查看和调试通过隧道的请求和响应。
  • 持久隧道：付费版支持持久的隧道地址，避免每次启动时生成不同的 URL。

安装 ngrok ​

ngrok 支持多个平台，包括 Windows、macOS 和 Linux。以下以 Windows 和 macOS 为例介绍安装步骤。

1. 下载 ngrok ​

访问 ngrok 官方网站 下载适合您操作系统的版本。

2. 解压并配置 ​

下载完成后，将压缩包解压到您想要存放的目录。

3. （可选）全局使用配置 ​

为了方便在任何目录下使用 ngrok，可以将其所在目录添加到系统的环境变量中。

  • Windows：
    • 打开“系统属性” > “高级系统设置” > “环境变量”。
    • 在“系统变量”中找到 Path，编辑并添加 ngrok 的目录路径。
  • macOS/Linux：
    • 编辑 ~/.bashrc 或 ~/.zshrc 文件，添加如下行：
      sh
      export PATH=$PATH:/path/to/ngrok
    • 保存并运行 source ~/.bashrc 或 source ~/.zshrc 使之生效。

4. 注册并获取身份验证令牌 ​

为了使用高级功能（如自定义子域名、持久隧道等），需要在 ngrok 官网注册账户，并获取身份验证令牌。

  • 注册账户：ngrok 注册页面
  • 登录后，获取身份验证令牌（Auth Token），在客户端配置中使用。

5. 配置 Auth Token ​

在终端中运行以下命令，替换 <your-auth-token> 为您在官网获取的 Auth Token：

sh
ngrok config add-authtoken <your-auth-token>

这会将 Auth Token 保存到配置文件中，确保 ngrok 客户端可以访问您的账户特权。

基本使用方法 ​

启动 HTTP 隧道 ​

假设您在本地运行了一个 Web 服务器，监听端口 8080，可以通过以下命令启动 HTTP 隧道：

sh
ngrok http 8080

执行后，终端会显示类似如下信息：

Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.x.x
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://abcd1234.ngrok.io -> http://localhost:8080
Forwarding                    https://abcd1234.ngrok.io -> http://localhost:8080

其中，http://abcd1234.ngrok.io 和 https://abcd1234.ngrok.io 是公网可访问的地址，访问这些地址会被转发到您本地的 http://localhost:8080。

启动 TCP 隧道 ​

如果您需要公开某个 TCP 服务（如 SSH、数据库），可以使用 TCP 隧道。例如，公开本地的 SSH 服务（通常监听 22 端口）：

sh
ngrok tcp 22

执行后，您将获得一个类似 tcp://0.tcp.ngrok.io:XXXXX 的地址，外部可以通过该地址访问您的本地 SSH 服务。

高级配置与使用 ​

自定义子域名 ​

默认情况下，ngrok 隧道使用自动生成的子域名。付费用户可以指定自定义子域名，便于记忆和访问。

示例命令：

sh
ngrok http -subdomain=mycustomsubdomain 8080

注意事项：

  • 自定义子域名必须唯一，且遵循一定的命名规则（仅允许字母、数字和短横线）。
  • 如果子域名已被占用，命令会失败，需更换子域名。

HTTPS 隧道 ​

ngrok 默认提供 HTTPS 隧道，确保数据传输的加密和安全。无论您本地服务是否支持 HTTPS，ngrok 都会为隧道提供 HTTPS 地址。

示例：

sh
ngrok http 8080

生成的 https:// 地址即为具备加密传输的隧道地址。

多个隧道 ​

同一个 ngrok 客户端实例可以同时启动多个隧道，适用于多服务或多端口场景。

示例命令：

sh
ngrok http 8080
ngrok tcp 22

或者通过配置文件同时定义多个隧道。

配置文件使用 ​

ngrok 支持使用配置文件（ngrok.yml）来管理多个隧道和高级设置。配置文件通常位于 ~/.ngrok2/ngrok.yml。

示例配置文件：

yaml
authtoken: <your-auth-token>

tunnels:
  web:
    proto: http
    addr: 8080
    subdomain: mywebapp
  ssh:
    proto: tcp
    addr: 22

启动所有定义的隧道：

sh
ngrok start --all

或者指定特定隧道：

sh
ngrok start web

安全性与鉴权 ​

暴露本地服务到公网时，确保服务安全至关重要。ngrok 提供了多种安全机制：

基本认证 ​

通过设置用户名和密码，限制外部访问。

示例命令：

sh
ngrok http -auth="user:password" 8080

访问时，用户需要输入 user 和 password 进行认证。

IP 白名单 ​

限制只有特定 IP 地址可以访问隧道。

配置文件示例：

yaml
tunnels:
  web:
    proto: http
    addr: 8080
    auth: "user:password"
    ip_restrictions:
      - <allowed-ip-address>

独享域名和高级访问控制 ​

付费用户可以使用独享域名、自定义认证方式以及更细粒度的访问控制策略。

常见问题及解决方法 ​

1. 隧道无法启动或连接失败 ​

可能原因：

  • 端口被占用或服务未启动。
  • 防火墙或网络设置阻止 ngrok 访问。
  • Auth Token 配置错误。

解决方法：

  • 确保本地服务正常运行，并监听指定端口。
  • 检查防火墙设置，确保 ngrok 可以出站连接。
  • 重新配置 Auth Token，确保其正确有效。

2. 自定义子域名被占用 ​

解决方法：

  • 尝试使用不同的子域名。
  • 升级到付费计划，获取更多或专属子域名权限。

3. 隧道速度慢或不稳定 ​

可能原因：

  • 网络带宽限制。
  • ngrok 服务器负载高。

解决方法：

  • 检查本地网络连接，确保带宽充足。
  • 考虑升级到更高性能的付费计划，获得更快的服务器节点。

4. 请求在 ngrok 控制面板中不可见 ​

可能原因：

  • 访问隧道的请求未正确转发或被过滤。
  • 使用了不支持的协议。

解决方法：

  • 确保隧道配置正确，协议匹配。
  • 检查 ngrok 的访问控制设置，确保请求未被阻止。

实际应用案例 ​

1. 本地 Web 应用演示 ​

开发者可以在本地运行 Web 应用，通过 ngrok 生成的公网 URL 分享给同事或客户，无需部署到线上。

2. 接收 Webhooks ​

整合第三方服务（如 GitHub、Stripe 等）时，可能需要接收 Webhooks。使用 ngrok 可将本地服务器暴露给第三方服务，实现快速测试和调试。

示例：

sh
ngrok http 3000

将生成的 URL 配置到第三方服务的 Webhook 设置中。

3. 远程访问 SSH ​

通过 ngrok 的 TCP 隧道，可以从外部网络安全地访问内网中的 SSH 服务，无需公网 IP 或 VPN。

示例命令：

sh
ngrok tcp 22

生成的地址可用于通过 SSH 连接到内网主机。

4. IoT 设备调试 ​

对于运行在内网中的 IoT 设备，可以使用 ngrok 将设备的控制接口暴露到公网，方便进行远程调试和管理。

ngrok 的替代方案 ​

虽然 ngrok 功能强大，但市场上还有其他内网穿透工具，您可以根据需求选择合适的工具：

  • Localtunnel：开源工具，提供简单的内网穿透服务。
  • Serveo：无需安装客户端，通过 SSH 端口转发实现内网穿透。
  • FRP (Fast Reverse Proxy)：高性能的反向代理工具，适用于复杂网络环境。
  • Tunnelblick：主要用于 VPN 隧道，但也可用于内网穿透。

总结 ​

ngrok 是一个简便、高效的内网穿透工具，适用于多种场景，如本地开发演示、Webhooks 接收、远程调试等。通过简洁的命令行操作和丰富的功能配置，ngrok 让开发者无需复杂的网络配置即可将本地服务安全地暴露到公网。同时，其提供的安全机制和高级功能，如自定义子域名、访问控制等，也为专业用户提供了更多的灵活性和控制力。无论您是初学者还是资深开发者，掌握 ngrok 都将极大提升您的开发和测试效率。