NPSNPS
首页
  • 安装与部署
  • 快速开始
  • 运行命令速查
  • 隧道模式
  • 使用示例
  • 使用说明
  • 配置文件
  • 增强功能
  • Docker 部署
  • 参数与安全速查
  • 使用说明
  • 增强功能
  • 配置与启动
  • 配置文件参考
  • 更新与远程升级
  • SDK
  • 功能概览
  • 域名代理与路由
  • 平台域名与证书诊断
  • 访问控制与配额
  • 运行说明
  • 配置示例
  • 对外 API v1
  • API 鉴权与兼容
  • 历史 Web API
  • 用户体系
  • FAQ
  • 升级迁移
  • 功能与兼容矩阵
  • 本项目更新日志
  • 上游更新日志
GitHub
首页
  • 安装与部署
  • 快速开始
  • 运行命令速查
  • 隧道模式
  • 使用示例
  • 使用说明
  • 配置文件
  • 增强功能
  • Docker 部署
  • 参数与安全速查
  • 使用说明
  • 增强功能
  • 配置与启动
  • 配置文件参考
  • 更新与远程升级
  • SDK
  • 功能概览
  • 域名代理与路由
  • 平台域名与证书诊断
  • 访问控制与配额
  • 运行说明
  • 配置示例
  • 对外 API v1
  • API 鉴权与兼容
  • 历史 Web API
  • 用户体系
  • FAQ
  • 升级迁移
  • 功能与兼容矩阵
  • 本项目更新日志
  • 上游更新日志
GitHub
  • 文档首页
  • 快速上手

    • 安装与部署
    • 快速开始
    • 运行命令速查
    • 完整部署参考
    • 隧道模式
    • 使用示例
  • 服务端

    • 服务端使用
    • 使用说明页面配置
    • 配置文件参考
    • 服务端增强功能
    • 服务端介绍
    • 部署安全与参数速查
    • Docker 部署
    • 宝塔面板部署
  • 客户端

    • 客户端使用
    • 客户端增强功能
    • NPC SDK
    • 客户端配置与启动
    • 配置文件参考
    • NPC Docker 部署
    • 飞牛 fnOS 原生包
    • NPC GUI 客户端
    • 客户端更新与远程升级
  • 扩展功能

    • 功能概览
    • 域名代理与路由
    • 平台域名与证书诊断
    • 访问控制与配额
    • 运行说明
    • 对外 API v1
    • API 鉴权与兼容
    • 历史 Web API
    • 使用示例
  • 项目与社区

    • 用户体系
    • 系统架构
    • 升级迁移
    • 功能与兼容矩阵
    • 构建发布
    • 本项目更新日志
    • 上游更新日志
    • FAQ
    • 贡献
    • 交流
    • 捐助
    • 致谢

功能与能力边界

本页按当前实现列出可用功能、配置入口和使用边界。完整的端到端操作可直接参考使用示例;服务端参数见服务端配置文件参考,NPC 参数与配置文件格式见客户端配置。

功能索引

目标阅读入口
选择 TCP、UDP、HTTP(S)、SOCKS5、Secret、P2P 或文件访问代理模式与隧道模式
配置域名、泛域名、路径路由、Host/Header、证书或非标准端口域名代理与路由
为多用户提供平台子域名、热更新证书或诊断路由命中平台域名、证书热更新与规则诊断
配置 Basic 认证、白名单、黑名单、端口限制、用户和客户端配额访问控制与配额
打开 TLS Bridge、KCP、压缩/加密、多路复用或健康检查服务端增强功能与NPC 配置文件参考
查看真实 IP、流量、带宽、连接状态、日志、pprof 和排查顺序运行说明
使用 API 自动化客户端、隧道和 Host 管理对外 API v1、API 鉴权与历史 Web API

代理模式

模式适用场景配置入口
TCPSSH、RDP、数据库、任意 TCP 服务Web 面板「TCP 隧道」或 NPC 配置文件 mode=tcp
UDPDNS、游戏、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 分支或旧版文档中的默认值。

在 GitHub 上编辑此页
最后更新: 2026/11/5 17:53
Next
域名代理与路由