排障隧道时容易自设陷阱。curl --resolve 指到 127.0.0.1 会绕过公网入口 SNI 并实测 404，应解析到公网 IP；DNS 缓存会让新增 *.tunnel 记录看似未生效，本机仍解析旧阿里云 IP 并返回他站内容，需等缓存过期或强制解析。Portainer CE 响应头易误认成企业站，判断隧道生效应看 X-Proxy-By: intranet-tunnel 或 HTML 中的 Portainer 标识。此外，EnsureTunnelRule/RemoveTunnelRule 无调用点，隧道变更后反代规则不自动更新，访问域名返回内置反代 404，启动日志 rules=0 tunnel_rules=N 可判断；临时调用重载接口或重启 tunnel-server，根治需在 control 包变更处调用。

隧道客户端验证与排障要点：测隧道域名须解析到公网 IP，勿用 --resolve 指向 127.0.0.1，否则绕过 SNI 返回 404；DNS 缓存会造成新记录未生效假象。确认是否经本方案应看 X-Proxy-By: intranet-tunnel，而非仅看状态码或 Portainer 响应头；更严格可用 SHA256 与后端直连比对，动态页面改比响应头。排查可用 logs、print-config、/healthz；tunnels 含服务端下发，可能多于 tunnels.json，persistence:false 多因 data/ 权限。常见故障涉及 Token、连接/证书、502、env_file 需重建、47802 端口绑定及配置持久化。

Docker 部署内网穿透客户端：客户端只出站连服务端 47800，开启 WEB_ENABLE 后才监听 47802 的 Web 配置界面，默认绑所有接口。部署前须运行 init.sh 并授权 data/ 给 uid 10001，否则配置库降级、界面配置重启丢失。配置优先级为 client.env、Web 界面、.env、默认值；改 client.env 需重建容器，Web 保存即时生效。容器内 127.0.0.1 是自身，宿主机服务用 host.docker.internal，静态隧道用 TUNNELS_FILE。验证看 /healthz 和 X-Proxy-By；隧道变更后反代规则不会自动更新，需重载或重启服务端。实测云端链路可打通，升级不影响 data/。

飞牛 OS NAS 用 Docker 部署内网穿透客户端一次成功，三条隧道全通，服务端在线数由 0 变 1。容器场景必须用隧道文件配置，简写参数会固定为容器内 127.0.0.1，不适用。域名按全库查占用，不能跨客户端复用；落入泛域的新隧道云端无需改动。改隧道文件只需重启，改凭据文件必须强制重建。验证应比对经隧道与 NAS 直连后端的哈希，并查代理头；流量统计表存窗口增量而非累计。1.2.0 起以配置库为权威。升级前若遇家目录权限导致 Docker 配置失败，可临时指定配置目录；旧容器名冲突先删再启动；实测仅一个泛域生效。

内网穿透系统云服务器部署包提供可直接部署的 compose、nginx 与 .env 配置及离线镜像，较本机版做了四项云环境调整：postgres 不映射宿主机端口，tunnel-server 的 nofile 提至 65535，容器加 no-new-privileges，资源上限由 .env 控制。部署前须确认 amd64/arm64 架构，安全组只放行 80、443、47800 等必要端口，勿开放 47801 和 5432；填写 EXTERNAL_IP、CERT_EMAIL 并替换 nginx 中的面板与隧道域名。自动生成的强随机凭据需立即保存，CONFIG_ENCRYPT_KEY 不可更改。证书用 HTTP-01 申请，续期后手动重启 nginx。发布包含服务端、客户端镜像与升级/自包含部署包，服务器无需联网。

系统采用控制面与数据面分离：每客户端一条持久控制连接负责鉴权、心跳与隧道注册，工作连接按需创建或池化；二者复用47800端口，靠首帧区分。HTTPS由Nginx终结，服务端按Host路由明文HTTP，工作连接由客户端主动发起，内网无需开放入站端口；启用yamux后以逻辑流替代新建TCP。控制协议用4字节大端长度加JSON，含登录、隧道下发、工作连接请求和心跳。47800对外，管理入口仅本机代理，TCP隧道池、HTTPS入口和转发范围按需对外。

隧道流量统计恒为0已在v1.0.4修复。根因是1.0.1把公网入口交给内置反代时只搬流量、未搬记账，统计仍只挂在数据面路径。修法是在反代隧道连接上记账，不包ResponseWriter，以覆盖HTTP、SSE、WebSocket，并须共用同一stats.Collector，否则会静默丢弃。验证需访问隧道3次确认增量非0，且未访问隧道仍为0。1.0.1还修复反代规则不自动同步和48080监听冲突，生产compose漂移须回写仓库。