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
    • 贡献
    • 交流
    • 捐助
    • 致谢

服务端配置文件

配置文件路径:<nps 可执行文件目录>/conf/nps.conf

首次启动时若 conf/nps.conf 不存在会自动生成默认配置。用户名默认为 admin,web_password、auth_key、auth_crypt_key 会随机生成并打印到终端。升级时会把新版模板中缺失的必需配置项追加到已有 nps.conf,不改已有值(包括显式空值)、注释和自定义项;通过 Web 面板关闭并移除的可选监听、证书、日志和调试配置不会在下次启动时被重新添加。仅已知的不安全占位密钥会按原有安全策略轮换。历史 Bridge 字段会按所选 bridge_type 迁移:明确使用 TCP 时只从 bridge_tcp_port / bridge_tcp_ip 获取主监听值;明确使用 KCP 时优先使用 bridge_kcp_port / bridge_kcp_ip;未指定类型时根据现有字段判断。旧字段保留不删除。修改通过同目录临时文件替换,并保留原文件权限。升级前仍建议备份配置。

发布包中的已知占位值会在启动时自动轮换;显式填写的自定义值和空值不会被覆盖。生产环境建议将 Web 面板限制在管理网段、启用 HTTPS,并按最小权限开放端口。

Web 面板维护 nps.conf

管理员登录后打开「系统 → 全局参数」的「服务端配置」Tab 即可查看当前 nps.conf。页面按 HTTP(S) 入口、Bridge 与传输、客户端认证、日志、Web 管理、权限开关等功能分组;证书、私钥和 ACME 字段统一在「证书设置」Tab 中维护:

  • 标记为“可维护”的字段可以直接编辑;保存会保留原文件中的注释、自定义键和文件权限,并通过同目录临时文件原子替换。
  • 可选监听、密钥、日志归档和调试功能带有“启用此配置”开关。关闭后对应键会从有效配置文件移除,NPS 使用代码内置默认值或保持关闭。
  • 页面支持“可视化配置”和“源码视图”切换。源码视图展示完整 nps.conf,保留注释、空行、字段顺序与自定义项;保存前会校验语法、已知字段类型和关键配置关系,并使用修订号阻止并发覆盖,文件上限为 1 MiB。
  • 管理员密码、API 密钥、公共验证密钥、TOTP 等敏感值不会回显;密码/Token 输入框留空表示保持原值。私钥文件路径会正常显示以便核对,但私钥内容不会被读取。明确关闭可选字段才会删除对应键。
  • 当前版本无法安全在线修改的历史键和自定义键会在“兼容与自定义字段”中只读展示,并在保存时原样保留。
  • 大多数保存结果需要重启 NPS 才会应用端口、Bridge 监听、Web 和日志设置; Bridge 证书文件是例外,保存或原子替换有效文件后会热加载到后续 TLS 握手。 由系统服务托管的进程可以在页面确认后发起重启;直接前台运行的进程会提示手动 重启。

配置页不会把生产环境配置复制到仓库或浏览器;页面只读取当前运行目录下的 conf/nps.conf。

本文中的带宽统一使用面板显示的 KB/s,流量配额统一使用 MB,均按 1024 进制换算:1 KB/s = 1024 B/s,1 MB = 1,048,576 B。流量累计值、当前速率 和限速配置均沿用这一口径。

通用配置

名称含义默认值
bridge_type客户端与服务端连接方式 tcp 或 kcptcp
bridge_select_mode同一 VKey 存在多个在线 Bridge 会话时的新流量选择策略:Primary、RoundRobin 或 Random;无效值回退 PrimaryPrimary
bridge_ip桥接监听 IP0.0.0.0
bridge_port服务端客户端通信端口8024
bridge_kcp_port可选并行 KCP Bridge UDP 端口;0 表示关闭;与主 KCP Bridge 使用同端口时不会重复监听0
bridge_ws_port可选 WebSocket Bridge TCP 端口;0 表示关闭0
bridge_wss_port可选 TLS WebSocket Bridge TCP 端口;0 表示关闭,使用 Bridge TLS 证书0
bridge_quic_port可选 QUIC Bridge UDP 端口;0 表示关闭0
bridge_quic_ipQUIC Bridge 监听 IP;为空时跟随 bridge_ip空
bridge_cert_fileBridge 全协议共用的 TLS 证书链路径;留空时生成临时自签名证书空
bridge_key_fileBridge 全协议共用的 TLS 私钥路径;必须与证书同时配置空
quic_alpnQUIC Bridge 的 TLS ALPN 标识,服务端和 NPC 必须一致nps
quic_keep_alive_periodQUIC 空闲保活周期(秒)10
quic_max_idle_timeoutQUIC 最大空闲超时(秒)30
quic_max_incoming_streams单个 QUIC 会话允许的最大并发流数100000
bridge_pathWS/WSS Bridge URL 路径,NPC 与服务端必须一致/ws
bridge_show_pathWeb 面板生成 WS/WSS 命令时展示的 Path;留空跟随 bridge_path,只影响展示空
bridge_real_ip_headerWS/WSS Bridge 位于可信前置代理后时,用于恢复 NPC 来源地址的请求头,例如 X-Real-IP;留空不读取空
bridge_trusted_ips允许使用 bridge_real_ip_header 的代理 IP/CIDR,逗号、换行或空白分隔;只有 TCP 对端命中时才信任该请求头127.0.0.1
bridge_tcp_show是否生成 TCP 连接命令;关闭不会停止监听true
bridge_tls_show是否生成 TCP + TLS 连接命令;关闭不会停止监听true
bridge_kcp_show是否生成 KCP 连接命令;关闭不会停止 UDP 监听true
bridge_ws_show是否生成 WS 连接命令;关闭不会停止监听true
bridge_wss_show是否生成 WSS 连接命令;关闭不会停止监听true
bridge_quic_show是否生成 QUIC 连接命令;关闭不会停止 UDP 监听true
bridge_tcp_show_ip / bridge_tcp_show_portTCP 命令的对外主机名和端口覆盖;留空使用自动地址和实际监听端口空
bridge_tls_show_ip / bridge_tls_show_portTCP + TLS 命令的对外主机名和端口覆盖空
bridge_kcp_show_ip / bridge_kcp_show_portKCP 命令的对外主机名和 UDP 端口覆盖空
bridge_ws_show_ip / bridge_ws_show_portWS 命令的对外主机名和端口覆盖,适合 CDN 或端口映射空
bridge_wss_show_ip / bridge_wss_show_portWSS 命令的对外主机名和端口覆盖空
bridge_quic_show_ip / bridge_quic_show_portQUIC 命令的对外主机名和 UDP 端口覆盖空
bridge_quic_show_alpnQUIC 命令展示的 ALPN;留空跟随 quic_alpn空
bridge_http3是否允许浏览器 HTTP/3 共用的 QUIC 入口同时承载 Bridge;需要 HTTPS 入口、HTTP/3 UDP 监听、证书和 bridge_host 正确配合false
bridge_addr客户端列表中生成 NPC 命令使用的对外 Bridge 主机名/IP;留空时按 Web 访问地址自动识别(空)
bridge_hostBridge 端口复用时标识 Bridge 流量的 Host/SNI;应与管理域名及普通站点域名区分(空)
tls_enable是否开启 TLS。开启后客户端可通过 -tls_enable=true 连接 tls_bridge_porttrue
tls_bridge_portTLS 桥接端口,默认 8025。与 bridge_port 并存:客户端可分别用 bridge_port(明文)或 tls_bridge_port(TLS)接入8025
disconnect_timeout未收到 mux 心跳回包的最大次数;每次检查间隔为 5 秒,默认 60(即约 5 分钟)60
flow_store_interval流量数据持久化间隔,单位分钟;留空或 0 关闭定时持久化1
usage_history_enabled是否记录用户、客户端、隧道和域名规则的分钟/五分钟用量历史true
usage_history_path历史用量 JSON 快照路径conf/usage_history.json
usage_history_interval用量采样间隔,单位秒;小于 10 秒时回退为 60 秒60
usage_history_1m_hours分钟精度数据保留时长,单位小时;启动及每次采样自动清理过期点48
usage_history_5m_days五分钟精度数据保留时长,单位天;两种精度均过期后自动回收已删除资源的空记录90
usage_history_save_every每采样多少次写盘一次;正常退出时额外保存5
usage_history_max_resources历史中最多保留的资源数量20000
client_history_limit客户端详情中保留的最近连接会话数;0 关闭,最大 1005
log_level日志级别:当前格式支持 0~7,也接受文字别名 trace、debug、info、warn、error、fatal、panic、off6
log_path日志文件路径;-log_path 命令行参数优先,归档保存在同一目录nps.log
log_max_size单个日志文件大小上限(MB);0 关闭大小轮转2
log_max_files最多保留的轮转归档数量;0 不限制10
log_max_days归档保留天数;0 关闭按时间清理7
log_compress是否将轮转归档压缩为 gzip;活动日志保持纯文本false
log_rotate_daily日期变化时是否轮转日志true
ip_limit旧版 Bridge 来源 IP 登记总开关;启用后只允许已写入旧 Bridge 登记表的来源建立代理连接。它不影响新版客户端、隧道或 Host 的 RegisteredOnly,新部署请使用「仅允许已登记 IP」-

bridge_type 选择主传输,默认 tcp。WS/WSS、并行 KCP 和 QUIC 是可选独立监听,配置后需同时在防火墙开放相应 TCP/UDP 端口。Web 客户端详情按实际启用入口分页生成普通命令和快捷启动命令;bridge_*_show 是持久布尔值,关闭后仍保留在配置中,只隐藏对应命令,不会关闭监听。bridge_*_show_ip/port 和 bridge_show_path 只覆盖命令展示,不改变监听地址。旧版 NPC(1.1.28 及以下)继续使用其原有 TCP/KCP 传输;多协议 v2 快捷命令需要新版 NPC/GUI。

启用历史用量采集时,过期点会自动从内存清除,并在下一次写盘时从历史文件移除 (默认每 5 次采样,约 5 分钟;正常退出会额外保存)。已删除资源在保留期内的 历史仍可由有权限的账号查询,全部过期后回收空记录和累计采样基线;仍在配置中的 离线客户端不会被当作已删除资源。资源上限继续生效,超出时优先淘汰最久未更新的 记录。修改采样或保留配置后需重启 NPS;旧版历史文件会自动补齐用户/客户端的 范围标识,不需要删除历史文件或升级 NPC。

服务安装/运行模式使用支持大小、日期轮转及保留策略的文件日志,压缩在后台日志工作线程执行;交互式前台运行仍写入控制台。升级时缺少的必需日志配置会自动追加到 nps.conf,不会覆盖现有值;通过 Web 面板关闭的可选日志路径与轮转配置保持移除状态。

旧部署中可能还会看到 Beego 兼容字段 runmode、appname 和旧版服务端别名 https_just_proxy。这些字段会被原样保留,便于回滚和人工核对,但不要依赖它们 配置当前 NPS 的运行行为。请使用本页列出的 web_open_ssl / web_cert_file / web_key_file 及 Host 证书字段配置 HTTPS。https_default_cert_file 和 https_default_key_file 仍是当前有效字段,用于 HTTP/3 等需要默认证书的场景, 统一在「证书设置 → HTTPS 默认证书」维护;升级程序不会自动删除旧字段。

Bridge TLS 证书

「系统 → 全局参数」的「证书设置」Tab 中,“Bridge TLS 证书”区块是 bridge_cert_file、bridge_key_file 的 管理员界面,不保存额外的配置副本。当前 Bridge 全协议共用一组证书,适用于 TCP TLS、WSS、QUIC/HTTP/3 和加密内层链路。

  • 支持路径、上传和粘贴三种录入方式;上传或粘贴后文件写入 conf/bridgessl/bridge_server.pem 与 conf/bridgessl/bridge_server.key,nps.conf 只保存这两个文件路径。
  • 保存前会校验证书与私钥匹配、当前有效期和可选域名/SAN。只填写证书或只填写 私钥时拒绝保存。
  • 页面同时显示运行中证书与配置证书的 SHA-256 指纹;两者不一致时标记为 “等待下一次 TLS 握手”并给出原因。
  • 保存后会主动重新读取并校验证书,新 TLS 握手立即使用新证书,已有连接不会 被强制断开。外部脚本以原子方式替换证书文件时,后续握手也会自动检测并加载。
  • 新文件无效、缺失或证书与私钥不匹配时,继续使用最近一次有效的运行证书。 如果主动热加载失败,页面会提示需要排查;修复后可重新保存,必要时再重启 NPS。
  • 清空证书和私钥会立即切回当前进程生成的临时自签名证书;需要稳定身份或 客户端证书固定时,应始终配置可长期使用的正式证书。

HTTP(S) 代理

名称含义默认值
http_proxy_iphttp(s) 代理监听 IP,默认 0.0.0.00.0.0.0
http_proxy_port域名代理 http 监听端口(默认 80),留空关闭80
https_proxy_port域名代理 https 监听端口(默认 443),留空关闭。详见 使用 https443
http_proxy_access_port管理面板生成 HTTP 域名访问链接时使用的对外端口;留空跟随监听端口,不改变监听(空)
https_proxy_access_port管理面板生成 HTTPS 域名访问链接时使用的对外端口;留空跟随监听端口,不改变监听(空)
show_http_proxy_port域名隧道访问地址是否拼接非 80/443 端口,true / falsetrue
http_add_origin_header是否向后端添加来源地址和协议请求头true
http_forwarded_header_modeoverwrite 覆盖、preserve 保留已有头并追加、trusted 仅对可信代理保留overwrite
http_forwarded_trust_modelegacy 兼容历史行为;strict 仅信任 trusted_proxy_ips 中的代理legacy
http_cache是否开启静态文件缓存false
http_cache_length缓存条目数上限,0 表示不限制100
http_proxy_response_timeout反向代理等待后端响应头的时间,单位秒,0 表示不限100
http_client_upload_stall_timeout客户端上传停滞超时,单位秒60
http_client_response_stall_timeout访问者读取响应停滞超时,单位秒60
http_client_upload_total_timeout客户端请求体上传总时长,0 不限0
http_client_response_total_timeout非流式响应总时长,SSE/gRPC/升级连接豁免,0 不限0
http_backend_connect_timeout后端连接启动超时,单位秒,0 不限10
http_backend_tls_handshake_timeout后端 TLS 握手超时,单位秒10
http_backend_request_start_timeout后端请求启动等待上限,单位秒100
http_backend_upload_stall_timeout向后端上传写入停滞超时,单位秒60
http_backend_read_stall_timeout后端正文读取停滞超时,SSE/gRPC 豁免60
http_backend_response_total_timeout非流式后端响应总时长,0 不限0
http_backend_keepalive是否按安全隔离键复用后端连接false
http_backend_max_idle_conns / http_backend_max_idle_conns_per_host空闲连接上限128 / 16
http_backend_idle_conn_timeout后端空闲连接回收秒数90
http_backend_expect_continue_timeout100-continue 等待秒数1
http_backend_max_pools后端隔离池上限256

HTTP 正向代理和 SOCKS5 现在在 Web 面板中统一显示为“HTTP / SOCKS 混合代理”。一条混合代理隧道共用一个公网端口,可在表单中分别开启 HTTP、SOCKS5,至少保留一种。旧版本保存的 httpProxy、socks5 记录仍可访问;编辑后会迁移为混合代理记录,服务端和 API 继续兼容旧模式值。

Web 管理后台

名称含义默认值
web_hostweb 管理使用的二级域名,端口复用时区分用a.o.com
web_usernameweb 后台用户名admin
web_passwordweb 后台密码首次启动随机生成
totp_secret管理员登录 TOTP 密钥;留空关闭(空)
web_portweb 管理端口,留空关闭 web8081
web_ipweb 管理监听 IP,新安装默认仅本机访问127.0.0.1
web_base_urlweb 管理子路径,例如 /nps,用于反代到子路径时使用(空)
instance_key_fileWeb 会话实例密钥路径;留空使用 conf/instance.key(空)
web_close_on_not_found访问不存在的管理路径时尽力直接关闭连接,不返回 404;排障和常规反向代理部署通常应保持关闭false
web_open_sslweb 管理是否启用 https;远程直连时应开启。证书路径在「证书设置」维护false
web_cert_fileweb 管理 https 证书路径;在「证书设置 → 管理面板 HTTPS」维护conf/server.pem
web_key_fileweb 管理 https 私钥路径;在「证书设置 → 管理面板 HTTPS」维护conf/server.key
allow_x_real_ip是否读取前置反向代理覆盖后的 X-Real-IP/X-Forwarded-For;默认开启,Docker + Nginx 场景需确保代理覆盖而不是追加这些请求头true
trusted_proxy_ips逗号分隔的可信代理 IP/CIDR;http_forwarded_trust_mode=strict 时用于 Web 登录和 HTTP/IP 登记来源识别127.0.0.1
x_nps_http_only可选反代共享密钥;请求携带匹配的 X-NPS-Http-Only 时允许使用真实 IP 头并保持 HTTP 入口空
open_captcha登录是否开启验证码校验false
force_pow是否强制登录前完成工作量证明false
pow_bitsPoW 难度(SHA-256 前导零位数)20
audit_log_path操作/登录审计 JSONL 路径;相对路径以程序运行目录为准,留空关闭。Docker 推荐指向持久化挂载内的 /logs/audit.logaudit.log
connection_log_path客户端 Bridge、隧道与域名代理连接日志的 JSONL 路径;留空关闭connection.log
allow_user_login是否允许普通用户登录。支持独立用户的用户名或绑定邮箱与密码;客户端 VKey 登录受下一项单独控制true
allow_user_vkey_login是否允许普通用户继续使用客户端 VKey 登录;关闭后只接受独立用户账号true
allow_user_change_username多用户登录后是否允许修改用户名true

注册与邮箱验证

管理员可在「系统 → 全局参数」的「用户注册」Tab 中统一维护自助注册入口、新账号默认权益、限频和 SMTP。服务端配置的完整源码视图仍可查看并维护相同字段;注册成功后,账号使用独立用户体系保存到 users.json。

名称含义默认值
allow_user_register是否开放公开注册和邮箱密码找回;关闭时相关入口隐藏、页面跳回登录,注册/找回提交接口均拒绝请求false
register_captcha注册提交是否必须通过图片验证码true
register_max_clients新注册用户默认最大客户端数;0 表示不限制0
register_max_tunnels新注册用户默认总隧道数,域名反代也计入;0 表示不限制0
register_max_conn新注册用户全部客户端共享的最大并发连接数;0 表示不限制0
register_upload_limit新注册用户全部客户端共享的上行带宽,单位 KB/s;0 表示不限制0
register_download_limit新注册用户全部客户端共享的下行带宽,单位 KB/s;0 表示不限制0
register_expire_days新注册用户从注册成功时起默认有效天数;0 表示永久有效0
register_rate_window注册频率统计窗口,单位秒60
register_rate_limit同一 IP 或同一用户名在一个窗口内允许提交的注册次数;0 表示不限制5
register_ip_rate_limit同一来源 IP 在一个窗口内允许成功创建的账号数;0 表示不限制3
register_email_verify是否要求邮箱和一次性验证码;关闭时为用户名、密码注册false
register_email_code_ttl邮箱验证码有效期,单位秒600
register_email_code_cooldown同一邮箱或来源 IP 两次发送验证码的最小间隔,单位秒;0 表示不限制60
smtp_hostSMTP 服务器主机名;启用邮箱验证时必填空
smtp_portSMTP 端口;STARTTLS 常用 587,隐式 TLS 常用 465587
smtp_securitystarttls、ssl 或 none;none 只应用于可信内网中继starttls
smtp_username / smtp_passwordSMTP 认证用户名和密码;不需要认证的中继可留空空
smtp_from验证码邮件的发件人地址;启用邮箱验证时必填空

邮箱地址在 users.json 中统一保存为小写,并且同一邮箱只能绑定一个用户。邮件验证码只保存在内存中,有效期结束、验证成功或失败次数达到上限后即失效;发送验证码不会记录验证码原文或 SMTP 密码。

已绑定邮箱的独立用户可以使用邮箱和密码登录,无需关闭用户名登录。开放注册后可通过 /login/recover 找回密码;该页面复用 SMTP,不依赖 register_email_verify。找回验证码独立使用固定 10 分钟有效期、60 秒发送间隔、最多 5 次错误尝试,不受注册验证码有效期和冷却配置放宽。重置成功会撤销该用户旧网页会话及免登凭证,不更改 API Token 或客户端 VKey。详见用户体系。

升级不会覆盖已有 nps.conf 中的显式注册值。只补齐缺失的 register_max_conn、register_upload_limit、register_download_limit;如果旧配置仍写着 register_expire_days=7,管理员需要在「系统 → 全局参数」的「用户注册」Tab 中主动改为 0 才能得到默认永久有效。

客户端认证与公共密钥

名称含义默认值
public_vkey允许 NPC 使用的公共验证密钥;留空关闭。启用后应限制 Bridge 来源并评估审计与配额边界,发布模板中的历史值 123 会被自动清空空
auth_time_windowNPC 1.1.29 及以上安全握手允许的客户端时钟偏差秒数;0 关闭时间窗口检查,但仍使用一次性随机挑战300

public_vkey 适合受控环境中的临时接入,不应替代逐客户端 VKey。 通过公共密钥连接的客户端不会沿用普通客户端的持久化归属关系;其运行数据可能在 服务重启后丢失,后台配额和审计口径也应按公共客户端单独评估。

IP 登记

名称含义默认值
public_register_key对所有启用“仅允许已登记 IP”的资源生效的公共登记口令空
ip_register_max_hoursIP 登记页面允许的默认最长有效期(小时)2
ip_register_ip独立 IP 登记监听地址;仅 ip_register_port 非 0 时生效127.0.0.1
ip_register_port独立 IP 登记监听端口;0 表示仅使用管理面板 /ip/register0
ip_register_cert_file / ip_register_key_file独立登记监听的 HTTPS 证书与私钥,需同时填写空

allow_x_real_ip 默认开启(true):前置反向代理覆盖传递 X-Real-IP(或 X-Forwarded-For)时,NPS 优先读取 X-Real-IP,无效时回退到 X-Forwarded-For 首地址;显式设为 false 后,页面直接使用 TCP 对端地址。因此在 Docker + Nginx 部署中,应让 Nginx 覆盖而不是追加这些请求头,才能登记访问者的真实公网 IP。也可以显式关闭全局开关,只让特定入口携带与服务端一致的 X-NPS-Http-Only 请求头密钥。http_forwarded_trust_mode=legacy 保持历史行为;改为 strict 后,只有 TCP 对端命中 trusted_proxy_ips 才会读取其转发来源头。页面检测到回环/内网地址时会主动提示代理链路问题,避免所有访问者被登记成同一地址。该开关默认开启意味着直连公网且可被任意客户端访问的入口存在请求头伪造风险,此类部署应显式设为 false。

API 鉴权

名称含义默认值
auth_key管理员 API 签名密钥,详见 API 鉴权与兼容首次启动随机生成
auth_crypt_keyauth/getauthkey 接口的 AES 加密密钥,必须 16 位首次启动随机生成

管理员可在「系统 → 账户管理」直接绑定、替换或关闭 TOTP,无需手工执行 nps -gen2fa 或重启服务。确认绑定后立即生效,并要求密码和认证器中的 6 位 动态码;替换或关闭时会清理旧管理员网页会话。此设置仅作用于 Web 管理员账号, 不改变旧 NPC、普通用户或客户端账号的登录方式。源码视图仍会显示 totp_secret 配置项,生产环境不应导出或公开该值。

P2P

名称含义默认值
p2p_ip服务端 IP,使用 p2p 模式必填-
p2p_portP2P 的 UDP 起始端口,共占用连续 6 个端口。若设为 6000,旧链路使用 6000-6002,新版 NAT observer 使用 6003-6005-
p2p_stun_servers新版 P2P 使用的 STUN 地址,逗号分隔;留空使用内置列表,none 关闭内置列表
p2p_enable_upnp_portmap允许 NPC 申请 UPnP 端口映射false
p2p_enable_pcp_portmap允许 NPC 申请 PCP 端口映射false
p2p_enable_natpmp_portmap允许 NPC 申请 NAT-PMP 端口映射false
p2p_portmap_lease_seconds端口映射租约秒数,0 使用网关默认值3600
p2p_probe_timeout_msNAT 探测超时;0 使用内置默认值0
p2p_handshake_timeout_msP2P 控制协商超时;0 使用内置默认值0
p2p_transport_timeout_ms直连传输建立超时;0 使用内置默认值0

当 p2p_port=6000 时,旧版 NPC 使用 6000-6002 的 UDP/KCP 通道;新版 NPC(>=1.1.29)额外使用 6003-6005 的 UDP NAT observer。新旧端口不能只开放一组,否则不同版本的客户端会出现“能连接但 P2P 不通”。新版直连失败会按客户端任务配置自动回退到 Secret 中继;普通 TCP/HTTP 转发不依赖 P2P,P2P 探测失败不会阻塞主转发链路。

HTTP/3、证书与 ACME

名称含义默认值
http3_proxy_port浏览器 HTTP/3/QUIC 域名反代 UDP 端口;必须同时开启 HTTPS 入口和证书(空)
https_default_cert_file / https_default_key_fileHost 未单独配置证书时的默认证书和私钥conf/server.pem / conf/server.key
force_auto_ssl非标准端口也允许 Host 自动申请 ACME 证书;标准 80/443 时可不打开false
ssl_pathACME 证书缓存目录conf/ssl
ssl_emailACME 联系邮箱(空)
ssl_caACME 服务名称;LetsEncrypt 使用默认目录,ZeroSSL 使用 ZeroSSL ACME 目录LetsEncrypt
ssl_zerossl_apiZeroSSL API 密钥;启动时仅用于换取 EAB 凭据,不写入日志(空)
ssl_cache_max / ssl_cache_reload / ssl_cache_idle证书缓存上限、检查周期(秒)和空闲回收时间(秒)0 / 3600 / 60

HTTP/3 只处理能在 NPS 终止 TLS 的 Host。TLS 原样透传和后端 TLS 卸载规则继续使用 HTTPS/TCP,不会被 HTTP/3 七层处理。HTTP/3 需要同时启用 HTTPS 入口、配置可用的 http3_proxy_port,并在防火墙和云安全组放行 UDP;如果 HTTPS 入口未启用或 UDP 端口绑定失败,管理面板不会生成 HTTP/3 Bridge 命令。证书仍按 SNI 选择。启用 bridge_http3=true 时,Bridge QUIC 与浏览器 HTTP/3 可以共用 UDP 端口:协商为 h3 且 SNI 不等于 bridge_host 的连接进入浏览器 HTTP/3;SNI 命中 bridge_host 时交给 Bridge,其他 ALPN 也交给 Bridge。quic_alpn=h3 可以使用,但必须为 Bridge 保留独立的 bridge_host,不能让浏览器站点和 Bridge 共用同一个 SNI。未配置 bridge_host 时,浏览器应使用带 SNI 的站点域名;不带 SNI 的 h3 连接会按 Bridge 处理。TLS 原样透传 Host 不会被 HTTP/3 七层反代处理。

限制开关

发布配置默认启用除 allow_local_proxy 外的各项开关;关闭某项后,Web 管理面板会隐藏对应字段。

名称含义默认值
allow_flow_limit是否启用客户端流量限制true
flow_limit_type客户端历史总流量的配额计算口径:total 按上下行实际传输量之和;actual 将双向传输量之和再乘 2,因此会更快耗尽同一配额total
allow_rate_limit是否启用客户端带宽限制true
allow_tunnel_num_limit是否启用客户端最大隧道数限制true
allow_connection_num_limit是否启用客户端最大连接数限制true
allow_multi_ip是否允许每个隧道监听不同的服务端 IPtrue
allow_local_proxy是否允许把隧道目标转发到 nps 所在服务器本地false
allow_user_local是否允许普通用户在资源中启用服务端本地代理false
allow_secret_link是否允许新版 Secret 访问端发送 Link 元数据(目标、来源、ACK)false
allow_secret_local是否允许 Secret Link 访问 NPS 所在主机的本地地址false
allow_remote_update是否允许管理员从 Web 面板向在线 NPC 下发更新指令true
allow_time_limit是否执行客户端和用户的到期时间限制true
allow_ports限制可开放的隧道端口范围,例如 9001-9009,10001,11000-12000,留空不限制(空)
system_info_display是否在 web 上展示服务器系统监控信息图表true(默认开启)

运行、DNS 与登录保护

名称含义默认值
timezone日志和时间显示使用的 IANA 时区名称,例如 Asia/ShanghaiAsia/Shanghai
dns_server服务端新版 P2P/STUN 等组件使用的 DNS 服务器,多个地址用逗号分隔8.8.8.8
login_ban_time同一来源 IP 或用户名两次登录请求的最小间隔,单位秒;0 不限制间隔5
login_ip_ban_timeIP 维度失败次数的统计窗口,单位秒180
login_user_ban_time用户名维度失败次数的统计窗口,单位秒3600
login_max_fail_times任一维度在统计窗口内达到该失败次数后拒绝继续登录10
login_max_body登录请求体上限,单位字节1024
login_max_skew浏览器 RSA 登录载荷允许的客户端时间偏差,单位毫秒;0 关闭时间偏差检查,但 nonce 仍必须匹配300000

登录保护参数在进程启动时读取。修改后需重启 NPS;若反向代理没有正确覆盖 X-Real-IP / X-Forwarded-For,所有访问者可能被归入同一个 IP 桶。

NTP、GeoIP/Geosite 与 ACL

ntp_server 和 ntp_interval 用于新版 Bridge 握手的时间校准;服务端和 NPC 都可以配置,校时失败时保留上一次成功的偏移。geoip_path 和 geosite_path 支持文本规则文件以及常见的 GeoIP/Geosite protobuf 数据文件:来源名单支持 geoip:cn,混合代理目标规则还支持 geosite:private。acl_max_rules 限制每张普通用户资源的黑名单、白名单或目标 ACL 列表,默认 1000;空行和 #、; 注释行不计数,全局管理员来源名单不受此限制。geo_reload_interval 控制文件变更检查周期,默认 60 秒。

GeoIP 用于来源 IP 规则,Geosite 用于混合代理和目标 ACL 的域名匹配。geoip_path 和 geosite_path 留空时分别使用运行目录下的 conf/geoip.dat 与 conf/geosite.dat,文件不存在时对应规则保持不可用。数据文件不写入 JSON 数据库;文件出现或替换后,NPS 会按刷新周期自动重新加载并编译运行中的策略。

管理操作审计日志记录登录、用户、客户端、隧道、Host 和全局配置等控制面变更,不记录密码、验证密钥、API Token 原文、证书私钥或代理请求体。客户端连接日志记录 Bridge 主连接、子通道、认证或握手失败,以及隧道和域名代理会话,并尽可能保存公网来源地址、NPS 服务端监听地址、客户端公网 IP、客户端版本、所属用户、资源、Bridge 通道、握手阶段、目标、耗时和双向字节数。日志按 JSONL 追加写入,文件权限为仅服务账号可读写;管理员可查询全部记录,普通用户只能查询所属客户端记录。

Web“审计与连接”页面仅从各自文件尾部读取最近最多 2000 条,搜索、筛选、分页总数也限定在该窗口内,避免每次全量扫描大文件。限制不会删除文件中的旧记录,既有 /api/v1/audit 与 /api/v1/audit/connections 历史查询不变。管理员可点击“清理旧日志”,按保留天数手动清理当前 Tab 的旧记录;需要确认删除范围,普通用户不可调用。清理使用同目录临时文件原子替换,因此 NPS 服务账号还需对日志目录有写入权限和足够磁盘空间。此功能不处理 nps.log、用量历史、客户端数据或外部轮转归档,不能识别时间的记录会保留。详细步骤见审计与连接日志。

客户端内网地址来自 NPC 在 Bridge 主控制连接上主动上报,属于客户端自述信息。成功主连接会在本次上报后记录;认证成功后的子通道和代理会话使用客户端记录中的已保存值。认证前失败、版本读取失败等请求无法取得本次内网地址,只能保留公网来源和服务端可观察字段;若凭据仍能匹配到已有客户端,日志会显示其上次成功上报值,并明确标记来源,不能把该缓存值视为本次请求地址。早期失败记录也不代表 NPC 已完成认证。

客户端连接历史在客户端详情的「时间信息」中展示,仅记录 NPS 收到的 Bridge 主控制连接上线和确认离线时间,不记录请求明细。记录保存在客户端数据中,并随 flow_store_interval 配置的客户端数据持久化周期写盘;因此意外断电或进程崩溃时,最近一次变更可能尚未落盘。旧版本客户端无需升级即可使用。

debug / pprof

名称含义默认值
pprof_ipdebug pprof 监听 IP-
pprof_portdebug pprof 监听端口-
在 GitHub 上编辑此页
最后更新: 2026/11/15 16:17
Prev
使用说明页面配置
Next
服务端增强功能