# 用白名单和限频保护 TCP 隧道

> 用 IP 或 CIDR 白名单限制 TCP 隧道来源并为公开入口设置新连接频率上限

---

LLMS 索引： [llms.txt](/llms.txt)

---

NPS 可以在接收 TCP 隧道的新连接时，根据来源 IP 执行以下一种策略：

| 访问模式     | 适用场景                                  | 新连接处理                                          |
| ------------ | ----------------------------------------- | --------------------------------------------------- |
| 公开访问     | 必须对外公开的 SSH、数据库或其他 TCP 服务 | 允许所有来源，可按每个来源 IP 限制新连接频率        |
| 仅白名单访问 | 只允许办公网、VPN 出口或固定管理设备访问  | 只允许命中 IP/CIDR 白名单的来源，不再执行新连接限频 |

该功能只作用于 `mode=tcp` 的普通 TCP 隧道。隧道内可以承载 SSH、HTTP、HTTPS 或数据库协议，但 HTTP(S) 域名隧道、HTTP 正向代理、SOCKS5、UDP、P2P、私密代理、NPC 接入和 Web 管理都不在适用范围内。

## 在 Web 中配置 IP 白名单

1. 新增 TCP 隧道时，在“TCP 访问控制”中选择“仅白名单访问”。已有隧道可在 TCP 隧道列表中点击对应的“TCP 访问控制”编辑入口。
2. 在“允许的 IP / CIDR”中每行填一个条目，也可使用英文逗号分隔。
3. 保存后用新连接验证；策略立即应用，无需重启隧道，已建立的连接不会主动中断。

示例白名单：

```text
203.0.113.10
198.51.100.0/24
2001:db8:1234::/48
```

支持单个 IPv4、IPv6 地址和 CIDR 网段，最多 1024 个去重后的条目。填写网段时应尽量缩小范围；例如 `/24` 会允许其中所有 IPv4 地址，不要为了省事填入过大网段。

> 选择“仅白名单访问”但留空名单时，NPS 会拒绝该隧道的所有新连接。无效 IP 或 CIDR 会导致保存失败，不会自动退回公开访问。

## 确认 NPS 看到的来源 IP

白名单匹配 NPS 接受 TCP 连接时看到的对端 IP，不信任 `X-Forwarded-For`，也不解析入站 PROXY 协议。NPS 前方有四层负载均衡、NAT 网关或反向代理时，它可能只看到中间设备的地址。

配置前先查看 NPS 日志或系统连接信息，确认实际来源。客户端经由家庭宽带、移动网络或企业共享出口时，公网 IP 可能变化或被多人共用；需要稳定身份边界时，应在白名单前搭配 VPN 或业务自身认证。

全局 IP 黑名单和客户端 IP 黑名单仍优先拒绝，即使同一地址也在 TCP 白名单中。客户端累计流量和并发连接配额也仍然生效。

## 限制公开隧道的新连接频率

公开访问模式按“单条隧道 + 来源 IP”独立计数。默认在 600 秒滑动窗口内允许 600 次新连接，第 601 次会触发 600 秒封禁。来源端口不参与区分，IPv4 与它的 IPv6 映射形式视为同一地址。

管理员可在 Web 管理的“全局设置 → TCP 新连接频率限制默认值”修改：

| 设置               | 默认值 |     可用范围 |
| ------------------ | -----: | -----------: |
| 是否启用           |     是 |      是 / 否 |
| 窗口内新连接数上限 |    600 |     1～10000 |
| 滑动窗口           | 600 秒 |  1～86400 秒 |
| 封禁时间           | 600 秒 | 1～604800 秒 |

保存后，继承这些值的 TCP 隧道会对新连接实时应用，不中断已有连接。如果某条隧道的实际限频规则发生变化，它原有的连接计数和自动封禁会清空。

在新增 TCP 隧道或其“TCP 访问控制”页面中，可以选择继承全局开关、对该隧道强制启用，或对该隧道关闭限频。数值填 `0` 表示继承服务端默认值。单隧道显式设置的优先级高于全局设置。

## 在 nps.conf 中设置后备默认值

未通过 Web 保存全局 TCP 限频设置时，NPS 从 `nps.conf` 读取后备值：

```ini
tcp_conn_limit_enabled=true
tcp_conn_limit_max=600
tcp_conn_limit_window=600
tcp_conn_limit_ban=600
```

修改 `nps.conf` 后需要重启 NPS。实际优先级为：**单隧道显式设置 → Web 中的全局设置 → `nps.conf` → 内置默认值**。

## 在 npc.conf 中配置

仅允许固定管理地址访问 SSH：

```ini
[ssh]
mode=tcp
server_port=2222
target_addr=127.0.0.1:22
access_mode=whitelist
access_allowlist=203.0.113.10,2001:db8:1234::/48
```

为公开 Web 服务单独设置限频：

```ini
[public_web]
mode=tcp
server_port=8080
target_addr=127.0.0.1:80
access_mode=public
conn_limit_mode=enabled
conn_limit_max=600
conn_limit_window=600
conn_limit_ban=600
```

| 字段                | 可用值                                     |
| ------------------- | ------------------------------------------ |
| `access_mode`       | `public`（默认）或 `whitelist`             |
| `access_allowlist`  | 英文逗号分隔的 IP/CIDR                     |
| `conn_limit_mode`   | `inherit`（默认）、`enabled` 或 `disabled` |
| `conn_limit_max`    | `0` 表示继承，否则为 1～10000              |
| `conn_limit_window` | `0` 表示继承，否则为 1～86400 秒           |
| `conn_limit_ban`    | `0` 表示继承，否则为 1～604800 秒          |

由 `npc.conf` 创建的隧道在 Web 中只能查看访问策略。修改配置文件并重连 NPC 才能持久生效。端口范围配置会给每条展开的隧道复制相同策略，但各自独立计数。

## 验证和排障

1. 白名单应分别从一个允许地址和一个未允许地址发起真实协议连接，例如 SSH 登录或 HTTPS 请求。
2. 被拒绝的连接在 TCP 握手后会立即关闭，而不是像防火墙 `DROP` 一样超时。只用端口扫描器可能仍然看到端口开放，应检查业务请求是否在建立后被关闭。
3. 限频触发时，NPS 在日志中记录新的自动封禁，并每分钟汇总拒绝次数。封禁期内继续重试不会延长封禁时间。
4. 重新保存某条隧道的访问策略会清空它的连接计数和自动封禁，可用于解除误封。重启 NPS 或重新启动隧道也会清空内存中的状态。

## 能力边界

- 新连接限频统计 TCP 连接，不能判断 SSH 是否登录成功，也不统计已建立连接中的 HTTP 请求数。
- 每条隧道最多跟踪 4096 个来源 IP 和 65536 个窗口内连接事件。达到容量时，NPS 拒绝无法继续跟踪的新连接，每分钟清理过期状态。
- 这是应用层的接入控制，不防御 SYN flood 或带宽耗尽攻击。公网服务仍应配置云安全组、主机防火墙和业务自身认证。

---

反链：

- [限制客户端连接数](/extend/feature/connection-limit.html)
- [服务端配置](/server/configuration.html)
- [增强功能](/server/nps_extend.html)