fix(desktop): 连接失败给出可执行的排查方向,并分离配对与传输状态
实测中出现「连接码解析正确但连不上」。诊断结果不是代码问题:两台机器 同在 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 触发超时路径,用刚释放的本地端口 触发拒绝路径,分别断言提示里包含对应的排查方向。
This commit is contained in:
@@ -18,6 +18,24 @@ v0.4.7 提供两套互不依赖的传输方式:
|
|||||||
|
|
||||||
## v0.5-m1:电脑 ↔ 电脑互传(新增)
|
## 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`,
|
桌面端目录从 `windows/` 改名为 `desktop/`,crate 更名 `qft-desktop`,
|
||||||
**现已可在 macOS / Linux / Windows 三平台编译运行**。平台差异全部收敛在
|
**现已可在 macOS / Linux / Windows 三平台编译运行**。平台差异全部收敛在
|
||||||
`desktop/src/platform.rs`(配置目录、下载目录、设备名、Direct AP 能力),
|
`desktop/src/platform.rs`(配置目录、下载目录、设备名、Direct AP 能力),
|
||||||
|
|||||||
+61
-2
@@ -111,7 +111,9 @@ impl PeerClient {
|
|||||||
"/qft/pair",
|
"/qft/pair",
|
||||||
&headers[..2],
|
&headers[..2],
|
||||||
Some(&[]),
|
Some(&[]),
|
||||||
Duration::from_secs(10),
|
// 配对只是一次极小的请求,4 秒还没建连基本就是不通了。
|
||||||
|
// 拖到 10 秒只会让用户以为程序卡死。
|
||||||
|
Duration::from_secs(4),
|
||||||
)?;
|
)?;
|
||||||
let body = response.read_body()?;
|
let body = response.read_body()?;
|
||||||
let value: serde_json::Value = serde_json::from_slice(&body).unwrap_or(serde_json::Value::Null);
|
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()))
|
.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 客户端
|
// ---------------------------------------------------------------- 极简 HTTP 客户端
|
||||||
|
|
||||||
struct HttpResponse {
|
struct HttpResponse {
|
||||||
@@ -437,7 +466,7 @@ fn send_request(
|
|||||||
timeout: Duration,
|
timeout: Duration,
|
||||||
) -> Result<HttpResponse> {
|
) -> Result<HttpResponse> {
|
||||||
let stream = TcpStream::connect_timeout(&address, timeout.min(Duration::from_secs(10)))
|
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_nodelay(true).ok();
|
||||||
stream.set_read_timeout(Some(timeout))?;
|
stream.set_read_timeout(Some(timeout))?;
|
||||||
stream.set_write_timeout(Some(timeout))?;
|
stream.set_write_timeout(Some(timeout))?;
|
||||||
@@ -582,3 +611,33 @@ mod integration_tests {
|
|||||||
let _ = std::fs::remove_dir_all(&root);
|
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}");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
+14
-2
@@ -136,6 +136,9 @@ struct PcPeerState {
|
|||||||
// 后台事件
|
// 后台事件
|
||||||
events: Option<mpsc::Receiver<PcEvent>>,
|
events: Option<mpsc::Receiver<PcEvent>>,
|
||||||
busy: bool,
|
busy: bool,
|
||||||
|
/// 仅在真正开始推送文件后为真。此前用 busy 兼作此用,
|
||||||
|
/// 导致配对阶段就显示「正在发送 0%」,误导用户以为传输已经开始。
|
||||||
|
transferring: bool,
|
||||||
current_file: String,
|
current_file: String,
|
||||||
done: u64,
|
done: u64,
|
||||||
total: u64,
|
total: u64,
|
||||||
@@ -228,6 +231,7 @@ impl QftApp {
|
|||||||
files: Vec::new(),
|
files: Vec::new(),
|
||||||
events: None,
|
events: None,
|
||||||
busy: false,
|
busy: false,
|
||||||
|
transferring: false,
|
||||||
current_file: String::new(),
|
current_file: String::new(),
|
||||||
done: 0,
|
done: 0,
|
||||||
total: 0,
|
total: 0,
|
||||||
@@ -985,6 +989,7 @@ impl QftApp {
|
|||||||
self.receive.events = None;
|
self.receive.events = None;
|
||||||
self.pc.events = None;
|
self.pc.events = None;
|
||||||
self.pc.busy = false;
|
self.pc.busy = false;
|
||||||
|
self.pc.transferring = false;
|
||||||
self.pc.token = None;
|
self.pc.token = None;
|
||||||
self.pc.connected_base = None;
|
self.pc.connected_base = None;
|
||||||
}
|
}
|
||||||
@@ -1003,6 +1008,7 @@ impl QftApp {
|
|||||||
});
|
});
|
||||||
ui.add_space(10.0);
|
ui.add_space(10.0);
|
||||||
ui.label(egui::RichText::new(&self.pc.status).weak());
|
ui.label(egui::RichText::new(&self.pc.status).weak());
|
||||||
|
// 失败原因常常是多行的排查建议,需要完整展示而不是被截断
|
||||||
ui.add_space(10.0);
|
ui.add_space(10.0);
|
||||||
|
|
||||||
match self.pc.mode {
|
match self.pc.mode {
|
||||||
@@ -1116,7 +1122,10 @@ impl QftApp {
|
|||||||
{
|
{
|
||||||
self.pair_pc_peer();
|
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), "● 已连接");
|
ui.colored_label(egui::Color32::from_rgb(80, 200, 120), "● 已连接");
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
@@ -1171,7 +1180,7 @@ impl QftApp {
|
|||||||
ui.label(format!("• {} {}", file.display(), human_bytes(size)));
|
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.add_space(8.0);
|
||||||
ui.label(format!("正在发送:{}", self.pc.current_file));
|
ui.label(format!("正在发送:{}", self.pc.current_file));
|
||||||
let fraction = if self.pc.total == 0 { 0.0 }
|
let fraction = if self.pc.total == 0 { 0.0 }
|
||||||
@@ -1247,6 +1256,7 @@ impl QftApp {
|
|||||||
let (tx, rx) = mpsc::channel();
|
let (tx, rx) = mpsc::channel();
|
||||||
self.pc.events = Some(rx);
|
self.pc.events = Some(rx);
|
||||||
self.pc.busy = true;
|
self.pc.busy = true;
|
||||||
|
self.pc.transferring = true;
|
||||||
self.pc.done = 0;
|
self.pc.done = 0;
|
||||||
self.pc.total = total;
|
self.pc.total = total;
|
||||||
self.pc.started = Some(Instant::now());
|
self.pc.started = Some(Instant::now());
|
||||||
@@ -1316,11 +1326,13 @@ impl QftApp {
|
|||||||
}
|
}
|
||||||
PcEvent::AllDone => {
|
PcEvent::AllDone => {
|
||||||
self.pc.busy = false;
|
self.pc.busy = false;
|
||||||
|
self.pc.transferring = false;
|
||||||
self.pc.current_file.clear();
|
self.pc.current_file.clear();
|
||||||
self.pc.status = "全部发送完成。".into();
|
self.pc.status = "全部发送完成。".into();
|
||||||
}
|
}
|
||||||
PcEvent::Failed(message) => {
|
PcEvent::Failed(message) => {
|
||||||
self.pc.busy = false;
|
self.pc.busy = false;
|
||||||
|
self.pc.transferring = false;
|
||||||
self.pc.status = message;
|
self.pc.status = message;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user