快连CLI模式如何静默更新订阅节点？
快连CLI模式如何静默更新订阅节点？用systemd定时器+静默参数，5分钟自动拉取，零打断。
功能定位：CLI 静默更新到底解决什么
桌面端点一次“刷新订阅”就会强制重连，这在树莓派、NAS 或云函数等无人值守环境里等于直接“自杀”。快连从 v8.2 起把「订阅更新」拆成独立子命令，可在不中断隧道的前提下把远端节点列表同步到本地，再由「AI-Route 2.0」引擎在后台完成毫秒级切换。所谓「快连CLI模式如何静默更新订阅节点」，指的就是这条命令行路径。
与 GUI 的明显区别：GUI 刷新＝立即重连；CLI 刷新＝仅写缓存，由引擎自行决定何时切线。经验性观察：同一小时内重复刷新 3 次以上，切线频率反而上升，建议把刷新间隔拉到 5 min 以上。
版本演进：订阅子命令的三次变更
v8.0 之前：无独立命令
订阅地址硬编码在 config.json，每次启动时拉取一次；无刷新机制，节点被拉黑只能手动重启客户端。
v8.2：引入 /subscription refresh
首次提供 HTTP API 与 CLI 双通道，但默认行为仍触发重连，需加 --soft 才能“软刷新”。
v8.4.1（截至当前的最新版本）：默认静默
refresh 子命令默认走软刷新；新增 --force 参数显式触发重连，反向兼容脚本。
最短操作路径（分平台）
Linux / macOS
- 安装目录下给 cli 加执行权限
chmod +x /opt/kuailian/bin/kuailian-cli - 执行刷新
/opt/kuailian/bin/kuailian-cli subscription refresh - 观察返回码
echo $?0 表示已写入缓存，非 0 可查看 stderr。
Windows PowerShell
- 以管理员身份打开 PowerShell，定位到安装目录（默认在
C:\Program Files\kuailian\bin，具体路径因版本和安装方式而异，请以实际为准）。 .\kuailian-cli.exe subscription refresh- 若返回“Already up to date”说明 304 未修改，不会触发写盘，可放心写入计划任务。
Android（仅 root 后可行）
快连在 Android 端同样提供 /data/data/com.kuailian/files/cli 可执行文件，但需通过 run-as 或 adb shell 调用；非 root 场景下无法定时，建议改用「Wi-Fi 连接时触发」Tasker 插件。
systemd 定时器：5 分钟自动刷新示例
以下单元文件在 Debian 12 通过，原理是「定时器唤醒 + 一次性服务」，失败自动重试 3 次。
启用命令：systemctl daemon-reload && systemctl enable --now kuailian-refresh.timer
提示：AccuracySec=10s 可把唤醒误差压到 10 秒内，降低云主机 CPU 计费点；若你用的是按量计费轻量云，可拉到 30s 节省事件数。
回退与失败分支
1. 远端 502/429
CLI 会以非 0 码退出，systemd 默认 30s 后重试；若连续 3 次失败，timer 进入挂起状态，需手动 systemctl reset-failed。
2. 本地缓存损坏
表现为 refresh 返回 0 但节点列表为空。解决：先 subscription clear-cache 再 refresh；若仍为空，需检查订阅链接是否被 CDN 重定向到验证页面。
3. 误加 --force 导致断流
若脚本里写错参数，触发全量重连，正在进行的 Zoom 会掉线 1~2 秒。缓解：在 CI 或 Ansible 里加预检 --dry-run，确认无 force 字样再下发。
验证与观测方法
| 观测项 | 命令/路径 | 正常值 |
|---|---|---|
| 最后刷新时间 | kuailian-cli subscription status | jq .LastUpdate | 距现在 < 5 min |
| 节点数量 | kuailian-cli node list | wc -l | > 30（经验性观察） |
| systemd 失败次数 | systemctl status kuailian-refresh.service -n 5 --no-pager | 无 red failed |
建议把以上三条写成 Prometheus textfile，被 node-exporter 抓取，可在 Grafana 画「节点数突降」告警，10 分钟内就能发现订阅源被劫持。
例外与取舍：什么时候不该静默刷新
- 「回国」模式专供游戏加速器：其订阅文件额外包含 L2TP 中继 IP，刷新时若撞上车流高峰，可能把游戏线路切到 200 ms 以上的出口。工作假设：对延迟敏感场景，改用「手动 + 告警」而非自动。
- 流量代币账户剩余 < 1 GB：静默刷新不会检查代币，但下次重连就会因为余额不足被强制断开。建议先在 API 查询 /account/traffic 低于阈值时暂停 timer。
- 合规审计场景：部分公司要求「任何配置变更必须双人审批」。静默刷新违背审批流，此时应关闭 timer，改用 Ansible playbook 走 OA 工单。
与第三方 Bot 协同的最小权限原则
经验性观察：TG 频道里流传「订阅机器人」可代刷节点，但多数需要把订阅链接中的 UID 明文发过去。一旦机器人被攻破，攻击者可直接消耗你的流量代币。可复现验证步骤：
- 在快连控制台生成「只读订阅」子链接（仅返回节点，不返回 UID）。
- 把子链接交给机器人，主链接留本地。
- 观察机器人后台请求：若仍出现 403，说明子链接已隔离账户敏感信息。
警告：任何需要「登录态 Cookie」的第三方工具都违反零日志原则，官方不会提供此类接口，出现泄露概不负责。
故障排查速查表
现象：timer 启动但节点数不增
可能原因：订阅地址被 302 到广告页。验证：curl -I https://你的订阅链接 看是否 200；处置：把订阅域名加入代理白名单，避免被国内 CDN 劫持。
现象：CLI 返回 0，但 journal 里报「decode error」
原因：缓存目录权限被别的进程改成 root，普通用户无法覆写。处置：chown -R kuailian:kuailian /var/lib/kuailian/cache
现象：5 分钟一次刷新导致 429
原因：同出口 IP 被订阅 CDN 限流。处置：在 timer 里加 RandomizedDelaySec=120，把请求打散到 2 分钟窗口。
适用/不适用场景清单
| 场景 | 推荐刷新间隔 | 备注 |
|---|---|---|
| 家用软路由 | 5 min | 节点掉线自动补，不影响追剧 |
| 云函数爬虫 | 30 min | 降低出口 IP 轮换频率，避免封账号 |
| 企业合规网关 | 手动 | 需审计，自动刷新违反流程 |
| 回国游戏加速 | 关闭 | 切线导致游戏瞬断，>50 ms 抖动 |
最佳实践 10 条检查表
- 永远用「只读订阅」子链接对接第三方。
- timer 加 RandomizedDelaySec，避免集体 429。
- 刷新间隔 ≥5 min，减少无意义切线。
- 失败 3 次后自动 reset-failed，防止 timer 永久挂起。
- 把 UID 订阅链接放密码管理器，禁止硬编码在 GitHub。
- 余额低于 1 GB 先停 timer，防止突然断网。
- 回国/出国双通道场景，用标签把游戏 IP 钉死在回国通道。
- 每次升级客户端后，在测试机先跑 30 min 无断流再推生产。
- 用 Prometheus textfile 监控节点数，突降 ≥20% 即告警。
- 保留 journal 30 天，出问题可回溯。
FAQ（结构化数据）
刷新订阅会断开现有连接吗？
默认软刷新不会断；只有显式加 --force 才会强制重连。
timer 失败重试间隔能改吗？
可以，在 Service 段加 RestartSec=60s 即可，最小值 1s，但不建议低于 10s，防止打爆订阅服务器。
Windows 家庭版没有 systemd 怎么办？
用任务计划程序，触发器设「每隔 5 分钟」，操作选 kuailian-cli.exe，参数填 subscription refresh，条件里取消「仅 AC 电源」即可。
如何确认节点已更新但未被使用？
执行 kuailian-cli node list --json | jq '.[] | select(.lastSeen==null)' 若返回空，说明所有节点都已至少被 AI-Route 探测过一次。
可以一次性刷新多个订阅链接吗？
截至当前的最新版本暂不支持，需要循环调用 refresh 并更换环境变量 kuailian_SUBSCRIPTION_URL，或等待官方后续迭代。
收尾：下一步行动建议
如果你已经在 Linux 路由器上跑快连，先复制本文的 systemd 单元文件，10 分钟就能实现「零感知」订阅更新；桌面用户可把刷新间隔放宽到 30 min，避免高峰时段抢线。最后一条：任何自动化都要配监控，用 Prometheus 抓节点数，再小的家宽也值得一个 Grafana 面板——毕竟，掉线永远发生在老板发消息的前一秒。
