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

功能与兼容矩阵

本文用于交付前核对服务端、客户端和 Web 管理面的能力。状态以当前版本为准;“旧客户端”指版本号小于等于 1.1.28 的 NPC。

功能域当前实现旧客户端行为说明
Bridge 传输TCP、TLS、KCP、WS/WSS、QUIC、HTTP/3 共用入口;可按配置选择监听继续使用原握手与原连接类型新增传输不会改变已有 TCP/TLS 端口;HTTP/3 只在 HTTPS 与 UDP 实际监听后生成命令
Bridge 握手新客户端使用挑战握手,服务端按版本自动分流使用旧握手,不接收新控制消息1.1.28 是兼容边界;两类客户端可同时在线
Bridge 快捷命令每个实际入口生成普通命令与快捷命令;TCP/TLS 用 v1,其他协议用 v2;列表显示在线连接协议v1 快捷命令与 TCP/TLS 普通命令继续可用v2 需要新版 NPC/GUI;同一 VKey 多协议系统服务按协议后缀区分
Bridge 在线实例同一 VKey 可同时存在多个实例,记录实例 ID、主机名、系统、架构、局域网地址、协议和连接时间,并支持单独断开旧 NPC 继续连接,新增实例字段为空实例身份和局域网地址需要 NPC 1.1.41 及以上
P2P新 P2P 优先,失败时回退 Secret/中继继续走旧 P2P/Secret 路径回退只影响当前连接,不影响其他隧道
TCP/UDP 隧道连接复用、来源访问控制、登记 IP、健康检查、上下行限速旧客户端继续使用原目标和本地配置新健康字段仅对支持控制消息的客户端下发
SOCKS5 UDP共享 UDP 端口、会话登记、来源地址区分、队列、空闲回收、断线回收保留原 UDP ASSOCIATE 协议UDP 会话不写入持久化日志,达到空闲时间自动释放
HTTP / SOCKS 混合代理同一公网端口可分别启用 HTTP 和 SOCKS5独立 httpProxy / socks5 规则继续可用编辑旧规则时可迁移为混合代理
域名反代HTTP/HTTPS、WebSocket、SSE/流式响应、CORS、兼容模式、路径/Header/重定向、后端健康检查、完整转发头、分阶段超时和可选隔离连接复用旧 Host 字段和证书路径继续识别Host 级 TLS 直通、TLS 终止、后端 HTTPS 分开配置;连接复用默认关闭
HTTP/3独立 HTTP/3 监听,可与 HTTP/HTTPS Host 共用规则,并可按 ALPN/SNI 承载 Bridge不参与 HTTP/3 协商需要 HTTPS 入口、证书、UDP 和 bridge_http3;运行失败会自动隐藏 Bridge 命令
证书与 ACMEHost 证书、自动 HTTPS、ACME、证书热更新继续读取旧证书路径证书路径不存在时只影响对应规则,不阻塞其他隧道
Geo 访问控制GeoIP/Geosite 数据加载、定时刷新、来源与目标 ACL不会收到 Geo 专用控制消息未配置数据文件时保持原 IP/域名 ACL 行为
NTP/DNSNTP 校时、NPC 自定义 DNS、代理 DNS、失败回退使用系统默认解析和时钟显式配置才改变默认网络路径
NAT 穿透UPnP、PCP、NAT-PMP 探测与映射保持原中继模式映射失败自动回退,不影响普通隧道
IP 登记独立登记口令、VKEY 兼容登记、有效期、仅登记 IP 访问控制;管理员管理全部登记,普通用户只管理自己客户端的登记原登记协议继续可用反代入口可读取 X-Real-IP / X-Forwarded-For;页面显示实际采用的来源;普通用户不能操作公共桶或其他用户记录
多用户与配额用户、客户端、隧道、Host 规则按授权范围隔离;客户端/用户配额统一计数;用户可设置全部客户端共享的并发连接与上下行带宽,0 为不限,P2P 直连不计量旧客户端账号字段保留管理员可查看全局数据,普通用户只看授权资源;用户级带宽会即时作用于已有连接,调低并发只限制新连接
历史用量按分钟/五分钟采集并持久化全局、用户、客户端、隧道和域名规则流量,仪表盘显示趋势,API 按账号权限查询不需要旧客户端配合默认写入 conf/usage_history.json;P2P 直连不计入,首次采样只建立累计基线
远程升级先下载校验、实际服务路径更新、独立更新器/Unix exec、GUI 运行连接恢复、进度回报和目标上线确认、故障回滚仅明确上报新版能力时发送新消息;1.1.23 起保留历史升级信号,更早版本手动升级容器重建镜像;旧更新器可能需手动迁移一次;远程升级不自动重启其他 VKey 服务,详见客户端更新
配置迁移启动时补齐新增字段,保留旧值、注释和未知字段;失败自动回滚原配置继续工作可选配置关闭后不再写入;迁移前自动备份
Web 配置维护管理员按分组维护 nps.conf,高级项联动显示,保存后提示重启不影响旧 API敏感字段只显示脱敏值,未知字段只读保留
对外 API新集成使用 /api/v1,统一响应信封、JSON 请求体、有界分页和 request_id;管理员签名与普通用户 Bearer Token 分离旧 /auth/*、/client/*、/index/*、/user/*、/global/* 路径与返回格式保持不变普通用户仅能访问授权客户端资源,管理员资源要求管理员凭据;接口不接受浏览器 Session
发布与镜像只有 vX.Y.Z 标签触发正式 Release、文档部署和 Docker 推送;同时推送版本号与 latest普通代码推送仅执行 CIlatest 始终指向最近一次正式发布,不代表任意 master 提交

设计差异与保留策略

  • 多用户权限和 JSON 持久化属于本项目的基础约束,因此所有新功能都在资源归属检查之后执行;不存在“功能已开启但越权可见”的旁路。
  • 新协议和高级控制消息都通过版本分流。旧客户端不理解的字段不会强制发送,也不会因为缺少新字段而拒绝连接;v1 快捷命令永久保留。
  • 新增的后台能力默认采用“显式开启”策略:未配置的数据文件、证书、Geo 数据、NTP 或 NAT 映射时,继续使用旧的系统默认路径。
  • 资源级限速、健康检查和 UDP 会话状态属于运行时数据,不写入额外的长期日志文件;服务重启后从配置和 JSON 数据恢复规则本身。
  • bridge_*_show 是例外:false 必须写入配置才能表达“保留监听但隐藏命令”,因此保存和升级都不会把显式关闭恢复为默认值。

最终验证项

交付前应依次执行:

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/nps
go build ./cmd/npc
cd docs && npm run docs:build
git diff --check

验证通过后,再创建与 lib/version.VERSION 完全一致的 vX.Y.Z 标签触发正式发布。

在 GitHub 上编辑此页
最后更新: 2026/11/7 20:51
Prev
升级迁移
Next
构建发布