常见问题 FAQ
按使用场景分类排查。
1. 通用
Q：二进制怎么拿？
仓库未发布预编译二进制。源码构建见 安装指南：cargo build --release 得到 target/release/tunnel_proxy。
Q：如何查看日志排查问题？
用 RUST_LOG 控制日志级别（默认 info）：
RUST_LOG=debug tunnel_proxy socks5 -l 0.0.0.0:1080 # 详细日志（Linux/macOS）
$env:RUST_LOG="debug"; tunnel_proxy socks5 -l 0.0.0.0:1080 # Windows PowerShellQ：配置文件支持什么格式？
YAML（Router 编排 run -C router.yaml、链 chain、SNI 路由）。--reload 轮询配置文件 mtime 自动热重载，或 POST /api/reload 手动触发。
2. 正向代理
Q：SOCKS5 代理需要认证吗？
默认无需认证。加 --user user --pass pass 开启单用户认证，或 --users user1:pass1（可重复）开启多用户。
Q：curl 走代理报错？
# SOCKS5
curl -x socks5h://127.0.0.1:1080 https://example.com
# HTTP
curl -x http://127.0.0.1:8080 https://example.com
# 走 HTTP/2 明文（h2c）需特殊客户端（curl --http2 需 TLS）；可用内置 h2client 验证Q：SS/SSR 加密方式支持哪些？
SS：aes-128-gcm / aes-256-gcm / chacha20-ietf-poly1305；SS2：2022-blake3-aes-256-gcm 等；SSR：aes-128-cfb / aes-256-cfb 等 + 混淆（plain/http_simple/http_post）+ 协议插件（origin/auth_aes128_md5/auth_sha1_v4）。
3. 反向穿透 pf
Q：内网穿透连不上公网端口？
① server 端口池在防火墙放行；② client 的 --mode 与 server 一致；③ --password 密钥相同；④ client 日志（RUST_LOG=debug）确认完成注册（出现「隧道已建立」）。
Q：分配模式怎么选？
三模式：random（server 端口池随机分配，默认）、fixed（server --port 固定）、client（client --port 指定，server 校验在 --pool 内且未占用）。
Q：如何让内网服务不暴露公网端口？（STCP）
目标 client 用 --stcp-server svc1 --stcp-secret key1 --target 127.0.0.1:80 注册（不占公网端口）；访问方 client 用 --stcp-server svc1 --stcp-secret key1 --stcp-listen 127.0.0.1:9000 本地监听，连接经 server 按密钥匹配中转。
Q：P2P 直连（XTCP）怎么用？
目标注册 --xtcp-server xt1 --xtcp-secret key1 --target 127.0.0.1:80（自动 UDP 打洞，KCP 加密数据面）；访问方 --xtcp-server xt1 --xtcp-secret key1 --xtcp-listen 127.0.0.1:9000。访问方依次尝试 UDP 打洞 → TCP 直连 → fallback 经 server 中转。目标端有 NAT 端口映射时用 --xtcp-punch "0.0.0.0:[email protected]:53030"（bind@public 分离：绑内网端口、公布公网映射端口）→ 访问方直接连公布地址，数据不经 server 中转（严格 P2P）。
Q：用标准 SSH 客户端做反向隧道？
pfserver 加 --ssh-gateway 0.0.0.0:2222 --ssh-gateway-user u --ssh-gateway-pass p，然后内网机器执行 ssh -R 7000:127.0.0.1:80 u@server，公网 7000 即转发到该机 80。
Q：公网 server 挂了怎么办？（HA）
pfclient 加 --server-b server-b:7000：主 server 会话结束自动切换备，指数退避重连。
Q：怎么访问「未被公网 NAT」的 server 端口？（反向访问内网）
穿透隧道的出口在内网 client 侧，内网端口对公网保持不可直连、无需任何 NAT 映射。
内网 client 用 pfclient --target 127.0.0.1:<内网端口> 注册，任何位置的
client 访问 server:<公网分配端口> 即到达该内网端口（场景 N）。
Q：多台机器怎么组虚拟局域网？（VNet）
server 加 --virtual-net，各机器（root/管理员）跑
vnet --virtual-ip 10.99.0.x（每台唯一）创建 TUN 网卡加入虚拟网段，之后用
虚拟 IP 直接互通（ping / TCP / UDP），可访问其它机器及其内网资产。UDP 承载
（--transport kcp/quic）在 NAT 后建议 --heartbeat-interval 5 保活。
Q：vnet 启动失败 / 网卡不通？
确认以 root/管理员运行（需要创建 TUN 网卡）；虚拟 IP 不能与其它 client 重复（冲突
server 返回 reg-err）；--transport 须与 server 一致；ping 用
--prefix 网段内的 IP。
4. 虚拟主机
Q：vhost 访问返回 404 / 直接断开？
域名未注册。检查 pfclient --domain 域名拼写与访问的 Host/SNI 完全一致。HTTP 未注册域名返回 404；HTTPS/HTTP3 未注册直接断开（TLS 无法发明文错误）。
Q：vhost 需要认证吗？
client 注册时加 --basic-auth user:pass，浏览器访问该域名时弹 Basic 认证。Host 改写用 --host-rewrite internal.local，路径前缀路由用 --path-prefix /api。
5. 传输层
Q：KCP 模式握手失败？
确认 server 与 client 的 --transport 一致；UDP 端口未被防火墙拦截。KCP 在 UDP 上跑可靠流，弱网/丢包链路更稳，可开 FEC（--data-shards/--parity-shards）。
Q：pf 隧道支持哪些承载？
tcp / kcp / quic / tls / mtls / ws / wss / relay 八种（--transport）。tls/mtls 隧道流量加密，ws/wss 为 WebSocket 承载，relay 经加密中继中枢按 ID 转发（DP02）；mtls 服务端用 --tls-client-ca 要求客户端证书。
Q：ICMP 传输需要什么权限？怎么用？
icmp / icmpclient（QUIC-over-ICMP，对应 gost icmp://）需要 raw socket：Linux/macOS 需 root，Windows 需管理员。适合网络层只放行 ICMP 的受限网络；可靠性由 QUIC 重传保证，ICMP 报文本身允许丢失。示例见教程场景 L。
6. TUN 透明代理
Q：tun 命令启动失败？
需要管理员/root 权限 + 虚拟网卡驱动：Linux /dev/net/tun、macOS 系统扩展、Windows Wintun。非 Linux 的 redirect/redu 透明代理自动回退 TUN 实现，同样需要上述前置。
Q：tun2socks 怎么用？
sudo tunnel_proxy tun2socks --address 10.0.0.1 -x socks5://127.0.0.1:1080
# 然后把本机默认路由指向 10.0.0.1 网卡，全部流量经 SOCKS 出口7. 安全与认证
Q：HTTPS 证书告警？
https/trojan 缺省用自签证书，客户端需 --proxy-insecure 跳过校验（仅测试）；生产用 --cert/--key 指定受信任证书。
Q：pfserver 支持 OIDC 认证吗？
支持（frp auth.method=oidc 语义）：server 配 --oidc-secret/--oidc-issuer/--oidc-audience，client 注册须携带 --oidc-token（HS256 签名校验 iss/aud/exp）。
Q：怎么给 pfserver 加管理面板认证？
--web-server 0.0.0.0:7500 --web-user admin --web-pass secret，访问面板与 /metrics 需 BasicAuth。
8. 性能
Q：怎么压测？
tunnel_proxy bench echo -l 127.0.0.1:9000 # 目标
tunnel_proxy bench ping -s 127.0.0.1:1080 -e 127.0.0.1:9000 # 延迟
tunnel_proxy bench tput -s 127.0.0.1:1080 -e 127.0.0.1:9000 -d 5 # 吞吐
# 传输层可选 tcp / ws / quic（-T）实测参考（2026-08-29 远程 NAT 联合测试）：本地 SOCKS5 吞吐 582–661 MB/s、 延迟平均 0.21ms（P99 0.48ms）、300 并发全通过；公网穿透 100 并发全通过、 RTT 104–118ms。完整报告见 docs/test-report-2026-08-29.md。
Q：如何限制带宽？
pfserver --bandwidth-limit 1MB（支持 1KB/500KB/1MB 等单位），作用于每条公网连接下载方向。
Q：可以调优哪些运行参数？
pf 内网穿透与 mux/KCP 数据面参数均可通过 CLI 覆盖默认值：
# pfserver：控制流读超时（90s）/ 头解析超时（15s）/ UDP 应答（5s）
tunnel_proxy pfserver ... --server-read-timeout 60 --parse-timeout 5 --udp-response-timeout 8
# pfclient：心跳间隔（30s）/ 应答超时（5s）/ 建连超时（15s）/ 重连退避（1s→60s）
tunnel_proxy pfclient ... --heartbeat-interval 15 --heartbeat-timeout 8 --reconnect-backoff 2
# 两侧：mux 单流窗口（KiB）/ 并发流上限 / 数据通道容量
tunnel_proxy pfserver ... --mux-window 2048 --mux-max-streams 8192 --mux-tx-capacity 65536
# KCP 传输：重传判死次数 / 空闲会话回收
tunnel_proxy kcp ... --dead-link 30
完整参数表见 docs/configuration.md §8 运行参数。
9. 平台相关
Q：Windows 上有什么限制？
无功能限制（三平台对齐）。网络命名空间（netns）仅 Linux 支持（gost 同款），其余平台启动时警告忽略。透明代理需管理员 + Wintun。
Q：redirect 透明代理在非 Linux 平台怎么工作？
Linux 用 iptables REDIRECT 内核重定向；macOS/Windows 自动切换到 TUN 透明代理（TunServer），行为一致、性能略低于内核 splice。