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 配置文件参考

配置文件模式适合批量静态部署、离线配置,或将规则与基础设施代码一起管理的场景。

NPC 不会自动生成或覆盖配置文件;仓库中的 conf/npc.conf 是完整参考模板。只有服务端首次启动时会自动生成 conf/nps.conf。multi_account 指向的账号文件也需要由部署者自行创建,路径按 NPC 当前工作目录解析。

./npc -config=conf/npc.conf

一个文件包含一个 [common] 公共连接节,以及任意数量的规则节。节名称用于备注,必须唯一。NPC 会在建立到 NPS 的控制连接后注册其中的规则。

常规的 Web 面板集中管理只需使用快捷启动命令。不要同时把同一条规则长期维护在面板和 NPC 配置文件两处,以免排查时无法确认实际来源。

最小可用示例

[common]
server_addr=nps.example.com:8024
conn_type=tcp
vkey=replace-with-verify-key
auto_reconnection=true

[tcp_ssh]
mode=tcp
target_addr=127.0.0.1:22
server_port=9001

这里的 127.0.0.1 指向 NPC 进程所在主机或容器,而不是 NPS 服务器。Docker 中如目标位于宿主机,需使用宿主机可达地址或按需使用 host 网络。

[common] 公共连接配置

配置项说明
server_addrNPS Bridge 地址,格式为 主机:端口;兼容旧键名 server。
vkey客户端验证密钥。
conn_typeBridge 类型,支持 tcp、kcp、ws、wss 和 quic;兼容旧键名 tp。WS/WSS/QUIC 需要服务端启用对应独立监听。
bridge_pathWS/WSS Bridge 路径,必须与服务端 bridge_path 相同,默认 /ws。
quic_alpnQUIC Bridge 的 ALPN,必须与服务端 quic_alpn 相同,默认 nps。
auto_reconnection控制连接断开后自动重连。长期运行建议设为 true。
proxy_url通过 HTTP/HTTPS CONNECT、SOCKS4/4a、SOCKS5/SOCKS5H 出站代理连接 NPS,例如 socks5h://user:pass@127.0.0.1:1080;留空时可使用 ALL_PROXY,并按 NO_PROXY 绕过。
compress对 Bridge 数据启用 Snappy 压缩。文本或低带宽场景可考虑开启,数据本身已压缩或 CPU 较弱时通常关闭。
crypt启用项目内置加密。跨不可信网络优先使用 TLS Bridge,不要将它当作 TLS 的替代品。
tls_enable改连服务端 tls_bridge_port,默认通常为 8025。
tls_ca_file信任服务端证书的 CA 文件路径。
tls_server_nameTLS SNI 和证书名称校验值;连接地址与证书名称不同时填写。
tls_fingerprint服务端证书 SHA-256 指纹,适合自签名证书。
tls_insecure_skip_verify显式跳过证书校验,仅用于旧部署兼容,生产环境不要开启。
basic_username / basic_passwordHTTP 正向代理、SOCKS5 和域名代理共用的 Basic 认证账号。
web_username / web_password旧版客户端 Web 登录兼容账号。当前面板应优先使用客户端的“所属用户”;配置文件模式只有在需要兼容旧客户端账号登录时才填写这两个字段,二者必须成对出现。
max_conn此客户端最大数据连接数。
rate_limit此客户端带宽上限,单位 KB/s。
flow_limit此客户端累计流量上限,单位 MB,入口与出口相加计算。
disconnect_timeout未收到心跳回包的最大检查次数;检查间隔为 5 秒,默认 60,约为 5 分钟。
local_ip / local_ip_forward指定 NPC 出站绑定地址;启用 local_ip_forward=true 后,对公网 IP/域名目标的 TCP、UDP、SOCKS5 UDP 转发也使用该地址,私网目标保持系统路由。不填写时由系统自动探测或由内核选择。
dns_serverNPC 目标解析和 NAT 探测使用的 DNS 服务器,多个地址用逗号分隔;未配置时使用操作系统解析器。
ntp_server / ntp_intervalNPC 校时服务器和周期(分钟);留空关闭,避免新握手因设备时钟偏差失败。
fallback_secretP2P 直连失败后是否回退到同任务 Secret 中继。
secret_link是否向已允许 allow_secret_link 的服务端发送 Link 元数据;旧服务端或服务端未开启时保持关闭。
disable_remote_update设为 true 后拒绝服务端下发的远程更新指令。
pprof_addr可选调试监听地址,例如 127.0.0.1:9999。只允许在受控网络使用。
remark客户端显示备注。

服务端是否执行 max_conn、rate_limit 和 flow_limit,取决于对应的 allow_* 开关。具体配额语义见运行说明。

upload_limit 和 download_limit 写在隧道或 Host 规则节中,而不是 [common]。同一条规则的所有连接共享对应方向的令牌桶;它们与客户端级 rate_limit、服务端全局带宽限制叠加生效。限速器只在 NPS 服务端转发链路上生效,P2P 成功直连时不经过 NPS,因此不受服务端资源限速影响。

HTTP(S) 域名规则

域名规则包含 host,不需要 mode:

[web_api]
host=api.example.com
target_addr=127.0.0.1:3000,127.0.0.1:3001
scheme=all
location=/api
host_change=api.internal.example
header_X-Environment=production
header_X-Proxy-Source=nps
配置项说明
host精确域名或泛域名,例如 app.example.com、*.example.com。DNS 必须解析到 NPS。
target_addr后端目标,多个地址以英文逗号分隔。
schemehttp、https 或 all。
auto_https开启后,HTTP 请求以 301 跳转到该规则的 HTTPS 入口;规则必须同时支持 HTTPS。
location路径匹配前缀,例如 /api。
host_change转发给后端时替换 HTTP Host。
header_名称新增或替换请求 Header,例如 header_X-Env=prod。
response_名称新增或替换后端响应 Header,例如 response_Cache-Control=no-cache;不改变响应正文。
proxy_protocol后端支持时传递 PROXY Protocol:0 关闭、1 v1、2 v2。普通 HTTP 服务不要开启。
target_is_https让 NPS 到内网目标这一段使用 HTTPS;公网入口协议仍由 scheme 决定。
https_just_proxy不终止公网 TLS,将加密流原样转给后端;路径重写、Header、CORS、Basic 等七层能力不可用。
tls_offloadNPS 终止公网 TLS 后,把解密后的原始 TCP 流交给后端;不执行 HTTP 路由和改写。
auto_ssl该 Host 是否参与自动 ACME 申请;还需服务端 force_auto_ssl=true 和可用的公网验证条件。平台域名证书由管理员托管,不能自动申请。
path_rewrite每行一条路径替换规则,例如 /api => /v1/api;查询参数保持不变。
redirect_url可选 307 重定向地址,{path} 会替换为原始请求路径和查询参数。填写后该 Host 不再转发到后端。
auto_cors是否自动追加宽松 CORS 响应头;不会代替后端处理 OPTIONS 预检。
compat_mode是否让普通 HTTP 请求走标准反向代理兼容链路,适用于 SSE、流式响应或复杂 Header。
authHost 级 Basic 认证账号,格式 用户名:密码;密码可以包含冒号。配置后优先于客户端公共 Basic。
multi_accountHost 独立 Basic 认证账号文件;每行 用户名=密码,路径按 NPC 当前工作目录解析。该规则认证优先于客户端公共 Basic 账号。
upload_limit此 Host 规则上行限速,单位 KB/s;访问者到内网服务,0 或留空表示不限速。
download_limit此 Host 规则下行限速,单位 KB/s;内网服务到访问者,0 或留空表示不限速。

proxy_protocol 同时接受本项目旧配置中的 proto_version=V1 / proto_version=V2 写法。省略时保持关闭,因此旧配置的转发行为不变。只有当后端明确配置为接收 PROXY Protocol 时才启用,否则后端通常会把 PROXY 头当作错误的 HTTP 数据。

配置文件只描述路由规则。HTTP/HTTPS 监听端口、证书和自动 HTTPS 仍由 NPS 服务端配置控制。DNS、非 80/443 端口和证书流程见隧道模式。

TCP 与 UDP 隧道

[tcp_rdp]
mode=tcp
target_addr=192.168.10.20:3389
server_port=13389

[udp_dns]
mode=udp
target_addr=127.0.0.1:53
server_port=5353
配置项说明
modetcp 或 udp。
server_portNPS 对公网监听的端口;云安全组和系统防火墙也必须放行。
target_addrNPC 所在网络可访问的目标地址。
server_ip可选。服务端开启 allow_multi_ip=true 后,将规则绑定到指定 NPS 网卡地址。
upload_limit此隧道上行限速,单位 KB/s;访问者到内网服务,0 或留空表示不限速。
download_limit此隧道下行限速,单位 KB/s;内网服务到访问者,0 或留空表示不限速。
proxy_protocolTCP 隧道可配置 0(关闭)、1(v1)或 2(v2);只有目标服务显式支持时才开启。兼容旧键 proto_version=V1 / V2。
target_typeSecret/P2P 任务的目标协议:tcp(默认)、udp 或 all。UDP 使用带长度前缀的数据报帧。

HTTP 正向代理、SOCKS5 与文件访问

[mixed_proxy]
mode=mixProxy
server_port=18080
http_proxy=true
socks5_proxy=true
dest_acl_mode=1
dest_acl_rules=10.0.0.0/8,geosite:private

[socks_outbound]
mode=socks5
server_port=1080
multi_account=conf/socks-users.conf

[file_share]
mode=file
server_port=19008
local_path=/srv/share
strip_pre=/files/

mixProxy 在同一端口按客户端首包自动分流 HTTP 正向代理与 SOCKS5。http_proxy 和 socks5_proxy 至少开启一种;两项都省略或都为 false 时,兼容逻辑会按两种都开启处理,因此需要单协议监听时应显式写成一项 true、另一项 false。

配置项说明
modemixProxy 为混合代理;历史 httpProxy、socks5 仍可单独使用。
http_proxy / socks5_proxymixProxy 内分别控制 HTTP 与 SOCKS5 开关。
dest_acl_mode混合代理目标 ACL:0 关闭、1 白名单、2 黑名单;只对 mixProxy 生效。
dest_acl_rules目标规则,逗号或换行分隔;支持 IP/CIDR、full:、domain:、keyword:、geoip:、geosite:。
multi_accountSOCKS5 独立账号文件,一行一个 用户名=密码。
local_path / strip_pre文件访问的本地根目录和对外路径前缀;访问 http://<NPS>:19008/files/ 时映射到该目录。

HTTP/SOCKS5 默认使用 [common] 的 basic_username 和 basic_password。在 Web/API 创建的混合代理规则还可以配置独立 proxy_auth,此时该规则优先使用独立账号,不回退客户端 Basic;NPC 配置文件当前没有对应的 proxy_auth 键。文件服务、SOCKS5 和 HTTP 正向代理暴露到公网前必须设置强认证并限制来源。

Secret 与 P2P

[secret_ssh]
mode=secret
password=replace-with-secret
target_addr=127.0.0.1:22

[p2p_ssh]
mode=p2p
password=replace-with-p2p-secret
target_addr=127.0.0.1:22

Secret 和 P2P 都需要一个访问端 NPC 在本地开端口。可以通过命令行启动,也可在同一配置文件中增加不含 mode 的本地访问节:

[secret_access]
local_port=2001
password=replace-with-secret

[p2p_access]
local_port=2002
password=replace-with-p2p-secret
target_addr=127.0.0.1:22
配置项说明
local_port访问端在 NPC 所在机器监听的端口。
local_ip访问端监听地址;留空为 0.0.0.0。
password对应的 Secret 或 P2P 任务密钥。
target_addrP2P 本地访问端使用的目标;Secret Link 模式也用它生成 Link 元数据。
target_typetcp(默认)、udp 或 all。
fallback_secretP2P 直连失败时是否回退 Secret;Secret 类型始终使用 Secret。
local_proxySecret Link 是否允许目标指向 NPS 主机本地地址;还受服务端 allow_secret_link 和 allow_secret_local 限制。

节名称必须以 secret 或 p2p 开头,NPC 才会把它识别为本地访问端。Secret/P2P 的命令和 NAT 限制见客户端配置。

P2P 版本兼容

NPC 1.1.28 及以下继续使用历史 UDP/KCP P2P 握手;NPC 1.1.29 及以上使用带时间校验的安全 Bridge 握手和现代 NAT 打洞。服务端同时保留两条路径,不会向旧 NPC 下发新控制帧。现代直连失败时,只有 fallback_secret=true 且服务端对应 Secret 任务存在、并允许 Secret 访问时才会回退;普通 TCP、HTTP、WebSocket 和文件转发不依赖 P2P。

现代 P2P 需要服务端开放 p2p_port 对应的旧版 +0..+2 UDP 端口和新版 +3..+5 UDP observer 端口。UPnP、PCP、NAT-PMP 默认关闭,只有明确打开服务端开关并且局域网网关支持时才会申请端口映射。映射失败不会阻塞普通转发。

健康检查

健康检查节名称必须以 health 开头。配置文件模式下可将不健康的后端临时从目标池移除;Web 面板为隧道或域名规则保存的健康检查也会通过兼容的新控制消息下发到 NPC。旧版 NPC 会忽略这部分 Web 配置并继续使用本地配置,不会影响普通隧道连接:

[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:8080,127.0.0.1:8082
配置项说明
health_check_typehttp 或 tcp。HTTP 返回 200、或 TCP 在超时内建立连接,视为健康。
health_check_target多个目标使用英文逗号分隔。
health_http_urlHTTP 检查路径。
health_check_timeout单次检查超时秒数。
health_check_max_failed连续失败次数达到该值后摘除目标。
health_check_interval检查间隔秒数。

health_check_target 为空时整组健康检查关闭,检查类型、超时、失败阈值等参数都会被忽略,也不会自动复用任务原本的 target_addr。只填写一个目标时仍会执行检查;该目标达到连续失败阈值后会被摘除,任务可能暂时没有可用后端。

端口范围映射

[batch_tcp]
mode=tcp
server_port=9001-9003,9010
target_port=8001-8003,8010
target_ip=192.168.10.20

server_port 与 target_port 必须一一对应。仅在范围映射时使用 target_ip;不填写时目标默认是 NPC 本地回环地址。服务端还可用 allow_ports 限制允许开放的端口范围。

环境变量模板

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=nps.example.com:8024
export NPC_SERVER_VKEY=replace-with-verify-key
./npc -config=conf/npc.conf

缺失的环境变量会被渲染为空。容器或自动化部署前应确认实际环境变量和启动日志,避免把空地址或空验证密钥带入生产。

参考模板

仓库中的 conf/npc.conf 保留了当前版本的完整示例。升级时请以它和服务端配置文件参考为准,避免直接复制其他 NPS 分支的旧字段。

在 GitHub 上编辑此页
最后更新: 2026/10/29 10:28
Prev
客户端配置与启动
Next
NPC Docker 部署