命令参考
所有命令均支持 --help 查看完整说明。全局参数放在子命令之前。
全局参数
| 参数 | 说明 |
|---|---|
-c, --config <FILE> | 配置文件路径（TOML），见配置文件 |
-v, --verbose | 输出调试日志（RUST_LOG=debug 级别，含帧级追踪） |
bash
frp-sh --config config/server.toml --verbose game createfrp-sh serve —— 启动信令服务器
bash
frp-sh serve [--addr <地址>] [--relay-addr <地址>]| 参数 | 默认值 | 说明 |
|---|---|---|
--addr | 0.0.0.0:8080 | HTTP REST + UDP 公网探测监听地址 |
--relay-addr | 0.0.0.0:8081 | TCP 中继监听地址 |
Ctrl-C 优雅退出。
frp-sh game create —— 房主创建房间
bash
frp-sh game create [选项]| 参数 | 默认值 | 说明 |
|---|---|---|
-p, --prefix | game | 房间前缀（房间号 = 前缀-6位hex） |
-t, --ttl <秒> | 43200 (12h) | 房间有效时长，过期后自动失效 |
--service <地址> | 127.0.0.1:25565 | 房主本地服务地址，隧道打通后向其转发（25565 是 Minecraft 默认端口，可改成任意端口） |
--relay | 关 | 跳过打洞，直接使用中继 |
--key <口令> | 无 | 端到端加密口令（双方一致才可通信） |
--max-conns <N> | 0 (无限) | 会话内最多接受的连接数 |
--spread <N> | 2 | 打洞端口散布范围（±N 端口） |
--tun | 关 | 虚拟网卡模式（建立二层隧道，对端可直连你的虚拟 IP） |
--tun-ip <IP> | 10.66.0.1 | 虚拟网卡 IP（同一网段内的稳定地址） |
--tun-netmask <掩码> | 255.255.255.0 | 虚拟网卡掩码 |
--tun-mtu <N> | 1400 | 虚拟网卡 MTU |
示例：
bash
# 最小命令
frp-sh game create
# 完整示例：加密 + 限 5 个连接 + 打洞散布 ±3
frp-sh game create --service 127.0.0.1:25565 --key mypass --max-conns 5 --spread 3
# 虚拟网卡模式（朋友可 ping 10.66.0.1 直连）
frp-sh game create --tunfrp-sh game join <room_id> —— 访客加入房间
bash
frp-sh game join <房间号> [选项]| 参数 | 默认值 | 说明 |
|---|---|---|
room_id | （必填） | 房间号，如 game-a3f9c2；格式校验 前缀-6位hex |
-r, --relay | 关 | 强制中继模式（跳过打洞） |
--listen <地址> | 127.0.0.1:25565 | 访客本地监听地址，玩家连接此端口（25565 是 Minecraft 默认端口，可改成任意端口） |
--key <口令> | 无 | 与房主一致的加密口令 |
--max-conns <N> | 0 (无限) | 会话内最多建立的连接数 |
--spread <N> | 2 | 打洞端口散布范围 |
--tun | 关 | 虚拟网卡模式（默认 IP 由你的设备 ID 稳定派生，如 10.66.0.42） |
--tun-ip <IP> | 自动派生 | 自定义虚拟网卡 IP（须与房主同网段） |
--tun-netmask <掩码> | 255.255.255.0 | 虚拟网卡掩码 |
--tun-mtu <N> | 1400 | 虚拟网卡 MTU |
示例：
bash
frp-sh game join game-a3f9c2
frp-sh game join game-a3f9c2 --listen 127.0.0.1:30000 --key mypass
frp-sh game join game-a3f9c2 --relay # 强制走中继会话输出含义
| 输出 | 含义 |
|---|---|
Room created : game-a3f9c2 | 房主房间创建成功 |
Your ID : <uuid> | 你的设备唯一 ID（存于 %APPDATA%\frp-sh\identity，用于派生稳定的虚拟 IP） |
LAN addrs : 192.168.1.5:51234 | 房主局域网地址（同局域网访客将直连此地址） |
LAN subnets : 192.168.1.0/24 | 房主局域网子网（--tun 时访客可访问整个局域网） |
Vnet IP : 10.66.0.x | 你的虚拟网卡 IP（朋友可长期用此 IP 直连） |
>>> 本地局域网直连 (LAN direct) with <addr> | 同 WiFi/局域网直连成功（不经服务器，延迟最低） |
>>> P2P direct link established with <addr> | 公网打洞成功，P2P 直连 |
>>> UDP hole punching failed, falling back to relay ... | 打洞失败，转入中继 |
>>> late P2P link established with <addr> | 中继等待期间补抓到直连，已切回 P2P |
connection N from <addr> | 访客侧：本地新连接进入隧道 |
guest connection N, dialing local service ... | 房主侧：收到访客连接，拨号本地服务 |
connection N closed | 一条隧道连接正常结束 |
max connections (N) reached, ending session | 达到 --max-conns，会话结束 |
session ended by peer | 对端关闭了会话 |
>>> 连接已断开，N 秒后自动重连... | 链路断开，退避等待后自动重连（2s, 4s, 8s... 上限 15s） |
本地网络拓扑支持
同局域网自动直连：房主创建房间时自动通告本机所有局域网地址，访客加入时向 「公网地址 + 局域网地址」同时打洞。双方在同一 WiFi/网线时秒级建立局域网直连 （输出 LAN direct），完全不经服务器；不在同一局域网时自动走公网打洞，打洞 失败再回退中继。
访客访问房主整个局域网（--tun）：房主在房间中通告自己的局域网子网 （如 192.168.1.0/24），访客 --tun 模式下自动为这些子网添加经虚拟网卡的路由， 即可直接访问房主局域网内的其他设备（NAS、打印机、其他电脑）：
bash
# 房主（需 root/管理员，自动开启 IPv4 转发）
frp-sh game create --tun
# → LAN subnets : 192.168.1.0/24
# 访客（需 root/管理员，自动添加路由）
frp-sh game join game-a3f9c2 --tun
# → 路由 192.168.1.0/24 → frp1 已添加
# 之后可 ping / 访问房主局域网内设备注意事项：
- 需要 root/管理员权限（改路由、开转发）
- 若访客本机与房主在同一网段（如双方都是 192.168.1.0/24），该子网会被自动跳过 以避免路由冲突（输出会提示
跳过与本地同网段的房主子网） - 访问的是房主当前所在的局域网；房主换网络后重新 create 即可刷新
退出方式
- 自动重连：断线（网络抖动、NAT 映射过期、服务重启）后自动重连，无需手动操作
- 房主：
Ctrl-C结束会话并自动删除房间；房间过期后自动结束 - 访客：
Ctrl-C结束会话；房间被删除/过期后自动结束
常见错误
| 错误 | 原因与解决 |
|---|---|
invalid room id: xxx | 房间号格式不对（需 前缀-6位hex） |
room not found or expired: xxx | 房间不存在/已过期；让房主重新 create |
UDP echo timed out | 服务器 8080/udp 未放行，或配置地址不对 |
decryption failed (wrong --key?) | 双方 --key 不一致 |
relay rejected: ERROR ROOM_EXPIRED | 房间过期后中继被拒 |
cannot reach local service xxx | 房主本地服务未启动或地址错误 |