NSGW · 数据网关

NSGW 是公网边缘与中继组件，通常部署在 PoP 或云区域。已实现的 managed 模式提供不透明的 WG / WSS 中继、终结、公网 HTTP / L4 入口以及 Gateway Egress / Exit。它主动向 NSD 发起登记、订阅、心跳与上报；节点主动发起 relay 会话。它在终结、公网入口、Egress 与 Exit 上判用户 ACL，全部 fail-closed。

NSGW 仓库还提供独立的 Quick relay（nsgw-quick-relay，与 nsgw-server 分开的二进制），服务 NS 的 Quick 模式：

1. 短码配对会合：/quick/v1（WebSocket，子协议 ns-quick-v1）为一次性邀请保存公开的身份证明与密文，有界过期；它不能批准对端、读取凭据或派生连接密钥。
2. 流量中继：UDP 与 /keynet/v1 WSS 载体上的已认证 slot 之间转发 WireGuard 密文，并为节点反射其 UDP 端点；多个成员可组成 relay 区域（最多 16 个，成员间 mTLS 网状连接、一跳转发、标记复制与短码服务 owner 交接）。

协议见 Quick 协议 §5、§12.5、§12.8，会合见 Quick 模式 §3。

1. 角色速读

• 位置：公网入口（PoP / cloud region）；Rust 2024 单一静态二进制（musl），kernel WireGuard（wireguard-uapi）为生产默认，BoringTun 用户态为无特权回退；可编译出只做 relay 的 slim 版本。
• 入站端口：
  • :51821/udp —— WireGuard 不解密中继（mac1 分流 + receiver-index 转发）与 NSGWP2P1 反射探测。
  • :51820/udp —— WireGuard 终结 设备（wg0），也承载 Exit / Egress 的 WG leg。
  • :9443/tcp —— WSS（rustls，可选 ACME）：/client（terminate）、/client?mode=wss-relay、/wss-relay、/relay、/exit-wss/v1。
  • :443/tcp + NSD 分配的 L4 端口 —— 公网边缘，由 host-network 的 Envoy sidecar 承载，NSGW 通过本地 ADS（:18000）下发 LDS / CDS / RDS，证书走 filesystem SDS；Envoy 只指向 NSGW 内部 listener（HTTP :8080、L4 ≥ 20000）。
  • :9091/tcp —— 管理 / livez / ready（readyz）/ metrics（bridge 私有）。
• 控制面：platform enrollment token 登记为 gateway；WebPKI 信任发现；SSE / Noise / QUIC 按发现顺序探测；60 s 心跳；30 s gateway.report；20 s gateway.realm_config_snapshot 轮询（多 realm）；gateway.services_report 上报本地 floor；gateway.usage_report 计量；接收中继测量名单（relay_probe_set.v1）。
• 信任事实：wg-relay / wss-relay / direct 下网关不持任何 WG 密钥、不见明文、不判用户 ACL；terminate / 公网入口 / Egress / Exit 下网关是 ACL 终决点之一，fail-closed，ACL 抓取失败超过 600 s 转全拒。

2. 文档结构

文档	你想了解
architecture.md	架构与功能设计（角色、五条职责、控制面接入、端口矩阵、设计特点、crate 清单）
peer-relay-protocol.md	WireGuard 不解密中继的协议层细节（mac1 分流、register_source、receiver-index 表、DoS 边界、兼容矩阵）
roadmap.md	进行中的计划、六大能力轴现状、跨组件协调点

3. 一屏速览

维度	现状（as-built）	进行中 / 规划
WG relay	mac1 分流、NAT 源学习（90 s TTL）、receiver-index 路由、因果转发租约、cookie + 令牌桶准入、会话 / pending 上限、sender-index 碰撞消歧；反射探测按源 IP 限速并应答 NSD 测量名单中的纯测量探测	配对表增量应用（PLAN-130）
terminate	WSS /client 终结 → 进程内 ACL 门 → WSS 缝合或 WG bridge 到发布端	NS 原生 WG terminate client leg（PLAN-096）
wss-relay	两条已认证出站 leg 的不透明缝合；(realm, nsc, nsn) rendezvous；250 ms 有界关闭	—
公网边缘	Envoy ADS（LDS / CDS / RDS）、filesystem SDS 证书与客户端 CA / CRL、源 IP RBAC、jwt_authn、ext_authz（OIDC / API key / 签名 URL / mTLS / Basic）、入口 ACL、L4 内部 listener、语义化 xDS 快照身份	公网 mTLS 商业化（NSD PLAN-036 集成）
Gateway Egress	单目标 L4 终结、fail-closed 主体 ACL、gateway_services.toml floor、WG client leg（nft / TPROXY）、1024 流上限、10 s 连接期限、半关闭排空	Both-protocol floor 兼容（PLAN-120）
Gateway Exit	per-pairing nft nsgw_gateway_exit SNAT（fixed / masquerade）、原子 CIDR 集替换、conntrack 上限、realm 快照收敛、/exit-wss/v1 承载；部署模式默认 docker_bridge_single_tenant	—
多 realm	served realm 独立 RealmConfigBucket，永不合并；路由按所属 realm 授权	—
控制面	WebPKI 信任发现、QUIC SPKI pin、签名 info.get 绑定 Envelope signer、版本上报	—
观测 / 运维	Prometheus /metrics（含 build_info）、/livez / /readyz、审计环、drain（/ready 503）、四类数据面计量经 gateway.usage_report 上报、Alpine 运行镜像、CAP_NET_ADMIN 单能力	大文件拆分（PLAN-107）

4. 五条数据面职责

职责	说明	用户 ACL 裁决
① wg-relay	盲转发原生 WireGuard UDP：mac1 匹配 init，之后按 receiver-index 路由；从不解密	发布端 NS（按 WG 公钥）
② terminate	终结访问端 leg（WSS /client），进程内判 ACL，重新发起到发布端的独立 leg	NSGW（terminate 绑定），发布端再判
③ wss-relay	缝合两条不透明出站 WSS leg（访问端 pump + 发布端 leg）为密文流；不持 WG 密钥	发布端 NS
④ 公网边缘	经 Envoy 承接 :443 与 NSD 分配的 L4 端口，外部鉴权 + 源 IP 准入 + 入口 ACL	NSGW（外部主体）
⑤ Egress / Exit	NSGW 终结的 L4 虚拟服务；per-NS 默认路由出口（SNAT）	NSGW（终决，fail-closed）

模式由 NSD 决定：NSD 为每条 pair 解析一种链路模式并投影 per-mode 配置，NSGW 从不自己选模式。backend 种类（NsnBacked / GatewayEgress / GatewayExit）与链路模式正交。

5. 推荐阅读顺序

1. 第一次接触 NSGW → architecture §1–§2
2. 要接 relay 协议 → peer-relay-protocol.md
3. 要规划演进 → roadmap.md