功能与能力边界
本页按当前实现列出可用功能、配置入口和使用边界。完整的端到端操作可直接参考使用示例;服务端参数见服务端配置文件参考,NPC 参数与配置文件格式见客户端配置。
功能索引
| 目标 | 阅读入口 |
|---|---|
| 选择 TCP、UDP、HTTP(S)、SOCKS5、Secret、P2P 或文件访问 | 代理模式与隧道模式 |
| 配置域名、泛域名、路径路由、Host/Header、证书或非标准端口 | 域名代理与路由 |
| 为多用户提供平台子域名、热更新证书或诊断路由命中 | 平台域名、证书热更新与规则诊断 |
| 配置 Basic 认证、白名单、黑名单、端口限制、用户和客户端配额 | 访问控制与配额 |
| 打开 TLS Bridge、KCP、压缩/加密、多路复用或健康检查 | 服务端增强功能与NPC 配置文件参考 |
| 查看真实 IP、流量、带宽、连接状态、日志、pprof 和排查顺序 | 运行说明 |
| 使用 API 自动化客户端、隧道和 Host 管理 | 对外 API v1、API 鉴权与历史 Web API |
代理模式
| 模式 | 适用场景 | 配置入口 |
|---|---|---|
| TCP | SSH、RDP、数据库、任意 TCP 服务 | Web 面板「TCP 隧道」或 NPC 配置文件 mode=tcp |
| UDP | DNS、游戏、VoIP 等 UDP 服务 | Web 面板「UDP 隧道」或 mode=udp |
| HTTP(S) 域名代理 | 网站、Webhook、接口回调 | Web 面板「域名反代」;共用 http_proxy_port / https_proxy_port |
| HTTP 正向代理 | 通过内网客户端访问 HTTP 资源 | mode=httpProxy |
| SOCKS5 | 通用代理访问内网资源 | mode=socks5 |
| Secret 私密代理 | 不固定占用公网端口的受密码保护连接 | mode=secret,访问端以 -local_type=secret 启动 NPC |
| P2P | 尝试让访问端与内网端直连 | mode=p2p,需要 p2p_ip、p2p_port 和 NAT 条件 |
| 文件访问 | 将客户端本地目录通过 HTTP 暴露 | mode=file,配置 local_path 与 strip_pre |
各模式的端口、命令和限制说明见隧道模式。普通 TCP/UDP/HTTP/SOCKS5/文件隧道占用服务端端口;域名代理使用统一 HTTP(S) 入口;Secret 与 P2P 在访问端本地监听端口。
隧道创建与复制
在 Web 面板新增普通隧道时,服务端端口留空或填 0 会由 NPS 在允许范围内自动选择未占用端口。若设置了 allow_ports,自动分配同样遵守该白名单。
隧道列表提供「复制」操作。复制会保留所属客户端、模式、目标、备注和访问控制相关设置,并分配新的隧道 ID 与服务端端口;复制后仍应确认端口开放策略、目标可达性和密钥是否符合预期。
列表搜索与筛选
客户端、普通隧道和域名规则列表的工具栏支持备注等关键字模糊搜索。管理员还可以按所属用户筛选,或选择「未分配」查看尚未关联用户的客户端及其资源;筛选会同时影响总数、分页和列表结果。用户选项以「备注(账号)」显示,客户端选项以「客户端备注(ID)」显示;隧道和域名规则列表选择用户后,客户端选项会联动收窄,也可以不选择用户而单独筛选客户端。普通用户只看到自己名下资源,不显示管理员专用的用户筛选项。列设置可将次要字段收起,展开每行详情即可查看完整配置。
用户管理和客户端列表采用两行身份信息:主要名称在上,备注在下,避免额外增加横向列;客户端备注和出口地址保持单行省略,完整内容可通过悬浮提示查看,客户端列表中的备注与所属用户内容居中显示。客户端列表默认显示入口、出口流量,表头同时标明「公网→内网」和「内网→公网」方向;中等桌面宽度会默认收起出口地址列,以同时保留两个流量列,地址仍可在列设置和展开详情中查看。域名反代入口使用带外链图标的“HTTP”“HTTPS”按钮;客户端列按“客户端备注 · 客户端 ID”和“所属用户备注 · 用户 ID”两行显示,两行都支持单行省略和悬浮全文。
隧道列表将目标地址拆成“主机”“端口”两行,只有端口的目标保持单行;多个目标按配置顺序分组展示。访问地址本身不再作为整行链接,复制按钮取得原始 host:port;TCP 隧道额外提供“HTTP”尝试按钮,便于承载 Web 服务的目标直接打开,但浏览器仍可能依据 HSTS 或 HTTPS 优先策略自动升级为 HTTPS。TCP 当前连接数默认不在列表显示,可在列设置中恢复,或展开详情查看。
域名代理能力
在 Web 面板「域名反代」新增 Host 规则,或在 NPC 配置文件中配置 host 和 target_addr。每条规则可以设置:
- 精确域名与泛域名:
app.example.com或*.example.com。DNS 仍要将相应域名解析到 NPS 公网 IP。 - 平台泛域名池:管理员可在「系统 → 全局参数」的「证书设置」Tab 中维护多个
*.example.com,按需绑定证书;用户选择后以唯一前缀创建子域名,平台证书在服务端锁定,无证书项仅支持 HTTP。DNS、续期和诊断见平台域名说明。 - 协议选择:
http、https或all。HTTP 与 HTTPS 监听端口由http_proxy_port和https_proxy_port决定;非 80/443 端口需要在浏览器 URL 中显式写出。 - 路径路由:同一个域名可按
location匹配不同路径,例如/api和/static。 - 多目标轮询:目标地址每行一个,NPS 按顺序轮换,可用于简单负载均衡。需要按存活状态摘除节点时,配合健康检查。
- Host 重写和自定义请求 Header:用于后端虚拟主机、上游鉴权或兼容已有应用;Header 每行
名称: 值。 - Basic 认证:域名代理优先使用 Host 级账号;HTTP 正向代理和 SOCKS5 优先使用混合代理规则级账号;未配置时才回退到所属客户端的公共 Basic。
- HTTPS 终结或透传:可上传/引用证书与私钥,或者让内网服务自行处理 TLS。自动 HTTPS 会将 HTTP 请求重定向到对应 HTTPS 端口。
- 真实来源 Header:
http_add_origin_header=true时,NPS 向后端添加X-Forwarded-For、X-Real-IP、X-Forwarded-Host、X-Forwarded-Proto、X-Forwarded-Port和X-Real-Proto,并支持覆盖、保留追加或仅信任指定代理。代理链路和信任边界见部署与运行说明。
HTTP 缓存
对适合缓存的 HTTP(S) 域名代理可开启:
http_cache=true
http_cache_length=100
缓存保存在 NPS 内存中,按域名和请求路径复用响应。它不替代 CDN,也不会自动识别应用的完整缓存语义;动态页面、带身份态响应或需要严格缓存控制的服务应保持关闭。http_cache_length=0 表示不限制缓存条目数,应谨慎使用以免占满内存。
代理到服务端本地
默认情况下,域名规则和隧道的目标由所绑定的 NPC 连接。若目标服务运行在 NPS 服务器本机,需要满足两个条件:
# nps.conf
allow_local_proxy=true
并在对应的隧道或 Host 规则中勾选「转发到本地」。此时 127.0.0.1:8081 指向 NPS 的网络命名空间;NPS 使用 Docker network_mode: host 时,等同于宿主机回环地址。未勾选该规则选项时,即使全局开关为 true,目标仍由 NPC 连接。
该功能允许规则创建者让 NPS 主动访问服务端可达地址,只应向可信管理员开放,并用防火墙、权限和网段隔离保护管理面板。
传输、健康检查与配置文件
压缩、加密与 TLS Bridge
客户端可在面板或 NPC 配置文件的 [common] 中设置:
compress=true
crypt=true
这会影响客户端与 NPS 的代理数据传输。需要使用标准 TLS 保护 Bridge 时,在服务端启用 tls_enable=true,客户端改连 tls_bridge_port 并传入 -tls_enable=true;自签名证书建议设置 -tls_fingerprint 或 -tls_ca_file,不要在生产环境使用 -tls_insecure_skip_verify=true。
Bridge 控制连接支持 tcp、kcp、ws、wss 和 quic。TCP TLS 可使用独立的 TLS Bridge 端口;WS/WSS 使用独立端口与 bridge_path(默认 /ws),WSS 使用服务端 Bridge 证书。KCP 可作为主 Bridge(bridge_type=kcp),也可通过 bridge_kcp_port 与 TCP 并行监听;WS/WSS 和 QUIC 也可设置独立监听端口。KCP/QUIC 使用 UDP;WS/WSS 使用 TCP,并需在前置反向代理放行 WebSocket Upgrade。QUIC Bridge 是加密的 UDP 字节流入口,NPC 使用 -type=quic,服务端和客户端的 quic_alpn 必须一致。
启用 bridge_http3=true 且 HTTPS 入口正常监听后,HTTP/3 反代 UDP 端口还可同时承载 Bridge QUIC。Web 面板通过 ALPN 与服务端 bridge_host 生成独立命令,客户端仍使用 -type=quic;这不是另一个传输实现。HTTPS 入口关闭、UDP 绑定失败或页面配置未生效时,不会生成不可用的 HTTP/3 命令。
NPC 1.1.29 及以上支持配置文件中的 conn_type=ws / wss、命令行 -type=ws / -type=wss,以及 bridge_path / -bridge_path。1.1.28 及以下仍按原 TCP/KCP 连接方式工作,不会收到新控制消息。
Web 客户端详情会同时列出所有实际启用的 Bridge 入口,每个入口都可复制普通命令和快捷启动命令。TCP、TCP + TLS 快捷命令继续使用历史 v1 格式;KCP、WS、WSS、QUIC、HTTP/3 使用可携带 Path、ALPN、SNI 和证书指纹的 v2 格式。1.1.37 起 NPC/GUI 同时兼容两种格式,同 VKey 安装多个协议系统服务时使用 -tls、-kcp、-ws、-wss、-quic、-http3 后缀。bridge_*_show 仅控制命令展示,bridge_*_show_ip/port 仅覆盖复制命令中的公网地址与端口。
多路复用
NPS 的数据连接默认使用多路复用,无需单独开启。高并发时优先检查操作系统的文件描述符、监听队列、带宽和连接数限制,参见部署与运行说明。
PROXY Protocol
TCP 隧道和域名反代可选择 PROXY Protocol V1 或 V2。开启后,NPC 在连接本地 TCP 后端前写入来源地址头,后端(例如 Nginx、HAProxy)必须显式启用对应协议解析。
它只适用于支持 PROXY Protocol 的 TCP 后端;未支持的服务会把该头当成业务数据,从而导致协议错误。域名规则默认关闭,旧规则行为不变;UDP 隧道不支持该协议。
环境变量模板
NPC 读取配置文件前会以环境变量渲染 Go 模板占位符,适合容器和批量部署:
[common]
server_addr={{.NPC_SERVER_ADDR}}
vkey={{.NPC_SERVER_VKEY}}
[web]
host={{.NPC_WEB_HOST}}
target_addr={{.NPC_WEB_TARGET}}
export NPC_SERVER_ADDR=1.1.1.1:8024
export NPC_SERVER_VKEY=replace-with-verify-key
./npc -config=conf/npc.conf
无配置文件模式也可使用 NPC_SERVER_ADDR 与 NPC_SERVER_VKEY。模板缺少对应环境变量时会渲染为空,启动前应验证最终配置和日志。
健康检查
NPC 配置文件模式支持 HTTP 与 TCP 健康检查。健康节名称必须以 health 开头:
[health_api]
health_check_timeout=2
health_check_max_failed=3
health_check_interval=10
health_http_url=/healthz
health_check_type=http
health_check_target=127.0.0.1:8081,127.0.0.1:8082
http:向http://<target><health_http_url>发起请求,返回200视为健康。tcp:能在超时时间内建立 TCP 连接视为健康。- 连续失败达到
health_check_max_failed后,NPS 会从该客户端的目标池移除该目标;检查恢复后会重新加入。
端口范围映射与指定监听 IP
NPC 配置文件模式支持 TCP/UDP 端口范围映射。server_port 与 target_port 必须一一对应;只有范围映射时可用 target_ip 指定非本机目标:
[batch_tcp]
mode=tcp
server_port=9001-9003
target_port=8001-8003
target_ip=10.1.50.2
服务端设置 allow_multi_ip=true 后,规则可指定 server_ip,从多网卡中的特定地址监听。用 allow_ports 可限制允许创建的服务端端口:
allow_ports=9001-9009,10001,11000-12000
受限端口复用
主 TCP Bridge 可以与 HTTP/HTTPS 域名代理、Web 管理及 WS/WSS Bridge 复用同一个 TCP 端口。明文 HTTP 根据 Host 分流:web_host 进入管理面板,bridge_host 进入 WebSocket Bridge,其他 Host 进入域名代理;TLS 根据 ClientHello 的 SNI 分流到 Bridge、管理面板或 HTTPS 代理。需要 TLS Bridge 与 HTTPS/管理面板共端口时,应为各入口配置不同的 bridge_host、web_host 和站点域名。TLS Bridge 与 WSS 使用同一个端口时无法区分加密后的应用协议,服务端会拒绝该冲突配置。KCP 和 QUIC 使用 UDP,不与 TCP 监听复用;新部署仍建议使用独立端口,复用时按服务端配置验证 Host/SNI 路由。
资源、访问与账号控制
客户端与用户配额
- 客户端可配置带宽、流量、最大连接数和最大隧道数。
- 普通用户可拥有多个客户端;用户级
MaxClientNum限制其名下客户端数量,管理员分配和普通用户自建共用该配额,0表示不限制。 - 用户级
MaxTunnelNum统计其所有客户端下的普通隧道与 Host 规则;管理员和普通用户创建隧道时都执行同一配额校验。 - 客户端到期时间不能晚于所属用户到期时间;客户端留空时跟随用户,到期后客户端及其隧道/Host 会被停用。
- 客户端或用户到期、停用后,其代理资源会被停止或拒绝新连接。
- 详细的对象关系、权限和迁移影响见用户体系与部署与运行说明。
IP 白名单、黑名单与访问授权
- 全局黑名单在「系统 → 全局参数」的「全局参数」Tab 中通过“全局访问控制”卡片维护,命中的来源会被所有入口拒绝。
- 客户端黑名单只作用于该客户端名下的隧道和 Host 规则。
- 客户端白名单可直接维护允许地址;需要让外部访问者自助登记时,应使用“仅允许已登记 IP”和独立的 IP 登记密钥。
- 访问者可在
/ip/register或POST /api/v1/ip-register登记服务端识别到的来源 IP;登记只保存在内存中,到期或 NPS 重启后失效。旧版跳转授权页、持久化 IP 授权列表和/authIp流程已移除。 - 在客户端、隧道或 Host 上开启「仅允许已登记 IP」后,服务端会按实际访问来源检查该客户端的
RegisteredOnly或资源级registered_only限时登记;访问者通过/ip/register或POST /api/v1/ip-register完成登记后,方可访问对应资源。 ip_limit是旧版 Bridge 来源 IP 登记总开关,与新版「仅允许已登记 IP」不是同一功能。仅旧部署仍可使用npc register -server=<NPS>:<bridge-port> -vkey=<key> -time=2写入旧登记表,单位小时;新部署应使用资源级登记与黑白名单。
白名单、黑名单和 IP 注册都依赖 NPS 实际看到的来源地址。若 NPS 位于反向代理或四层负载均衡之后,先确认源地址透传方式,再启用严格的 IP 策略。
认证与 API
- 管理员账号在
nps.conf中;普通用户、客户端级 Web 登录账号保存在 JSON 数据文件中。 - 域名代理支持 Host 级 Basic;HTTP 正向代理和 SOCKS5 支持混合代理规则级 Basic,并在留空时回退客户端公共 Basic。
/api/v1使用管理员签名或普通用户 Bearer Token;鉴权边界见API 鉴权与兼容,旧接口见历史 Web API。- 登录验证码通过
open_captcha=true开启,登录尝试限制和安全部署建议见部署与运行说明。
运维能力
- JSON 持久化:客户端、隧道、域名、用户和全局配置保存在
conf/,方便备份、迁移和恢复。 - 系统服务:NPS/NPC 支持安装、启动、停止、重启和卸载服务;命令见运行命令速查。
- Docker 与多架构镜像:服务端、客户端可容器化运行;注意容器的网络命名空间和端口发布,详见Docker 部署。
- GUI 客户端:提供 Wails GUI,用于管理连接、日志、状态和更新,见GUI 客户端。
- 日志和 pprof:
log_level/log_path控制日志;pprof_ip与pprof_port仅应在受控网络临时开启。 - 流量持久化:
flow_store_interval按分钟将流量写入配置数据;设置为空或0关闭定时持久化。
当前不支持或需要谨慎使用的能力
下列项目不应当作已支持功能部署:
- 通过任意 TCP 端口嗅探自动复用 TCP、UDP、KCP、WS/WSS 等全部传输。现有复用范围仅限受支持的 TCP Bridge、HTTP(S) 和管理面板分流。
- mTLS/客户端证书双向校验。
- 完整的
nps.conf热重载;端口、监听器和 TLS/P2P 启停都需要重启 NPS。 - NPC 的
reload子命令。修改 NPC 配置文件后应重启对应 NPC 进程或系统服务。
部署前请以本仓库版本、服务端配置文件参考和实际启动日志为准,不要直接套用其他 NPS 分支或旧版文档中的默认值。
