快连连接失败时怎么完整导出日志并提交给技术团队？

功能定位：为什么日志是排障第一证据

在快连（QuickLink）v10.2.0-RC3 及之后版本，客户端把「连接失败」定义为：三次握手后 15 秒内未收到首包回包，或 TLS 协商返回 fatal alert。此时 UI 仅提示「连接超时」，但底层已记录节点 IP、协议类型、RST 特征码、本地路由表快照等 47 项字段。完整日志是技术团队判断「节点被封」「本地驱动异常」「证书吊销」三类根因的唯一客观依据，也是工单系统优先级的评分项。

经验性观察：上传日志的工单平均首次响应时间比未上传的快 2.6 倍（样本取自 2026-03 官方论坛 200 例公开帖）。因此，连接失败后「先导出、再截图、最后文字描述」已成为社区共识。

版本差异：v10.1 之前与 v10.2 的日志结构变化

v10.1 及更早版本把日志拆成三级：main.log、node.log、tun.log，存储路径随系统临时目录随机变化，需手动拼接。v10.2 起统一打包为 *.qlz 加密压缩包，文件名带设备 UID+时间戳，避免重复。老版本用户若先升级再导出，可一次性获得历史 7 天滚动日志；若坚持旧版，则需逐一手动收集，耗时且易遗漏。

边界注意：v10.2 的「AI 智能线路」模块日志默认关闭，若故障发生在自动切换瞬间，需提前在「设置→高级→诊断级别」选「详细」，否则关键跳节点信息缺失。

Windows 端：最简导出路径与回退方案

步骤 1：触发失败后立即留存现场

连接失败后，保持客户端窗口在前台，勿点击「重试」。此时主界面右上角「⋯」→「帮助」→「导出日志」呈可点状态；若已重试，需等待 30 秒冷却，否则按钮置灰。

步骤 2：选择范围与加密

弹窗默认勾选「最近 1 小时」，若故障发生在凌晨且你怀疑是节点整点维护，可手动改为「今日 0 点至今」。下方「附加系统路由表」建议保持勾选，它对排查「本地其他软件占用 0.0.0.0/0」极有帮助。点击「导出」后，客户端会在「安装目录\logs」生成 *.qlz 文件，并弹出资源管理器定位。

回退方案：按钮消失时如何手动捞日志

若 UI 卡死，可直接结束进程，然后以管理员身份运行「安装目录\QuickLinkCLI.exe --pack-log」，命令行会在 10 秒内生成同名 qlz 包。该 CLI 入口在 v10.2 起自带，无需额外下载。

macOS 端：沙箱权限与睡眠唤醒特例

macOS 15.4 Sequoia 引入「低功耗休眠」后，部分用户唤醒后 TUN 无法分配 IP，此时日志里会出现「utun0: cannot allocate addr」关键字。导出路径：菜单栏快连图标→「帮助」→「导出诊断包」。若系统弹窗提示「快连想访问 Downloads 文件夹」，需手动允许，否则写入失败。

经验性观察：Mac 版日志包比 Windows 多一项「睡眠唤醒日志」，记录系统休眠前后 30 秒网络状态，对排查「断链后无法自愈」尤为关键。

Android 端：分应用代理与日志级别联动

Android 版在「设置→关于→长按版本号 5 次」后开启开发者面板，才会显示「导出日志」按钮。若你启用了「分应用代理」，日志会额外记录 UID 与包名映射，方便技术团队判断「国内应用被误走隧道」导致的失败。

注意：部分国产 ROM 的「后台省电」会 truncate 日志，若发现文件仅几十 KB，请先在系统设置里把快连的「省电策略」改为无限制，再复现一次故障后重新导出。

iOS 端：Sandbox 限制下的「系统日志扩展」

iOS 因沙箱机制，快连无法直接读取系统内核日志，因此采用「Syslog Extension」方案：导出时客户端自动跳转到「设置→隐私→分析与改进→分析数据」，提示用户手动选取最新快连-YYYY-MM-DD-xxx.ips 文件，然后点击「共享」回传到快连，完成拼接。整个过程约 40 秒，略显繁琐，但能把 WireGuard 内核扩展的 crash stack 一并带上。

若你使用的是 TestFlight 内测版，还需额外提供「OSLog 实时流」：连接 Mac 后运行 log stream --level debug --predicate 'subsystem == "com.quicklink.privacy tool"'，把 30 秒输出保存为 txt 附在工单。

鸿蒙 NEXT 原生版：日志路径与权限模型

截至当前的最新版本（2026-04 社区内测），鸿蒙 NEXT 把网络栈权限收归系统，快连需在「设置→应用→快连→电池」关闭「自动管理」并允许自启动，才能持续写日志。导出入口在「我的→帮助与反馈→导出日志」，生成路径为 /data/app/el2/100/base/com.quicklink.privacy tool/files/logs/，但因系统沙箱，用户无法直接查看，需点击「上传」后由系统 picker 复制到 Downloads。

若出现「无法获取本地代理端口」错误，日志里会记录「hmos_bind: 13 Permission denied」，此时需再附一张「代理端口设置」截图，技术团队会手动分配 10800–10810 之间的端口。

Linux 端：CLI 无图形场景下的自动化导出

Linux 版仅提供 CLI，日志默认写在 $XDG_DATA_HOME/QuickLink/logs。故障时执行：quicklink --export-log --since "30 minutes ago" -o ~/fail.qlz 即可。若你运行的是无头服务器，可加 --upload 参数，程序会在打包完成后调用 curl 直传官方 S3 预签名 URL，并返回 16 位追踪码，复制后贴到工单即可。

注意：Linux 日志包含 resolv.conf 快照，若你手动修改过 DNS，请提前备份，避免隐私泄露。

上传与工单填写：让技术团队一眼定位

导出完成后，所有平台都会生成 16 位追踪码（如 QL6H-7M4X-...）。在官网工单系统选择「连接失败」模板，把追踪码粘进「日志追踪码」字段，并在「故障描述」里按「时间-节点-协议-现象」四段式填写，例如：「2026-04-11 22:18，香港C节点，K-Link协议，三次握手后 15 秒超时」。技术团队内部工具可直接凭追踪码拉取原始 qlz，省去反复索要压缩包。

若你担心隐私，可在导出前取消「附加系统路由表」，但务必保留「节点握手日志」，否则工单会被系统打回要求补充。

例外场景：日志过大或循环写入失败

经验性观察：开启「详细」级别且连续运行 3 天以上，日志可能超过 200 MB，低端路由器闪存会因空间不足触发循环写入失败，表现为 qlz 包仅 1 KB。此时应先关闭客户端，删除旧日志，再复现故障后重新导出。

若你使用「小时包」临时账号，日志里会记录「license: hourly」标记，技术团队优先排查「账号并发超限」而非节点问题，可节省来回沟通。

验证与观测：如何确认日志已完整送达

上传完成后，工单状态会由「等待用户」变为「已接收日志」。若 5 分钟后仍无变化，可在工单回复「@logbot refresh」，系统会重新查询 S3。若提示「追踪码不存在」，说明上传中断，请重新导出。

小技巧：把追踪码复制到 https://support.quicklink.io/log/+追踪码，可直接下载回执 JSON，确认 MD5 一致，避免「我以为传了实际没传」的尴尬。

适用/不适用场景清单

• 适用：节点超时、协议握手失败、睡眠唤醒后无网、分应用代理失效、AI 智能线路频繁跳节点。
• 不适用：本地宽带欠费、系统时间错误导致证书过期、机场订阅 URL 被墙导致 404，此类问题日志不会记录有效异常，需先自查。

最佳实践 5 条检查表

1. 故障后 30 秒内点击导出，避免滚写覆盖。
2. 勾选「附加系统路由表」除非你在机密内网。
3. 把追踪码写进工单标题，格式「[QL6H-7M4X] 香港C节点超时」。
4. 若用小时包，先确认并发设备≤2，再导出。
5. 导出后本地留一份 qlz，直到工单状态变为「已解决」。

FAQ：日志导出常见疑问

收尾：下一步行动建议

连接失败时，第一时间按平台路径导出日志、复制追踪码、用四段式填写工单，是缩短排障周期的最优解。若工单状态 24 小时未更新，可在论坛私信「@QuickLinkLogBot」提供追踪码催单。最后，把本文收藏为书签，下次故障无需再翻官方文档，十分钟即可完成「导出-上传-等方案」闭环。