组件参考手册

按「监听入口 / 协议处理 / 出口 / 传输」分组索引全部子命令与参数。所有命令均与 tunnel_proxy --help 核对。

1. Listeners（监听入口）

这些子命令启动一个监听服务，作为流量入口：

子命令	功能	关键参数
`socks5`	SOCKS5 代理	`-l` `-u/--user` `-p/--pass` `-a/--users`
`socks4`	SOCKS4 / SOCKS4a 代理	`-l`
`auto`	HTTP / SOCKS4 / SOCKS5 自动协商	`-l` `-u` `-p`
`http`	HTTP 代理	`-l` `-u user:pass` `-a`
`http2`	HTTP/2 代理（h2 CONNECT）	`-l` `-a`
`https`	HTTP/2 over TLS（自签证书）	`-l` `--cert/--key` `--http1`
`ss`	Shadowsocks	`-l` `-m/--method` `--password`
`ss2`	Shadowsocks 2022	`-l` `-m` `--password`
`ssr`	ShadowsocksR	`-l` `-m` `--password` `-o/--obfs` `--obfs-host` `-p/--protocol`
`trojan`	Trojan	`-l` `--password` `--cert/--key`
`vmess`	Vmess	`-l` `--uuid`
`vless`	Vless	`-l` `--uuid`
`sni`	SNI 路由（域名→后端）	`-l` `-f/--file routes.yaml`
`file`	HTTP 静态文件服务	`-l` `-d/--dir`
`relay`	自定义加密中继	`-l` `-u` `-p`
`h3socks`	HTTP/3 SOCKS 入口	`-l`
`wtsocks`	WebTransport SOCKS 入口	`-l`
`chain`	链式代理入口	`-l` `-f/--file`
`run`	Router 编排（多服务 + 分流）	`-l` `-C/--config` `--api` `--reload` `--netns` `--api-user/--api-pass`

2. Handlers（协议处理）

协议解析与目标连接在入口侧完成的处理单元（与 gost Handler 一致）：

Handler	说明
`Socks5Handler`	SOCKS5 认证 + CONNECT/UDP 关联
`AutoHandler`	自动识别 HTTP/SOCKS4/SOCKS5
`HttpHandler`	HTTP CONNECT + 绝对 URI GET
`SsHandler`	SS 加密流
`SsrHandler`	SSR 流密码 + 混淆 + 协议插件
`TrojanHandler`	TLS + Trojan 认证
`VmessHandler`	Vmess 认证 + 加密
`SniHandler`	TLS SNI 路由
`FileHandler`	静态文件
`RelayHandler`	relay 协议

3. Dialers（客户端/出口）

用于本地验证或 stdio 中继的客户端子命令（连到对应 server）：

子命令	连接目标	关键参数
`ssclient`	SS server	`-s` `-m` `--password` `-t/--target`
`ss2client`	SS2 server	同上
`ssrclient`	SSR server	同上 + 混淆/协议插件
`trojanclient`	Trojan server	`-s` `--password` `-t`
`vmessclient`	Vmess server	`-s` `--uuid` `-t`
`vlessclient`	Vless server	同上
`relayclient`	Relay server	`-s` `-u` `-p` `-t` `--nodelay`
`rtcpclient`	RTCP 加密转发	`-s` `-k` `-t`
`runixclient`	Runix（unix/named pipe）	`-s` `-k` `-t`
`wgclient`	WireGuard（stdio 中继）	`-s` `-k` `-p`
`stdio`	SSH ProxyCommand 中继	`-t`

4. Connectors（传输承载）

传输层服务器/客户端子命令：

子命令	传输	说明
`kcp` / `kcpclient`	KCP	`-l` `-t` `--mtu` `--window` `--data-shards/--parity-shards` `--dead-link`（kcp 另 `--session-idle-timeout`）
`dtls` / `dtlsclient`	DTLS	`-l` `-t`
`mtcp`	Multiplex TCP	一条 TCP 承载多流
`mux` / `muxclient`	Mux	多路复用流
`h2` / `h2client`	HTTP/2 隧道	h2 明文隧道
`h3` / `h3client`	HTTP/3	QUIC
`wt` / `wtclient`	WebTransport	QUIC
`mtls` / `mtlsclient`	Multiplex TLS	TLS + mux
`obfs` / `obfsclient`	Obfuscation	HTTP/TLS 伪装
`obfs4` / `obfs4client`	obfs4	防探测混淆
`ohttp` `otls` `pht` `ftcp`	混淆传输	HTTP/TLS 伪装、Fake TCP
`ws` / `wsc` / `wsecho`	WebSocket	ws 隧道 + echo 验证
`quic` / `quicclient`	QUIC	UDP 可靠流
`grpc` / `grpcclient`	gRPC	gRPC 隧道
`sshtunnel` / `sshd`	SSH	SSH 隧道 / SSH 服务器
`icmp` / `icmpclient`	ICMP	QUIC-over-ICMP 传输（三平台）
`wg`	WireGuard	服务器（-l -k -p -t）

5. 反向穿透 pf 全参数

pfserver

参数	默认	说明
`--listen`	`0.0.0.0:7000`	隧道监听地址
`--password`	必填	共享密钥
`--pool`	—	公网端口池 `from-to`
`--mode`	`random`	random / fixed / client
`--port`	—	固定公网端口
`--vhost-http/--vhost-https/--vhost-http3`	—	虚拟主机共享端口
`--vhost-subdomain`	—	subdomain 基础域名
`--proxy-protocol`	—	v1 / v2 透传真实 IP
`--max-ports-per-client`	—	单 client 端口上限
`--interface`	—	公网端口绑定网卡
`--bandwidth-limit`	—	每连接带宽上限
`--web-server/--web-user/--web-pass`	—	Dashboard + Prometheus
`--transport`	`tcp`	tcp/kcp/quic/tls/mtls/ws/wss/relay
`--relay-addr/--relay-id`	—	中继地址与本 server 注册 ID（relay 传输必填，DP02）
`--tls-cert/--tls-key/--tls-client-ca`	—	TLS 服务端证书/mTLS CA
`--oidc-secret/--oidc-issuer/--oidc-audience`	—	OIDC 认证
`--tcpmux`	—	TCPMUX 单端口
`--mark`	—	socket 标记（Linux）
`--ssh-gateway/--ssh-gateway-user/--ssh-gateway-pass`	—	SSH 反向隧道网关
`--http-plugin`	—	注册事件 HTTP 回调
`--virtual-net`	关	虚拟网络注册表（V1）
`--vnet2-net 名称:CIDR`	—	VNet v2 广域网虚拟化：定义网络及独立 TUN IP 池（可重复，如 `net1:10.99.0.0/24`）
`--vnet2-peer peer@网络名`	—	VNet v2 联邦 peer：本 server 以 pfclient 身份连接 peer server，互为超级节点通告路由实现跨域互通（可重复，如 `10.0.0.2:7000@net1`）
`--server-read-timeout`	`90`	服务端控制流读超时（秒），client 静默掉线时回收死会话
`--parse-timeout`	`15`	vhost/tcpmux/SNI 头解析超时（秒），防慢速连接
`--udp-response-timeout`	`5`	UDP 响应等待超时（秒）
`--mux-window`	`1024`	mux 单流发送窗口（KiB），越大单流吞吐越高
`--mux-max-streams`	`4096`	mux 单会话最大并发流数
`--mux-tx-capacity`	`32768`	mux 数据写通道容量（帧数）

pfclient

参数	说明
`--server`	服务器地址
`--password`	共享密钥
`--mode`	分配模式（须与 server 一致）
`--port`	指定公网端口（client 模式）
`--target`	透明转发目标（与 --proto/--config/--udp 互斥）
`--udp`	UDP 穿透
`--domain`	vhost 域名注册
`--group`	负载均衡组
`--transport`	传输承载（tcp/kcp/quic/tls/mtls/ws/wss/relay，须与 server 一致）
`--relay-addr/--relay-id`	中继地址与目标 server 注册 ID（relay 传输必填，DP02）
`--tls-cert/--tls-key/--tls-ca/--tls-insecure`	TLS 客户端参数
`--oidc-token`	OIDC access token
`--tcpmux-target`	TCPMUX CONNECT 目标
`--mark`	socket 标记（Linux）
`--sniffing`	嗅探首包 HTTP Host / TLS SNI
`--stcp-server/--stcp-secret/--stcp-listen`	STCP visitor（本地监听）
`--stcp-server/--stcp-secret/--target`	STCP 服务端（不占公网端口）
`--xtcp-server/--xtcp-secret/--xtcp-listen`	XTCP visitor（UDP 打洞 + fallback）
`--xtcp-server/--xtcp-secret/--target`	XTCP 服务端（自动 UDP 打洞，KCP 加密数据面；候选经 frps 交换）
`--xtcp-punch "bind@public"`	XTCP 服务端 TCP 直连：bind = 本机绑定端口，public = 对外公布 NAT 映射端口；指定时优先 TCP 直连，数据不经 server 中转（严格 P2P）
`--stun-server`	XTCP UDP 打洞 STUN 服务器（可重复；默认公共 STUN）
`pfrelay -l :7001 [-k key]`	加密中继中枢（DERP-like，按 ID 转发加密包，DP02）
`token-gen / token-parse / token-resolve`	连接令牌生成/解析/校验（DP03）
`tc --token <tok> --target <addr>`	令牌一键建隧道（自动带密码与地址）
`p2p-ping --server ... --xtcp-server ...`	XTCP 路径探测（udp-holepunch/tcp-direct/relay-fallback + RTT，DP04）
`--server-b`	HA 备 server
`--virtual-ip`	虚拟网络 IP
`--proto`	协议模式（socks5/http/ss/.../file）
`--config`	Router 编排 YAML
`--user/--users/--pass`	认证
`--health-check/--health-interval/--health-timeout/--health-max-failed/--health-url`	健康检查
`--ports`	端口范围映射（remotePort）
`--subdomain/--basic-auth/--host-rewrite/--path-prefix`	vhost 增强
`--heartbeat-interval`	心跳间隔（秒，默认 30），NAT 保活频率
`--heartbeat-timeout`	心跳应答等待超时（秒，默认 5）
`--client-session-timeout`	建连+握手总超时（秒，默认 15）
`--reg-response-timeout`	注册响应等待超时（秒，默认 15）
`--reconnect-backoff`	重连退避初始秒数（默认 1，指数增长）
`--reconnect-backoff-max`	重连退避封顶秒数（默认 60）
`--mux-window`	mux 单流发送窗口（KiB，默认 1024）
`--mux-max-streams`	mux 单会话最大并发流数（默认 4096）
`--mux-tx-capacity`	mux 数据写通道容量（帧数，默认 32768）

vnet（虚拟组网客户端）

本机创建 TUN 网卡加入 pfserver（--virtual-net）组织的虚拟网段，以虚拟 IP 与其他 vnet client 三层互通（ping / TCP / UDP）。需 root/管理员权限。

参数	默认	说明
`--server`	必填	pfserver 地址
`--password`	必填	共享密钥（与 server 一致）
`--virtual-ip`	必填	本机虚拟 IP（如 10.99.0.2，须唯一）
`--prefix`	`10.99.0.0`	虚拟网段前缀
`--netmask`	按 prefix /16	网段掩码
`--mtu`	`1400`	TUN 网卡 MTU
`--name`	`tpvnet`	TUN 网卡名
`--transport`	`tcp`	承载（tcp/kcp/quic/tls/mtls/ws/wss/relay，与 server 一致）
`--heartbeat-interval`	`30`	心跳间隔（秒）；UDP 承载 NAT 后建议 5
`--heartbeat-timeout`	`5`	心跳应答超时（秒）

server 需 pfserver --virtual-net；虚拟 IP 冲突返回 reg-err。数据经 pf mux 隧道由 server 按虚拟 IP 路由转发（V1 中转；P2P 直连为后续）。

vnet2（VNet v2 广域网虚拟化客户端）

VNet v2 采用非规范逻辑地址 overlay + 联邦跨域路由。本机创建 TUN 网卡接入 pfserver --vnet2-net 定义的网络，以逻辑地址（可选，如 266.266.266.266）与其他 vnet2 client 互通；多个 server 通过 --vnet2-peer 联邦后跨域可达。

参数	默认	说明
`--server`	必填	pfserver 地址
`--password`	必填	共享密钥（与 server 一致）
`--net`	必填	网络名（server `--vnet2-net` 定义）
`--vaddr`	server 分配	逻辑地址（可选，如 `266.266.266.266`）
`--tun-ip`	server 分配	TUN 承载 IP（可选）
`--mtu`	`1400`	TUN MTU
`--name`	`tpvnet2`	TUN 网卡名
`--transport`	`tcp`	pf 承载（tcp/kcp/quic/tls/mtls/ws/wss/relay）
`--heartbeat-interval`	`30`	心跳间隔（秒）
`--heartbeat-timeout`	`5`	心跳应答超时（秒）

6. 工具与服务

子命令	功能	关键参数
`bench echo/ping/tput`	性能测试	`-l` `-s` `-e` `-d` `-T` `-c`
`forward`	TCP/UDP 端口转发	`-l` `-t` `-T tcp\|udp` `-f`
`rtcp`	加密 TCP 转发	`-l` `-k`
`rudp`	加密 UDP 转发	`-l` `-k`
`ssu`	SS UDP 转发	`-l` `-m` `--password`
`runix`	Unix socket / named pipe 加密承载	`-l` `-k`
`redirect` / `redu`	透明代理（Linux iptables / 其他平台 TUN）	`-l` `-f`
`tap`	TAP 虚拟网卡	`--address` `-f`
`tun`	TUN 透明代理	`--address` `-f`
`tun2socks`	TUN 流量全走 SOCKS	`--address` `-x socks5://`
`dns`	DNS 代理	`-l`
`serial`	串口三方向转发	`-p` `-t` `-l` `-b`
`wg-keygen`	WireGuard 密钥生成	—
`tunnel` / `unix`	简易 TCP/Unix 隧道	`-l` `-t`

7. Router 编排配置

# run -C router.yaml
chains:                # 候选代理链
  - name: c1
    nodes:
      - name: hop1
        proto: socks5
        addr: 1.2.3.4:1080
        user: u
        pass: p
    retry: 2
strategy: RoundRobin   # RoundRobin / Random / Weighted / Hash
bypass:                # 旁路直连
  - 127.0.0.0/8
  - "*.internal"
reverse: false
max_conn: 1000          # 并发连接上限（0 = 不限）
rate: 0                 # 每连接速率限制（字节/秒，0 = 不限）
traffic: 0              # 每连接总流量上限（字节，0 = 不限）
services:              # 单进程多服务
  - name: socks
    addr: 0.0.0.0:1080
    proto: socks5
webhook:               # observer 事件回调
  url: http://127.0.0.1:9000/hook
  events: [connect, close]
  timeout_secs: 5

8. API 与指标

RouterApiServer（run --api 127.0.0.1:18085）暴露；以 --api-user/--api-pass 启动可对 API 加 BasicAuth 保护：

端点	方法	说明
`/`、`/ui`	GET	内嵌 Web 仪表盘（HTML）
`/api`	GET	API 服务信息 JSON
`/metrics`	GET	运行指标（默认 JSON；`Accept: text/plain` 为 Prometheus 文本）
`/metrics/prometheus`	GET	始终 Prometheus 文本
`/status`	GET	完整状态（指标 + 链信息 + 策略）
`/api/reload`	POST	热重载配置（需 `--reload` 启动）
`/api/services`	GET/POST	动态服务列表 / 启动
`/api/services/{name}`	DELETE	停止动态服务

pfserver Dashboard（--web-server）暴露 /（HTML）、/metrics（tunnel_proxy_pf_*）、/status（JSON 含 ports/vhosts/vnets）。