ngrok 内网穿透技术超详细部署与配置指南

---

---

一、环境准备

1.1 系统要求

• 支持平台：Windows、macOS、Linux、Docker
• 网络要求：本地服务需能访问互联网（用于连接ngrok云端服务器）
• 账户注册：免费版需注册 ngrok 账户，获取授权Token。

---

二、安装与配置

2.1 安装步骤

2.1.1 Windows

1. 下载安装包：
   ngrok Windows 版
2. 解压文件：
   将 ngrok.exe 解压至任意目录（如 C:\ngrok）。
3. 配置环境变量：
   将目录路径加入系统环境变量 PATH。

2.1.2 macOS/Linux

# 使用curl安装
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com jammy main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update
sudo apt install ngrok

# 或手动下载二进制文件
wget https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip
unzip ngrok-stable-linux-amd64.zip
sudo mv ngrok /usr/local/bin/

2.1.3 Docker

docker run -it --rm -p 4040:4040 -e NGROK_AUTHTOKEN=<YOUR_TOKEN> ngrok/ngrok http 80

2.2 认证配置

# 使用Token授权（从Dashboard获取）
ngrok config add-authtoken <YOUR_AUTH_TOKEN>

---

三、基础使用

3.1 暴露本地HTTP服务

# 暴露本地端口8080的Web服务
ngrok http 8080

# 输出示例：
# Forwarding  http://a1b2.ngrok.io -> http://localhost:8080
# Forwarding  https://a1b2.ngrok.io -> http://localhost:8080

3.2 暴露TCP服务（如SSH/数据库）

# 暴露SSH服务（端口22）
ngrok tcp 22

# 输出示例：
# Forwarding  tcp://0.tcp.ngrok.io:12345 -> localhost:22

# 远程连接命令
ssh user@0.tcp.ngrok.io -p 12345

---

四、高级配置

4.1 自定义域名（付费功能）

# 绑定自有域名
ngrok http --domain=api.example.com 8080

# 强制HTTPS（自动签发Let's Encrypt证书）
ngrok http --domain=api.example.com --scheme=https 8080

4.2 访问控制

4.2.1 IP白名单

# 仅允许特定IP访问
ngrok http 8080 --allow-ip=192.168.1.0/24,203.0.113.5

4.2.2 OAuth 2.0 验证

# 集成Google登录验证
ngrok http 8080 --oauth=google

4.3 流量监控与重放

• Web控制台：访问 http://localhost:4040 查看实时请求日志。
• 请求重放：

  # 根据请求ID重放
  ngrok replay <request_id>
  

---

五、安全加固

5.1 端到端加密（企业版）

# 启用TLS全程加密
ngrok http --tls-termination=upstream 8080

5.2 敏感头信息过滤

# ngrok.yml 配置文件
tunnels:
  myapp:
    proto: http
    addr: 8080
    request-header-remove: "Authorization, Cookie"

---

六、性能优化

6.1 连接池复用

# ngrok.yml 配置文件
version: "2"
authtoken: <YOUR_TOKEN>
tunnels:
  myapp:
    proto: http
    addr: 8080
    http-max-conns: 1000  # 最大并发连接数

6.2 多区域部署

# 选择欧洲区域服务器
ngrok http --region=eu 8080

---

七、企业级场景

7.1 私有化部署（On-Premise）

1. 下载企业版：从官网获取企业版二进制文件。
2. 启动服务端：

   ngrokd -tls-key=key.pem -tls-cert=cert.pem -domain=ngrok.internal.com
   

3. 客户端连接：

   ngrok http --region=internal 8080
   

7.2 CI/CD集成

# GitHub Actions 示例
jobs:
  deploy:
    steps:
      - name: Expose service via ngrok
        run: |
          ngrok http 8080 &
          sleep 5  # 等待隧道建立
          NGROK_URL=$(curl -s localhost:4040/api/tunnels | jq -r '.tunnels[0].public_url')
          echo "PUBLIC_URL=$NGROK_URL" >> $GITHUB_ENV

---

八、故障排查

8.1 常见错误

错误信息	解决方案
Failed to bind to local port	检查端口是否被占用或权限不足（Linux需sudo）
Tunnel session expired	重新运行命令或升级付费版解除时间限制
Invalid authtoken	检查Token是否正确或重新运行 ngrok config add-authtoken

8.2 调试模式

# 启用详细日志
ngrok http 8080 --log=stdout --log-level=debug

---

九、学习资源

9.1 官方文档

• 快速入门：https://ngrok.com/docs/guides
• API参考：https://ngrok.com/docs/api

9.2 社区资源

• Stack Overflow：标签 ngrok
• Reddit：r/ngrok

---

通过本指南，您可快速掌握ngrok的核心功能，从基础调试到企业级部署，实现安全高效的内网穿透。

---