frp-sh

中文

English

中文

English

Appearance

故障排查 FAQ ​

连接类问题 ​

访客提示 room not found or expired: xxx ​

  • 房间号输入有误（区分大小写）
  • 房间已过期（默认 12 小时）或被房主 Ctrl-C 关闭
  • 让房主重新 game create 获取新房间号

访客提示 UDP echo timed out ​

客户端无法与服务器的 UDP 探测端口通信：

  • 检查服务器 8080/udp 是否放行（云安全组 + 系统防火墙都要）
  • 检查配置 signaling_addr 是否指向正确服务器
  • 用 nc -u 服务器IP 8080 或任意 UDP 客户端发 ECHO test 验证回显

一直 UDP hole punching failed, falling back to relay ... ​

打洞失败属正常现象（NAT 过于严格），会自动转中继且不影响使用。若希望直连：

  • 尝试增大 --spread（对称 NAT 场景）
  • 双方都保证 UDP 出站可用
  • 若两端在同一局域网/同一 NAT 后，公网打洞属 hairpin 场景，直连可能失败——改用 --relay

双方直连成功但数据不通（客户端连不上/连上没响应） ​

  • 确认房主 --service 指向的服务正在运行且监听正确端口
  • 确认访客 --listen 端口未被占用
  • 用 --verbose 查看帧日志是否在收发

decryption failed (wrong --key?) ​

双方 --key 口令不一致（或有一方没带）。统一口令后重开房间。

部署类问题 ​

服务器启动报端口占用 ​

text
AddrInUse
  • 8080 或 8081 被其他进程占用，换端口：
    bash
    frp-sh serve --addr 0.0.0.0:9000 --relay-addr 0.0.0.0:9001
  • 客户端配置相应改为 http://IP:9000 与 IP:9001

Windows 上快速重启服务器报「权限不允许的套接字尝试」 ​

Windows 下刚关闭的 TCP 监听端口会短暂处于过渡态，立即用同端口绑定 UDP 可能失败：

  • 等待 2~3 秒再启动
  • 或让 UDP 探测使用独立端口（signaling_udp + 服务器独立监听）

性能与稳定性问题 ​

传输慢 ​

  • 可靠流窗口为 32 帧 × 1200B ≈ 38KB 在途；高延迟链路吞吐有限
  • 若经中继，带宽受服务器出口限制
  • 打洞直连一般比中继快（少一跳服务器）

长空闲后连接失效 ​

NAT 映射有超时（通常 30~120s）。frp-sh 每秒互发 keepalive ACK 帧保活，正常不会失效；若你的 NAT 超时极短，可保持低频数据流动。

大流量时读缓冲丢弃帧 ​

读缓冲上限 1MB，超过后丢弃帧并依赖重传（go-back-N 流控），属预期行为，不影响正确性。

安全类问题 ​

中继模式数据安全吗？ ​

中继通道为明文中转（数据经过你的信令服务器）。需要机密性时：

  • 优先使用打洞直连 + --key
  • 或自行在信令服务器前部署加密隧道（如 WireGuard）

房间号会被别人猜中吗？ ​

房间号主体为 6 位十六进制（约 1600 万组合）+ 12 小时 TTL，暴力扫描需在短时间访问服务器 1600 万次——低风险但非零。需要更高安全时：

  • 使用长前缀自定义房间号，如 frp-sh game create --prefix my-long-room-2024
  • 配合 --key 加密（即使房间号泄露，无口令也无法解密）

其他 ​

双方在同一 WiFi 下，怎么做到局域网直连？ ​

无需任何操作——自动的。房主创建房间时会通告自己的局域网地址，访客加入时同时向 「公网地址 + 局域网地址」打洞。同网段时几秒内即输出 本地局域网直连 (LAN direct)， 流量完全在局域网内，不经服务器，延迟最低（适合联机游戏）。

访客能访问房主局域网里的其他设备吗（NAS/打印机）？ ​

可以。双方用 --tun 虚拟网卡模式：房主自动通告局域网子网（如 192.168.1.0/24） 并开启 IPv4 转发，访客自动添加经虚拟网卡的路由，之后即可直接 ping / 访问房主 局域网内的设备（需双方 root/管理员权限）。若双方在同一网段，该子网会被自动跳过 以避免路由冲突。

为什么默认端口是 25565？是 Minecraft 的吗？ ​

是的，25565 正是 Minecraft（Java 版）的默认服务器端口。frp-sh 最初面向「和朋友联机开黑」场景，因此把房主服务与访客监听的默认端口都定为 25565，开服党开箱即用。

完全可以用任意端口：房主 --service 指定你的服务地址，访客 --listen 指定本地监听端口。例如跑一个 3000 端口的 Web 服务：

bash
frp-sh game create --service 127.0.0.1:3000
frp-sh game join game-a3f9c2 --listen 127.0.0.1:3000

invalid room id 校验规则 ​

房间号格式为 前缀-6位hex（如 game-a3f9c2）。--prefix 仅保留小写字母数字与 -_，最长 16 字符。

会话怎么结束？ ​

默认断线自动重连（退避间隔 2s 起，上限 15s），不会因链路抖动结束。真正结束的途径：

  • 房主/访客 Ctrl-C（房主退出会删除房间）
  • 房间过期或被删除（双方自动结束）
  • --max-conns 用尽后本轮会话结束，随即自动重连等待下一轮

支持 IPv6 吗？ ​

信令、中继、打洞均使用标准 SocketAddr，支持 IPv6 地址（配置中写 [::1]:8080 形式）。打洞与 NAT 行为以实际网络环境为准。

可以在 Docker 里跑吗？ ​

可以。静态二进制可直接放入镜像：

dockerfile
FROM ubuntu:24.04
COPY frp-sh /usr/local/bin/frp-sh
EXPOSE 8080/tcp 8080/udp 8081/tcp
CMD ["frp-sh", "serve", "--addr", "0.0.0.0:8080", "--relay-addr", "0.0.0.0:8081"]

反馈 ​

遇到文档未覆盖的问题，附上 frp-sh --verbose 的输出与网络环境描述反馈。

frp-sh · 社交化 P2P 打洞工具

MIT License