# 增强功能

> 配置 HTTPS、TLS 桥接、访问限制和 Web 管理界面反向代理

---

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

---

## 使用 HTTPS

NPS 会根据 HTTP(S) 隧道是否同时配置证书和私钥选择处理方式：

| 证书和私钥 | 行为                                 | NPS 能否获取 HTTP 层真实 IP |
| ---------- | ------------------------------------ | --------------------------- |
| 均已配置   | NPS 终止 TLS，再把请求转发到内网服务 | 能                          |
| 均未配置   | NPS 透传 TLS，由内网服务终止 TLS     | 不能                        |

![image](/image/new/https.png)

### 自动跳转 HTTPS（301）

在 Web 的 HTTP(S) 隧道编辑页勾选“自动跳转 HTTPS（301）”后，NPS 会把该域名的 HTTP 请求重定向到 `https://<隧道域名>:<https_proxy_port>`。

当前重定向目标**不会保留原请求的路径和查询参数**。如果业务依赖完整 URL，请在 Nginx、Caddy 或应用层完成 HTTP 到 HTTPS 的跳转。

### HTTPS 证书来源

Web 中的“HTTPS 证书（内容或文件路径）”和“HTTPS 私钥（内容或文件路径）”支持两种填写方式：

- 分别粘贴完整的 PEM 证书和私钥内容。
- 分别填写 NPS 服务端可读取的文件路径，例如 `/etc/letsencrypt/live/proxy.com/fullchain.pem` 和 `/etc/letsencrypt/live/proxy.com/privkey.pem`。

证书和私钥必须使用同一种方式。只要任一字段包含 `-----BEGIN`，NPS 就会把两个字段都当作 PEM 内容，而不会再把另一个字段当作路径。

使用文件路径时，NPS 会在新的 TLS 连接到来时读取文件。证书续期并原位替换文件后，后续连接通常无需重启即可使用新内容；应同时确认 NPS 进程对两个文件及其父目录有读取权限。

## TLS 桥接加密

TLS 桥接会加密 NPC 与 NPS 之间的控制和隧道流量。它只支持 TCP 桥接，并使用独立的监听端口：

```ini
# nps.conf
bridge_type=tcp
tls_enable=true
tls_bridge_port=8025
```

修改后重启 NPS，客户端连接 TLS 端口并同时启用 TLS：

```shell
./npc -server=1.1.1.1:8025 -vkey=客户端验证密钥 \
  -tls_enable=true -tls_server_fingerprint=替换为服务端实际公钥指纹
```

NPS 默认生成并持久化自签名证书，也支持自定义证书文件。NPC 默认校验服务端身份；默认自签名部署可从可信的服务端启动日志或新版 Web TLS 连接码获取公钥指纹。公共 CA、私有 CA、名称模式及迁移方法见[桥接证书与身份验证](/extend/feature/bridge-tls-certificates.html)。

## 全局设置

Web 管理界面的“全局设置”保存在 `conf/global.json`：

| 字段           | 含义                                                                                                            |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| 全局 IP 黑名单 | 一行一个精确的 IPv4 或 IPv6 地址，不支持 CIDR 或地址范围；命中后拒绝普通 TCP、HTTP(S) 和 UDP 隧道的对应入口流量 |
| 服务端对外地址 | 用于在 Web 中生成 NPC 连接命令和隧道访问地址；填写服务端 IP 或域名，不带端口和路径，留空时使用当前访问地址      |

全局 IP 黑名单不是主机防火墙，也不保护 Web 管理端口或 NPC 桥接端口。公网部署仍应使用安全组或防火墙限制这些管理入口。

## 客户端 IP 黑名单

客户端编辑页中的 IP 黑名单作用于该客户端下的普通 TCP、HTTP(S) 和 UDP 隧道。每行填写一个精确的 IPv4 或 IPv6 地址，不支持 CIDR；命中后连接或数据包会被丢弃。

## 客户端 IP 白名单与授权

客户端编辑页中的旧版“IP 白名单”只有在**启用白名单且填写授权密码**时才会执行。未在名单中的 HTTP(S) 请求会收到 `401` 授权页面，密码正确后，来源 IP 会加入该客户端的白名单。

这一功能按精确 IP 匹配，不支持 CIDR。普通 TCP 隧道会尝试向未授权连接返回同一套 HTTP 授权页面，因此只适用于 TCP 隧道内承载 HTTP 的场景；SSH、数据库等非 HTTP 协议无法通过该页面授权。UDP 隧道不执行这套白名单授权。

如果要保护 SSH、数据库等普通 TCP 隧道，请使用 [TCP 白名单与连接限频](/extend/feature/tcp-access-control.html)。该功能在单条 TCP 隧道上直接支持 IPv4、IPv6 和 CIDR，不依赖授权页面。

![img](/image/new/ip.png)

## PROXY 协议

在 Web 的 TCP 隧道编辑页选择“PROXY 协议版本”后，NPS 会在转发数据前向后端发送 PROXY v1 或 v2 头。只有正确解析相应 PROXY 协议的后端（如 Nginx、HAProxy）才能据此取得原始来源 IP；不支持该协议的后端会把头部当作业务数据。

![img](/image/new/protocol.png)

## Web 登录验证码

在 `nps.conf` 中设置：

```ini
open_captcha=true
```

重启 NPS 后，Web 登录页会要求图形验证码。结合“Web 管理保护”（连续 10 次失败封禁 1 分钟，见[说明](/extend/feature/web-protection.html)），可以缓解密码暴力尝试。

## 关闭 HTTP(S) 隧道入口

将 `http_proxy_port` 留空可关闭 HTTP 入口，将 `https_proxy_port` 留空可关闭 HTTPS 入口。修改 `nps.conf` 后需要重启 NPS。

## 流量数据持久化

`flow_store_interval` 控制流量统计的保存间隔，单位为分钟。首次自动生成配置时默认值为 `1`，即每分钟保存一次；设置为 `0`、负数或无效值会停用定时保存。

NPS 不会持久化通过 `public_vkey` 动态创建的临时客户端。

## 系统信息显示

`system_info_display` 控制 Web 首页是否显示服务端系统信息图表。首次自动生成配置时默认为 `true`；修改后重启 NPS。

## 关闭 Web 管理

将 `web_port` 留空或删除该项，然后重启 NPS。关闭前应确认仍有可用的配置和运维方式。

## 服务端多用户登录

首次自动生成配置时 `allow_user_login=true`。启用后，客户端可使用自己的 Web 凭据登录，并且只能管理自身资源：

- 客户端同时设置了 Web 用户名和 Web 密码时，使用这组凭据登录。
- 两者都为空时，用户名为 `user`，密码为该客户端的 `vkey`。

如不需要客户端登录，应设置 `allow_user_login=false` 并重启 NPS。`vkey` 本身是敏感凭据，不应通过不可信渠道发送。

## 用户注册功能

设置 `allow_user_register=true` 并重启 NPS 后，登录页会出现注册入口。公网部署前应同时设置端口范围、客户端配额和访问控制，避免匿名用户占用任意监听端口。

## 监听指定 IP

设置 `allow_multi_ip=true` 并重启 NPS 后，可在 Web 中为隧道选择服务端监听 IP。通过 `npc.conf` 创建隧道时也可在对应隧道段设置：

```ini
server_ip=192.0.2.10
```

## 客户端到期时间

在创建或修改客户端时可以填写到期时间，留空表示不过期。到期后该客户端会被自动停用，所有隧道停止服务，直到管理员延长或清空到期时间。

支持格式：`2006-01-02 15:04:05`、`2006-01-02 15:04`、`2006-01-02T15:04:05`、`2006-01-02T15:04` 或 `2006-01-02`。

## 首次启动凭据

仅当运行目录中不存在 `conf/nps.conf` 时，NPS 才会生成默认配置。`web_username` 固定为 `admin`，`web_password`、`auth_key` 和 `auth_crypt_key` 使用随机值。启动日志格式如下：

```text
[CONFIG] Auto-generated default config file: <path>
[CONFIG] Web login username: admin, password: <xxxxxxxx>
[CONFIG] auth_key: <xxxxxxxx>
[CONFIG] auth_crypt_key: <xxxxxxxxxxxxxxxx>
```

已有配置文件不会被随机改写。请保护日志和配置文件中的凭据，修改 `nps.conf` 后重启 NPS。

## 与 Nginx 配合

如果由 Nginx 复用 80/443 端口，可让 NPS 的 HTTP 隧道入口监听本机非标准端口，例如：

```ini
http_proxy_ip=127.0.0.1
http_proxy_port=8010
https_proxy_port=
```

重启 NPS 后，让 Nginx 的 HTTP 和 HTTPS 虚拟主机都代理到同一个 NPS HTTP 入口。必须保留原始 `Host`，NPS 才能匹配域名隧道：

```nginx
server {
    listen 80;
    server_name *.proxy.com;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8010;
    }
}

server {
    listen 443 ssl;
    server_name *.proxy.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8010;
    }
}
```

此方案由 Nginx 终止公网 TLS，NPS 不再监听 `https_proxy_port`。修改后先运行 `nginx -t`，再重载 Nginx。

## Web 管理使用 HTTPS

在 `nps.conf` 中设置 `web_open_ssl=true`，并配置 NPS 服务端可读取的 `web_cert_file` 和 `web_key_file`，然后重启 NPS。

## 使用 Caddy 代理 Web 管理

下面是 Caddy 2 的子路径代理示例。假设外部地址为 `http://nps.example.com/nps`，NPS Web 管理监听 `127.0.0.1:8081`：

```caddyfile
http://nps.example.com {
    @nps path /nps /nps/*
    reverse_proxy @nps 127.0.0.1:8081
}
```

同时在 `nps.conf` 中设置：

```ini
web_base_url=/nps
```

重启 NPS，并执行 `caddy reload --config /etc/caddy/Caddyfile`。反向代理必须保留 `/nps` 路径，不能在转发前去掉该前缀。

---

反链：

- [配置示例](/extend/example.html)
- [服务端配置](/server/configuration.html)