核心概念

理解这几个术语即可掌握全部能力：Service、Handler、Transport、Chain、Router。

1. 三层架构

与 gost 一致的分层模型：

入口（Listener/Handler）：监听端口，识别协议（SOCKS5/HTTP/SS/...），得到目标地址。
路由（Router）：准入控制 → 限流 → 按 Bypass/Selector 决定走哪条链。
出口（Chain/Dialer）：沿链逐跳连接目标（每节点按协议/传输包装流）。

2. Service（服务）

一个「监听地址 + 协议入口」的实例。CLI 子命令大多是单个服务（如 socks5、ss）；run -C 支持单进程多服务共享 Router：

# router.yaml
services:
  - name: socks
    addr: 0.0.0.0:1080
    proto: socks5
  - name: web
    addr: 0.0.0.0:8080
    proto: http
    users: [admin:pass]
  - name: ss1
    addr: 0.0.0.0:8388
    proto: ss
    method: aes-256-gcm
    password: secret

3. Handler（处理入口）

每个协议一个 Handler，负责解析请求、连接目标、双向转发。当前支持全部正向入口协议：

协议	Handler	说明
`socks5/socks4/auto`	Socks5Handler 等	认证、UDP 关联
`http/http2/https`	HttpHandler	CONNECT + GET 代理
`ss/ss2/ssr`	SsHandler	加密流解析
`trojan/vmess/vless`	TrojanHandler 等	TLS 包裹 + 认证
`sni`	SniHandler	SNI 路由 YAML
`file`	FileHandler	HTTP 静态文件服务
`relay`	RelayHandler	自定义加密中继协议

4. Transport（传输层）

隧道内承载流量的底层协议，可叠加在链上：

类型	值
可靠流	`tcp` `kcp` `quic` `wt`（WebTransport）
TLS 类	`tls` `mtls` `utls`（指纹伪装）
WebSocket	`ws` `wss` `mws` `mwss`
HTTP 类	`http` `h2` `h3` `grpc`
多路复用	`mtcp` `mtls` `mux`
混淆	`ohttp` `otls` `pht` `obfs` `obfs4` `ftcp`
其他	`icmp` `ssh` `sshd` `wg` `dtls` `udp` `serial` `unix`

5. Chain / Node / Hop

链是「有序节点列表」：流量逐跳经过每个节点，链尾节点连接目标。同层多个等价节点组成一个 Hop，建链时按策略选其一。

Node 节点

字段	说明
`name`	节点名
`proto`	载荷协议：http / socks5 / ss / ss2 / ssr / vmess / vless / trojan / relay / sni
`transport`	传输层（见上表）
`addr`	`host:port`
`user/pass`	认证
`method/protocol`	加密方式 / SSR 协议插件
`tls_ca/tls_cert/tls_key/tls_servername`	TLS 参数
`wg_key/wg_peer_pub`	WireGuard 密钥

Hop 分组

chain.yaml 顶层 hops：每个 hop 是一组等价节点，建链时按选择策略挑一个。例：hops: [[nodeA1, nodeA2], [nodeB]] 表示第一跳从 A1/A2 选一，第二跳必须 B。

6. Router 编排

Router 是核心编排器：Router::new(chains, bypass, selector)。每个入口连接先过准入 → 限流 → 选链 → 转发。

Selector 选择器

候选链选择策略：RoundRobin（轮询）/ Random（随机）/ Weighted（加权）/ Hash（按目标地址哈希）。

Bypass 旁路

目标地址匹配规则（白/黑名单）：IP/CIDR、域名、通配符；reverse 取反。命中旁路的目标直接直连、不走链。

Limiter 限流

连接级限流（总连接数/并发）、流量限额（按 token/hourly_bytes 的固定窗口）、用户级限流（多用户共享 Router 时按 key 隔离）。超限返回 429/拒绝。

Observer 观测

路由事件（connect/close/route/error）记录指标，可经 Webhook POST 到外部，或由 RouterApiServer 暴露 /metrics（Prometheus）+ /status（JSON）+ Web UI。

7. 反向穿透 pf 与虚拟组网 VNet（双向服务）

pf（port-forward）是本项目提供的内网穿透能力：内网 client 主动连公网 server，把公网端口映射到内网服务。它同时构成双向服务的两半：

穿透方向（外→内）：公网端口 → 内网未公网 NAT 的服务。内网端口对公网保持不可直连，client 从任意位置访问 server 公网端口即触达内网。
组网方向（内↔内）：pfserver --virtual-net + 多机 vnet（TUN + 虚拟 IP）组成虚拟局域网，client 经虚拟 IP 直接访问其它 client 及其内网资产（小型广域网）。

术语	说明
隧道	client↔server 的加密长连接（SS2 + mux 复用，支持 8 种承载：tcp/kcp/quic/tls/mtls/ws/wss/relay）
端口分配	random / fixed / client 三模式
数据流	每条公网连接 = 一条 mux 流，经隧道转发到内网
虚拟主机 vhost	多域名共享端口，按 Host/SNI/:authority 路由
负载均衡组	同组多 client 共享端口，RR 分发
STCP/XTCP	不暴露公网端口 / P2P 打洞直连
SSH Gateway	接受标准 `ssh -R` 反向隧道
VNet 虚拟组网	多机 TUN 网卡 + 虚拟 IP 三层互通（ping/TCP/UDP），数据经 server 按虚拟 IP 路由

8. 数据流全景

公网用户 ──TCP──▶ 入口端口
                     │
                     ▼
              [Handler 协议解析]      socks5/http/ss/...
                     │ 目标地址
                     ▼
              [Router 编排]  ──► Bypass 直连？──► 直接 TCP
                     │ 选链（Selector）
                     ▼
              [Chain 链]  node1 ──▶ node2 ──▶ ... ──▶ 目标
                     │ (每节点按 proto/transport 包装流)
                     ▼
              双向 copy_bidirectional（零拷贝 splice 优化）