3分钟搞定ngrok自定义域名：从DNS解析到本地服务穿透全指南

3分钟搞定ngrok自定义域名：从DNS解析到本地服务穿透全指南

【免费下载链接】ngrok Introspected tunnels to localhost 项目地址: https://gitcode.com/gh_mirrors/ng/ngrok

你是否还在为测试环境的外网访问发愁？想让客户即时查看你本地开发的网站却苦于没有公网IP？本文将带你通过CNAME解析和自定义域名配置，3分钟内搭建稳定的ngrok隧道服务，让localhost瞬间拥有公网访问能力。读完本文你将掌握：DNS记录配置技巧、服务器与客户端设置方法、常见错误排查方案，以及企业级部署的安全最佳实践。

为什么需要自定义域名？

默认情况下，ngrok提供随机生成的域名（如23dfg.ngrok.io），但这存在三大痛点：每次启动随机变化难以记忆、无法用于品牌展示、长期测试需要固定访问地址。通过自定义域名功能，你可以将本地服务映射到自己的域名下（如dev.yourcompany.com），实现专业级的开发测试环境。

官方文档中详细说明了自托管方案的优势：docs/SELFHOSTING.md。该文档包含从SSL证书配置到服务器部署的完整流程，是深入学习的重要资源。

准备工作：环境与文件说明

在开始配置前，请确保你已完成以下准备：

• 拥有一个已备案的域名（如example.com）
• 具备DNS管理权限（能添加CNAME记录）
• 已安装ngrok客户端（src/ngrok/client/main.go）
• 自托管ngrok服务器（src/ngrok/server/main.go）

项目中与域名配置相关的核心文件包括：

文件路径	功能说明
src/ngrok/client/config.go	客户端配置解析逻辑，定义了Hostname和Subdomain参数
docs/SELFHOSTING.md	自托管服务器配置指南，包含域名设置步骤
assets/client/tls/	客户端TLS证书存储目录，影响HTTPS域名验证

第一步：DNS解析配置（关键步骤）

CNAME记录设置

1. 登录你的DNS管理平台（如阿里云DNS、DNSPod等）
2. 添加两条CNAME记录：
   • 主机记录：*.dev（表示所有子域名，如app1.dev、test.dev）
   • 记录值：ngrok.example.com（你的ngrok服务器域名）
   • TTL：建议设置为300秒（5分钟）以便快速生效

图解DNS配置流程

DNS记录生效后，可通过nslookup命令验证：

nslookup test.dev.example.com  # 应解析到ngrok服务器IP

第二步：服务器端配置

启动ngrokd时指定域名

服务器端配置是自定义域名生效的核心，需要在启动ngrokd时明确指定-domain参数：

./ngrokd -tlsKey="/path/to/tls.key" -tlsCrt="/path/to/tls.crt" -domain="example.com"

其中：

• -tlsKey和-tlsCrt指定SSL证书路径（项目中提供了示例证书：assets/server/tls/snakeoil.key和assets/server/tls/snakeoil.crt，生产环境需替换为正式证书）
• -domain参数设置基础域名，客户端将基于此生成访问地址

服务器配置验证

启动成功后，服务器日志应显示类似内容：

[INFO] [ngrokd] Starting ngrokd v1.7
[INFO] [ngrokd] Domain: example.com
[INFO] [ngrokd] Listening for control connections on :4443

第三步：客户端配置

创建配置文件

客户端配置文件（默认路径~/.ngrok）是实现自定义域名的关键。根据src/ngrok/client/config.go中的结构体定义，支持两种自定义域名方式：

server_addr: example.com:4443
trust_host_root_certs: true
tunnels:
  webapp:
    proto:
      http: 8080
    hostname: app.dev.example.com  # 完整域名方式
  apiservice:
    proto:
      http: 3000
    subdomain: api  # 子域名方式（自动拼接为api.example.com）

配置参数说明

参数名	类型	说明
server_addr	字符串	ngrok服务器地址，格式为域名:端口
trust_host_root_certs	布尔值	是否信任系统根证书，自签名证书需设为false
hostname	字符串	完整域名（如app.dev.example.com），优先级高于subdomain
subdomain	字符串	子域名前缀（如api将生成api.example.com）

启动客户端并指定配置

ngrok -config=~/.ngrok start webapp apiservice

成功连接后，客户端将显示自定义域名：

Tunnel Status                 online
Version                       1.7/1.7
Web Interface                 127.0.0.1:4040
Forwarding                    http://app.dev.example.com -> 127.0.0.1:8080
Forwarding                    http://api.example.com -> 127.0.0.1:3000

常见问题排查

1. DNS解析延迟

如果启动后提示"域名未找到"，可能是DNS记录尚未生效。可通过以下命令强制刷新本地DNS缓存：

# Windows
ipconfig /flushdns

# macOS
dscacheutil -flushcache

# Linux
systemd-resolve --flush-caches

2. 证书验证失败

当使用自签名证书时，需在客户端配置中添加：

trust_host_root_certs: false

项目中提供了客户端信任的根证书：assets/client/tls/ngrokroot.crt，可导入系统信任库解决证书警告问题。

3. 端口占用冲突

ngrok服务器默认使用4443端口（控制连接），如遇占用可通过-tunnelAddr参数修改：

./ngrokd -domain="example.com" -tunnelAddr=":4444"  # 修改为4444端口

企业级部署最佳实践

多环境隔离方案

对于团队开发，建议按环境划分不同子域名：

# 开发环境
dev:
  proto:
    http: 3000
  hostname: dev.yourcompany.com

# 测试环境
test:
  proto:
    http: 8080
  hostname: test.yourcompany.com

安全加固措施

1. 限制域名前缀：在服务器端代码中添加白名单验证（src/ngrok/server/registry.go）
2. 启用HTTP认证：通过http_auth参数设置访问密码
3. 定期轮换证书：使用Let's Encrypt免费证书并自动续期

总结与后续学习

通过本文的三步配置，你已成功实现ngrok自定义域名访问。核心要点回顾：

1. DNS配置是基础：正确设置CNAME通配符记录
2. 服务器端是关键：启动时指定-domain参数
3. 客户端是入口：通过hostname或subdomain参数指定域名

进阶学习建议：

• 研究隧道协议实现：src/ngrok/proto/http.go
• 探索多协议支持：src/ngrok/proto/tcp.go
• 参与社区贡献：查看CONTRIBUTORS文件了解贡献指南

现在，你的本地服务已经拥有专业的公网访问地址，无论是客户演示、第三方集成还是移动设备测试，都能享受稳定便捷的隧道服务。

【免费下载链接】ngrok Introspected tunnels to localhost 项目地址: https://gitcode.com/gh_mirrors/ng/ngrok