NAT 服务器检测与穿透建议

本文介绍面板如何自动识别 NAT 服务器、区分「可设置端口的 NAT」和「无法设置端口的 NAT」，以及在必要时引导用户使用穿透运维。

功能简介

添加服务器后，面板在 SSH 连接成功时会自动检测这台机器是否为 NAT 类型（本机只有内网地址、没有独立公网 IP）。检测到 NAT 后，会在服务器卡片上显示一个小角标，并在「概览」顶部显示一份集中的说明。用户可点击黄色角标确认该 NAT 服务器能否在服务商面板自行设置端口转发，从而决定是否需要使用穿透运维。

为什么需要区分 NAT

「内网 IP」≠「需要穿透」。NAT 服务器分两类：

只有「无法设置端口的 NAT」才需要穿透运维。可设置端口的 NAT 端口能自己映射，用起来和公网机没区别，不应被反复提醒。

检测原理

面板在 SSH 连接成功后，执行只读命令 ip -4 addr show 读取服务器本地网卡 IP，判断是否全部属于内网段：

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• 100.64.0.0/10（CGNAT 运营商级 NAT）
• 127.0.0.0/8、169.254.0.0/16、0.0.0.0/8

只要存在任意一个公网段 IP，判定为「有公网 IP」（非 NAT）；全部为内网段则判定为「NAT」。

> 检测命令是只读的，不会修改服务器任何状态。检测结果写入数据库 servers.is_nat，只在首次连接时检测一次，之后直接复用结果，不拖慢连接。

角标与说明位置

检测到 NAT 后，提示分两处呈现：

1. 系统管理面板「概览」选项卡：点击某台服务器卡片上的「系统管理」进入面板后，第一个选项卡「概览」里会显示对应的 NAT 提示横幅——黄色标记的服务器显示黄色说明（含消除指引），红色标记的服务器显示红色穿透引导。提示只在 NAT 且未确认（nat_portable !== 1）的直连服务器上出现，不挤占卡片。

2. 卡片小角标：卡片上只保留一个小的角标，分三种状态：

黄色 NAT 角标是「待确认」状态：点击弹出确认框，可二选一：

• 「端口没问题，消除标记」→ nat_portable=1，角标消失，之后不再提醒；
• 「端口无法访问，标记为需穿透」→ nat_portable=0，角标变红，引导穿透运维。

红色 需穿透 是「警告」：点击直达穿透运维 + 端口穿透。

> 为什么不做「自动探测端口能否访问」：面板服务器与目标服务器可能在同一机房，面板探测走内网，测「通」不代表外部访客能通，结果不可信。故「需穿透」由用户在黄色说明弹窗里手动标记（这种机器少，点一下即可）。

为什么 NAT 服务器「用着用着会断开」

NAT 服务器在服务商网关处有 idle timeout（空闲连接超时）。SSH 连接空闲几分钟后，网关会悄悄掐断连接（TCP 半开），而双方都感知不到。

面板通过以下两点根治：

1. SSH 连接开启 keepalive：所有连接建立后调用 Transport.set_keepalive(30)，每 30 秒发一个保活包，既防止 NAT 空闲掐断，又能及时发现半死连接。

2. 连接池定期清理：后台线程每 2 分钟关闭闲置超过 2 分钟的隐式连接（健康检查/普通操作复用的连接），防止半死连接无限堆积拖垮文件描述符和线程。

数据字段

servers 表新增两个字段：

设置接口：POST /api/servers/<id>/nat-mode，body {"nat_portable": 0|1}。

注意事项

1. 检测依赖 SSH 连接成功：服务器离线或密码错误时无法检测，is_nat 保持 -1（未检测），不显示角标。

2. 不显示角标的服务器：公网服务器、安卓机(Termux)、已穿透设备（有 tunnel_token）都不显示 NAT 角标——它们本来就走各自的通道，无需 NAT 提醒。

3. 误判留余地：极少数「1:1 NAT」（端口全通的服务器）本地 IP 也是内网，会被检测为 NAT。此时用户在确认框里选「可以」即可，不影响使用。

4. 确认后可改：角标状态由用户确认决定，随时可通过点击角标（若仍显示）或数据库字段调整。

相关文档

• 服务器管理
• 穿透运维
• 端口穿透