无法连接？先看日志自查

功能定位：为什么先看日志

当连锁门店 POS 突然掉线或远程桌面卡顿，先翻日志往往比反复重连更快。快连 v8.4 把「连接轨迹」「AI 选路决策」「卫星切换事件」全部写进本地日志，等于把黑盒拆开给你看：延迟突增是出口被 QoS，还是边缘节点被屏蔽，一行时间戳就能对齐。

与竞品不同，快连日志采用明文 JSON+GZIP 双格式，既可直接 grep，也能丢进 Splunk/Grafana，无需额外解析器。官方在 2025-11 公告中明确：「个人版保留 7 天，企业版 90 天，不支持远程云端拉取」，这意味着你必须在本地及时导出，否则过期即焚。

操作路径：三平台最短入口

Windows / macOS（桌面端 v8.4）

主界面右上角「⋯」→ 诊断 → 导出日志 → 选择「近 3 次会话」或「近 24 h」。
文件默认落在 ~/Downloads/Kuailian_logs_[timestamp].zip，含 kuailian.log、wireguard.log、routing_decision.json 三件套。
若「导出」按钮灰显，先点「停止连接」释放写锁，再重试；这是 8.4 已知缺陷，官方说 8.4.2 修。

导出完成后建议立即复制一份到非系统盘，防止系统清理工具误删；若需长期归档，可把 zip 重命名为「故障现象+日期」格式，方便后续检索。

Android / iOS（移动端 v8.4）

我的 → 设置 → 高级 → 日志 → 生成报告 → 等待 100% → 分享面板选「保存到文件」。
Android 15 若被杀后台，需提前把快连加入「电池无限制」白名单，否则日志会在 60% 断。
iOS18 以上若提示「日志过大」，系统会分卷，记得把 .1.zip 与 .2.zip 一并收走，缺失任一卷都会导致 JSON 截断。

经验性观察：移动端日志包平均 3-8 MB，若超过 20 MB，大概率包含完整抓包，上传工单前可先用 zip -d *.pcap 剔除，节省带宽。

NAS 路由器 ROM 集成版

群晖 DSM 7.3 路径：套件中心 → 快连 → 右上角「日志」→ 下载。注意 ROM 版无 GUI 进度条，日志包生成在 /volume1/Kuailian/logs/，需用 admin 账号 SCP 出来；否则重启会轮转。

若路由器 eMMC 寿命告警，可先在「设置-系统-日志级别」降为 warning，减少写入量，待故障复现后再临时调高至 debug，避免过早磨损。

关键字段速查：30 秒定位故障

打开 kuailian.log，先搜最近一次 "event":"handshake_complete"，往前 30 行通常就是根因。经验性观察：若看到 "subtype":"stun_timeout" 连续 >3 次，基本可判定两端 UDP 被对称 NAT 拦住，此时应切「卫星直连」或「TCP 443 中继」。

字段	含义	阈值参考
rtt_ms	端到端 RTT	>180 ms 且抖动 >30 ms 时视频会议卡顿
loss_pct	链路丢包	>1 % 远程桌面出现半秒黑屏
p2p_success	打洞结果	false 且 relay_region=”EU2” 可能走高价节点

示例：某次远程代码编译卡顿，grep 发现 rtt_ms=740 且 loss_pct=4.3，对应时间段路由决策切换到卫星中继，立即在控制台关闭「自动 fallback」后恢复。

注意

2025-12 以后国密双证书环境下，日志会对敏感字段做脱敏，SRC_IP 只留前 24 bit，若你需要完整地址用于本地防火墙对比，需临时在「设置-隐私」里关闭「日志脱敏」，导出完再开回去，否则合规审计会报警。

场景映射：什么时候必须导出日志

连锁门店收银闪断

某便利店 40 台 POS 每晚 20:00-20:05 批量掉线。日志显示 "ai_route":"ctcc_backhaul" 每日 19:59 被强制切换到电信出口，触发 PostgreSQL 长连接 RST。解决：在「AI 流控白名单」把 5432 端口标记为「数据库高优先」，锁定链路 48 h 无复现。

工业 PLC 数采延迟抖动

边缘网关每 10 s 上报 Modbus-TCP，发现延迟从 40 ms 跳到 300 ms。日志里 "satellite_fallback":true 与地面站切换同时发生，关闭「省电 GPS」后定位漂移消失，延迟回到 45 ms。

不适用清单：日志也救不了的情况

客户端本地时间被手动调到 2024，导致证书有效期校验失败，日志里全是 "cert_not_yet_valid"，此时先校准时区再导出，否则时间戳全乱。
iOS 侧因「屏幕使用时间」把快连网络权限全关，日志空白，只能去「设置-屏幕使用时间-应用限制」里放行，日志无法记录未发生的握手。
企业控制台推送了全局「禁用日志」策略，本地按钮直接隐藏，需管理员在后台临时关闭策略，客户端重启后才能恢复导出。

经验性观察：若日志文件仅 1 KB 且无任何握手事件，优先检查本地权限与时间，而非反复重装客户端。

与第三方协同：最小权限喂给 SIEM

把日志接进 Splunk 时，只开 514/UDP 即可，千万别给写权限。官方示例字段表已把 user_id、device_sn 放最外层，方便你做 GDPR 遗忘：搜索 user_id=123 → 删除事件 → 完成数据主体请求。

示例：用 Splunk 的 rex 命令提取 rtt_ms 字段，设置告警阈值 >200 ms，10 分钟内触发 3 次即推送钉钉，平均定位时间从 2 小时压缩到 15 分钟。

验证与观测方法：确保日志可信

导出前后各跑一次 ping 1.1.1.1，把 RTT 写在日志文件名里，方便事后对照。
检查 MD5：桌面端导出完毕会生成同名的 .md5 文件，确认未被中间邮件网关二次压缩。
用 jq '.event' kuailian.log | sort | uniq -c 快速统计事件分布，若 handshake 数量远小于重连次数，说明有致命超时未落地。

补充：在 Linux 可用 date -d @1699941234 把 Unix 时间戳转成可读格式，方便与门店监控摄像头时间轴对齐。

版本差异与迁移建议

v8.3 及更早版本使用二进制 .klg 格式，需要官方工具 kl_decode.exe 转文本；升级到 v8.4 后首次启动会把旧日志自动转存为 legacy.klg，但不再更新，建议在 30 天内完成解码归档，否则后续版本会清理。

提示

企业控制台 8.4 新增「日志采样率」旋钮（10%-100%），调低可减少边缘网关 eMMC 磨损，但排障时可能抓不到关键握手。建议在非高峰调到 100%，事后调回 30%。

最佳实践清单：一次就拿到可用日志

步骤	检查点	不过则回退
1. 复现故障	确保现象出现 ≥2 次	否则日志噪声大，难对齐
2. 立即停连	点「断开」释放写锁	导出按钮灰色就重启客户端
3. 导出并 MD5	确认文件大小 >10 KB	太小说明日志被轮转，重试
4. 本地脱敏确认	SRC_IP 掩码合规	否则传 SIEM 会触发审计告警
5. 命名带时间戳	格式：YYYYMMDD_HHMMSS_症状	方便 30 天后快速检索

案例研究：两条真实链路

案例 A：小型零售 10 节点

做法：每晚 21:00 定时脚本 SCP 拉取 NAS 日志，jq 过滤 loss_pct>1 自动建 Jira。

结果：两周内发现电信出口每日 20:58 丢包突增，协调 ISP 更换城域链路后 POS 掉线率从 3% 降到 0.2%。

复盘：脚本里增加 --slurp 合并多条日志，避免切割导致事件丢失。

案例 B：跨国工厂 500 节点

做法：把日志采样率调到 100%，Splunk 侧写 rex 提取 rtt_ms，>220 ms 触发 PagerDuty。

结果：发现卫星中继每周三 02:00 例行切换，提前把批处理任务错开 30 分钟，产线停工次数归零。

复盘：跨国链路需考虑时区，告警窗口使用 UTC，避免夏令时跳变误报。

监控与回滚 Runbook

异常信号

1. handshake_complete 数量 5 分钟内下降 50%。

2. rtt_ms 均值突增 3 倍且持续 >2 分钟。

3. stun_timeout 连续 >5 次。

定位步骤

1. 立即导出日志，命名带 _alert 后缀。

2. jq 过滤 .relay_region，判断是否误入高价节点。

3. 对照本地 traceroute，确认是出口 NAT 还是骨干丢包。

回退指令

1. 控制台临时关闭「AI 选路」，手动锁定上次可用出口。

2. 若卫星异常，CLI 执行 kuailian-cli fallback off 强制地面站。

3. 观察 5 分钟，RTT 恢复后逐步开放 AI 选路。

演练清单

每季度做一次「假出口」演练：控制台把可用节点全部关掉，观察告警是否 3 分钟内触发，并验证回滚脚本能在 10 分钟内恢复。

FAQ

Q1：导出按钮一直灰色？
A：先点「断开」释放写锁，若仍灰，重启客户端即可。
背景：8.4 存在已知缺陷，8.4.2 修复。

Q2：iOS 分卷 zip 缺失其一？
A：系统拆分后必须全部收下，否则 JSON 截断无法解析。
证据：官方文档明确 iOS18 以上大于 15 MB 自动分卷。

Q3：日志里时间戳与本地差 8 小时？
A：客户端使用 UTC，分析时可用 date -d @xxx +0800 转换。
背景：统一时区避免跨国团队混淆。

Q4：NAS 日志目录为空？
A：ROM 版无 GUI 进度条，需 SCP 手动拉出，重启会轮转。
经验：拉取前先在 NAS 上 ls -lh 确认大小。

Q5：企业控制台找不到采样率旋钮？
A：仅 8.4 企业版可见，确认控制台已升级。
背景：旧版 8.3 无此功能。

Q6：日志脱敏后无法定位 IP？
A：临时关闭「日志脱敏」导出，再开回，合规窗口 30 分钟。
背景：国密双证书合规要求。

Q7：kl_decode.exe 打不开 8.4 日志？
A：8.4 已改为 JSON，无需解码，直接用 jq 即可。
背景：8.3 及更早为二进制 .klg。

Q8：splunk 解析失败？
A：确认 sourcetype 设为 _json，时间戳字段选 ts。
经验：官方提供 props.conf 样例。

Q9：日志文件 0 KB？
A：客户端被「禁用日志」策略隐藏，需管理员后台关闭策略并重启。
背景：企业策略优先级最高。

Q10：移动端日志 60% 中断？
A：Android 15 需把快连加入「电池无限制」白名单。
背景：系统杀后台导致写失败。

术语表

STUN：打洞协议，用于获取公网地址，首次出现在「stun_timeout」字段。

Relay Region：中继节点地域，如 EU2，决定计费与延迟。

AI Route：智能选路算法，日志中显示为 ai_route。

Fallback：卫星回退，日志中 satellite_fallback:true。

loss_pct：丢包百分比，阈值 1% 为视频红线。

rtt_ms：往返时延，>180 ms 卡顿感知明显。

handshake_complete：握手成功事件，定位起点。

legacy.klg：8.3 旧格式，需 kl_decode 转换。

采样率：8.4 企业旋钮，控制写入频率。

日志脱敏：国密环境下隐藏 IP 后 8 位。

写锁：连接时日志文件被占用，导出需先断开。

分卷 zip：iOS18 大文件自动拆分，需合并解析。

电池无限制：Android 15 白名单，防止后台被杀。

GMT 偏移：日志 UTC 与本地时间差，需转换。

GDPR 遗忘：按 user_id 删除日志，满足合规。

风险与边界

不可用情形：本地时间错误、策略禁用、系统杀后台。

副作用：全开采样率会加速 eMMC 磨损，边缘网关寿命可能缩短 15%。

替代方案：若日志无法导出，可临时打开 Wireshark 抓包，但需额外解析器，且无法看到 AI 选路决策。

未来趋势与版本预期

官方 2026 H1 路线图透露，8.5 版将上线「日志自动打标签」：系统根据故障模式自动附加「建议切换中继」「建议关闭省电 GPS」等标签，并给出一键修复按钮。经验性观察，该功能可把平均排障时间从 30 分钟再降 40%，但需企业控制台配合策略模板。个人版预计仅开放只读标签，不支持一键下发。若你计划明年扩建边缘节点，现在就把控制台升到 8.4 最新补丁，可避免后续大版本跳跃带来的兼容坑。

在那之前，记住今天的顺序：复现→导出→脱敏→压缩→上传工单。把日志先拿到手，你就领先了 90% 的「无法连接」求助帖。