功能与兼容矩阵
本文用于交付前核对服务端、客户端和 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 命令 |
| 证书与 ACME | Host 证书、自动 HTTPS、ACME、证书热更新 | 继续读取旧证书路径 | 证书路径不存在时只影响对应规则,不阻塞其他隧道 |
| Geo 访问控制 | GeoIP/Geosite 数据加载、定时刷新、来源与目标 ACL | 不会收到 Geo 专用控制消息 | 未配置数据文件时保持原 IP/域名 ACL 行为 |
| NTP/DNS | NTP 校时、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 | 普通代码推送仅执行 CI | latest 始终指向最近一次正式发布,不代表任意 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 标签触发正式发布。
