快连Linux端如何一键更新订阅并剔除失效节点？

功能定位：为什么Linux端需要“一键更新+剔除”

桌面端点两下按钮就能刷新订阅，到了无头服务器或NAS里却常因“节点漂移”把SSH拖慢、CI跑超时。快连Linux端把“更新订阅”与“健康探测”拆成两条独立命令：先拉取最新列表，再用轻量级探活脚本把高丢包或不可达节点临时注释掉，既保证自动化，又避免误删付费线路。

官方文档把关键词“快连Linux端如何一键更新订阅并剔除失效节点”拆成两步：①qlink-cli sub refresh；②qlink-cli health --prune。理解输入输出后，就能把刷新、筛选、回滚串成无人值守的Systemd Timer。

前置条件与版本边界

截至2026-03-28发布的7.4.0，快连把CLI工具独立打包为quicklink-tools，与GUI版互不冲突。需要：

• amd64/arm64 Linux，内核≥4.14（WireGuard模块依赖）
• systemd≥240（用于定时任务）
• 订阅链接为HTTPS且已绑定账号（CLI首次登录写~/.quicklink/token）

警告

若仍在用2025 LTS旧仓库名qlink，需先执行sudo apt purge qlink再装新包，否则路径冲突会导致health子命令缺失。

安装与首次登录

1. 一键安装脚本（推荐）

curl -fsSL https://repo.quicklink.io/install.sh | sudo bash
# 脚本自动检测apt/yum/pacman，写入/etc/apt/sources.list.d/

2. 手工添加仓库（无网络脚本场景）

sudo tee /etc/apt/sources.list.d/quicklink.list <<'EOF'
deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/quicklink.gpg] https://repo.quicklink.io/stable/ubuntu jammy main
EOF
sudo wget -O- https://repo.quicklink.io/gpg.key | gpg --dearmor | sudo tee /usr/share/keyrings/quicklink.gpg
sudo apt update && sudo apt install quicklink-tools

安装后执行qlink-cli login，移动端扫码即可，JWT写入~/.quicklink/token，30天有效期并自动刷新。

两条核心命令拆解

qlink-cli sub refresh

拉取远端订阅压缩包，合并到/etc/quicklink/profiles/user.yaml，并生成带时间戳的备份user.yaml.bak.20260410T12。

常见失败：

• HTTP 401：token过期，重新login即可。
• HTTP 426：客户端版本过低，升级quicklink-tools。

qlink-cli health --prune

并发ping+TCP握手，默认丢包>20%或RTT>450 ms即失效，自动注释节点；加--dry-run可预览不写入。

提示

境外CI建议放宽RTT阈值到600 ms，避免误杀跨海链路：qlink-cli health --prune --rtt-max 600

拼装一键脚本

把两条命令串起并留回滚口：

#!/usr/bin/env bash
set -e
CONF=/etc/quicklink/profiles/user.yaml
BAK="${CONF}.bak.$(date +%Y%m%dT%H%M%S)"
cp "${CONF}" "${BAK}"
echo "备份已写至 ${BAK}"
qlink-cli sub refresh
qlink-cli health --prune
systemctl reload quicklink-daemon.service

保存为/usr/local/bin/qlink-auto-refresh并赋权+x。

定时任务：Systemd Timer优于crond

经验性观察：Systemd Timer支持秒级精度与失败重退，比crond更稳。

sudo tee /etc/systemd/system/qlink-refresh.service <<'EOF'
[Unit]
Description=QuickLink Subscribe Refresh and Prune
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/bin/qlink-auto-refresh
EOF
sudo tee /etc/systemd/system/qlink-refresh.timer <<'EOF'
[Unit]
Description=Run qlink-refresh every 6 hours
[Timer]
OnCalendar=*-*-* 00,06,12,18:00:00
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now qlink-refresh.timer

回退方案：如何秒级还原

剔除过度导致可用节点不足时，手动还原：

1. 找到最近备份ls -l /etc/quicklink/profiles/user.yaml.bak.*
2. sudo cp user.yaml.bak.XXXX user.yaml
3. sudo systemctl reload quicklink-daemon.service

也可在脚本里加判断：剩余节点<3时自动回退并告警。

验证与观测：让结果可度量

1. 看日志

Timer执行记录：journalctl -u qlink-refresh.service -b

2. 看节点数

qlink-cli list | grep -c '^\s\+-'  # 刷新前后对比

3. 看延迟分布

qlink-cli health --json | jq '.nodes[] | {name: .name, rtt: .rtt}'

把JSON推到Prometheus Node Exporter，可绘制“剔除后平均RTT”曲线，经验性观察晚高峰下降约18%。

例外与取舍：什么时候不该自动剔除

• 企业SLA场景：节点虽丢包但承载专线备份，剔除会触发BGP切换，建议加--exclude-tag backup跳过。
• IPv6 Only测试床：部分IPv4节点在IPv6-only网络被误判，可临时加--family ipv4只测IPv4。

与第三方监控协同

已有Zabbix或Grafana时，在脚本末尾把剩余节点数、平均RTT写成Pushgateway格式，即可在“订阅质量”面板直接告警，省去登录排障。

故障排查速查表

现象	最可能原因	验证	处置
refresh报401	token过期	cat ~/.quicklink/token	qlink-cli login
health剔除0节点	阈值过松	qlink-cli health --json | jq .summary	调低--loss-max
reload后断流	yaml语法被误改	qlink-cli validate	回退bak文件

适用/不适用场景清单

• ✅ 个人NAS、软路由、远程开发机，节点>10且更新频率>1次/日
• ✅ 小型团队共享单账号，需保证CI出口稳定
• ❌ 合规要求“固定IP审计”的证券交易容器，剔除会导致IP变化
• ❌ 节点<3，剔除后无冗余路径，建议手动选路

最佳实践检查表

1. Timer间隔≥4小时，避免订阅服务器被限流
2. 保留近7天备份，用logrotate压缩
3. 剔除阈值写入脚本变量，方便批量调整
4. 重要业务节点打tag，用--exclude-tag跳过自动剔除
5. 每次reload后跑qlink-cli validate，确保yaml合法

FAQ（结构化数据）

总结与下一步行动

快连Linux端用两条官方命令即可实现订阅更新与失效剔除，配合Systemd Timer可在NAS、软路由、云服务器零干预运行。关键是：每次操作前自动备份，留回滚口；用JSON输出+jq做可观测，避免“盲删”；对特殊节点加tag，防止误杀。

下一步，把剩余节点数、平均RTT推送到Grafana，再配OnFailure告警，就能在“订阅质量”上实现闭环。立即保存脚本跑一遍验证，晚高峰的SSH卡顿会明显减少。