From 3e4d5861aaf03f81620f64471aaa9aa7b0400336 Mon Sep 17 00:00:00 2001 From: zhy200308 <2258391712@qq.com> Date: Tue, 11 Aug 2026 17:39:53 +0800 Subject: [PATCH] =?UTF-8?q?fix(desktop):=20=E8=BF=9E=E6=8E=A5=E5=A4=B1?= =?UTF-8?q?=E8=B4=A5=E7=BB=99=E5=87=BA=E5=8F=AF=E6=89=A7=E8=A1=8C=E7=9A=84?= =?UTF-8?q?=E6=8E=92=E6=9F=A5=E6=96=B9=E5=90=91=EF=BC=8C=E5=B9=B6=E5=88=86?= =?UTF-8?q?=E7=A6=BB=E9=85=8D=E5=AF=B9=E4=B8=8E=E4=BC=A0=E8=BE=93=E7=8A=B6?= =?UTF-8?q?=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 实测中出现「连接码解析正确但连不上」。诊断结果不是代码问题:两台机器 同在 192.168.8.0/24,ARP 能解析对方 MAC(二层通),但 ICMP 100% 丢包、 TCP 39393 连接超时——典型的对端主机丢包,即 Windows 防火墙拦截入站。 顺带暴露的连带影响:二进制从 qft-windows.exe 改名为 qft-desktop.exe 后, 此前给旧名字放行的防火墙规则对新程序不生效,用户不会想到这一层。 README 已补充放行步骤与排查顺序。 代码侧的三个真实缺陷 1. 连接失败只说「失败」,等于什么都没说。现按 io::ErrorKind 分类: - TimedOut → 包发出去没回应:防火墙 / AP 客户端隔离 / 对方已关闭 - ConnectionRefused → 主机在线但端口没人监听:对方没点「启动接收」 - Host/NetworkUnreachable → 本机没有到该地址的路由 三者成因完全不同,给的建议也必须不同。 2. 配对超时从 10 秒缩到 4 秒。配对只是一次极小的请求,拖到 10 秒 只会让用户以为程序卡死。 3. 配对阶段就显示「正在发送 0%」。此前用 busy 兼作「正在传输」, 导致刚点连接就出现发送进度条。新增独立的 transferring 标志, 进度块只在真正推送文件时出现;配对期间改为显示 spinner 与 「正在建立连接…最多等 4 秒」。 验证:cargo test 32/32。新增两项针对错误分类的用例—— 用 RFC 5737 文档网段 192.0.2.1 触发超时路径,用刚释放的本地端口 触发拒绝路径,分别断言提示里包含对应的排查方向。 --- README.md | 18 +++++++++++++ desktop/src/client.rs | 63 +++++++++++++++++++++++++++++++++++++++++-- desktop/src/main.rs | 16 +++++++++-- 3 files changed, 93 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4ace74f..279d551 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,24 @@ v0.4.7 提供两套互不依赖的传输方式: ## v0.5-m1:电脑 ↔ 电脑互传(新增) +### Windows 首次运行必须放行防火墙 + +二进制已从 `qft-windows.exe` 改名为 `qft-desktop.exe`,**此前给旧名字放行的 +防火墙规则对新程序不生效**,接收方会表现为「对方能解析连接码但连不上」。 + +管理员 PowerShell: + +```powershell +New-NetFirewallRule -DisplayName "QFT Desktop" -Direction Inbound ` + -Program "<完整路径>\qft-desktop.exe" -Action Allow -Profile Private,Domain +``` + +或在「允许应用通过 Windows Defender 防火墙」里勾选 `qft-desktop.exe` 的**专用网络**。 + +排查顺序:对端 `ping` 不通且 TCP 端口连不上,但 `arp -a` 能看到对方 MAC, +基本可以判定是对端主机在丢包(防火墙),而不是网络不通。 + + 桌面端目录从 `windows/` 改名为 `desktop/`,crate 更名 `qft-desktop`, **现已可在 macOS / Linux / Windows 三平台编译运行**。平台差异全部收敛在 `desktop/src/platform.rs`(配置目录、下载目录、设备名、Direct AP 能力), diff --git a/desktop/src/client.rs b/desktop/src/client.rs index 3c36217..8eb8dfd 100644 --- a/desktop/src/client.rs +++ b/desktop/src/client.rs @@ -111,7 +111,9 @@ impl PeerClient { "/qft/pair", &headers[..2], Some(&[]), - Duration::from_secs(10), + // 配对只是一次极小的请求,4 秒还没建连基本就是不通了。 + // 拖到 10 秒只会让用户以为程序卡死。 + Duration::from_secs(4), )?; let body = response.read_body()?; let value: serde_json::Value = serde_json::from_slice(&body).unwrap_or(serde_json::Value::Null); @@ -402,6 +404,33 @@ fn platform_ensure_dir(path: &Path) -> Result<()> { .with_context(|| format!("创建目录 {} 失败", path.display())) } +/// 把底层 io 错误翻译成能指导下一步的说法。 +/// +/// 「超时」和「被拒绝」的成因完全不同:前者是包被丢了(防火墙、主机不可达、 +/// AP 客户端隔离),后者是端口上没人监听(对方没点"启动接收")。 +/// 给用户一句笼统的"连接失败"等于什么都没说。 +fn describe_connect_failure(address: SocketAddr, error: &std::io::Error) -> anyhow::Error { + use std::io::ErrorKind; + let ip = address.ip(); + match error.kind() { + ErrorKind::TimedOut => anyhow::anyhow!( + "连接 {address} 超时:数据包发出去了但没有任何回应。\n\ + 常见原因:① 对方电脑的防火墙拦截了入站连接(Windows 上需要放行 qft-desktop.exe 的专用网络);\ + ② Wi-Fi 开了客户端隔离,同网段设备之间不能互通;\ + ③ 对方已经关掉接收或换了网络。" + ), + ErrorKind::ConnectionRefused => anyhow::anyhow!( + "{ip} 明确拒绝了连接:主机在线,但 {} 端口上没有程序在监听。\n\ + 请确认对方已经在「我要接收」里点了「启动接收」,并且连接码是最新的那一串。", + address.port() + ), + ErrorKind::HostUnreachable | ErrorKind::NetworkUnreachable => anyhow::anyhow!( + "路由不可达:本机没有能到达 {ip} 的路由。请确认两台设备连在同一个网络里。" + ), + _ => anyhow::anyhow!("连接 {address} 失败:{error}"), + } +} + // ---------------------------------------------------------------- 极简 HTTP 客户端 struct HttpResponse { @@ -437,7 +466,7 @@ fn send_request( timeout: Duration, ) -> Result { let stream = TcpStream::connect_timeout(&address, timeout.min(Duration::from_secs(10))) - .with_context(|| format!("连接 {address} 失败"))?; + .map_err(|e| describe_connect_failure(address, &e))?; stream.set_nodelay(true).ok(); stream.set_read_timeout(Some(timeout))?; stream.set_write_timeout(Some(timeout))?; @@ -582,3 +611,33 @@ mod integration_tests { let _ = std::fs::remove_dir_all(&root); } } + +#[cfg(test)] +mod failure_message_tests { + use super::*; + + /// 不可达地址必须给出「超时」类的排查建议,而不是一句空洞的失败。 + #[test] + fn unreachable_host_yields_actionable_timeout_message() { + // 192.0.2.0/24 是 RFC 5737 保留的文档用网段,不会有真实主机应答 + let error = PeerClient::pair("http://192.0.2.1:39393", "abcdef", "tester") + .expect_err("不可达地址必须失败"); + let text = format!("{error:#}"); + assert!(text.contains("防火墙") || text.contains("超时") || text.contains("路由"), + "应给出可执行的排查方向,实得:{text}"); + } + + /// 本机没人监听的端口会被内核直接拒绝,提示必须与"超时"区分开。 + #[test] + fn refused_port_says_receiver_not_started() { + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let port = listener.local_addr().unwrap().port(); + drop(listener); // 端口随即空出,连接会被拒绝 + + let error = PeerClient::pair(&format!("http://127.0.0.1:{port}"), "abcdef", "tester") + .expect_err("空端口必须失败"); + let text = format!("{error:#}"); + assert!(text.contains("启动接收") || text.contains("拒绝"), + "被拒绝时应提示对方没启动接收,实得:{text}"); + } +} diff --git a/desktop/src/main.rs b/desktop/src/main.rs index b815d1f..eae0b2e 100644 --- a/desktop/src/main.rs +++ b/desktop/src/main.rs @@ -136,6 +136,9 @@ struct PcPeerState { // 后台事件 events: Option>, busy: bool, + /// 仅在真正开始推送文件后为真。此前用 busy 兼作此用, + /// 导致配对阶段就显示「正在发送 0%」,误导用户以为传输已经开始。 + transferring: bool, current_file: String, done: u64, total: u64, @@ -228,6 +231,7 @@ impl QftApp { files: Vec::new(), events: None, busy: false, + transferring: false, current_file: String::new(), done: 0, total: 0, @@ -985,6 +989,7 @@ impl QftApp { self.receive.events = None; self.pc.events = None; self.pc.busy = false; + self.pc.transferring = false; self.pc.token = None; self.pc.connected_base = None; } @@ -1003,6 +1008,7 @@ impl QftApp { }); ui.add_space(10.0); ui.label(egui::RichText::new(&self.pc.status).weak()); + // 失败原因常常是多行的排查建议,需要完整展示而不是被截断 ui.add_space(10.0); match self.pc.mode { @@ -1116,7 +1122,10 @@ impl QftApp { { self.pair_pc_peer(); } - if self.pc.token.is_some() { + if self.pc.busy { + ui.spinner(); + ui.weak("正在建立连接…最多等 4 秒"); + } else if self.pc.token.is_some() { ui.colored_label(egui::Color32::from_rgb(80, 200, 120), "● 已连接"); } }); @@ -1171,7 +1180,7 @@ impl QftApp { ui.label(format!("• {} {}", file.display(), human_bytes(size))); } - if self.pc.busy || self.pc.total > 0 { + if self.pc.transferring || self.pc.total > 0 { ui.add_space(8.0); ui.label(format!("正在发送:{}", self.pc.current_file)); let fraction = if self.pc.total == 0 { 0.0 } @@ -1247,6 +1256,7 @@ impl QftApp { let (tx, rx) = mpsc::channel(); self.pc.events = Some(rx); self.pc.busy = true; + self.pc.transferring = true; self.pc.done = 0; self.pc.total = total; self.pc.started = Some(Instant::now()); @@ -1316,11 +1326,13 @@ impl QftApp { } PcEvent::AllDone => { self.pc.busy = false; + self.pc.transferring = false; self.pc.current_file.clear(); self.pc.status = "全部发送完成。".into(); } PcEvent::Failed(message) => { self.pc.busy = false; + self.pc.transferring = false; self.pc.status = message; } }