如何在Linux终端使用快连命令行导入节点配置文件？

功能定位：为什么要在终端导入节点

快连在 2026 年 2 月发布的 v11.4.6 把「极速链 2.0」协议下放给 Linux CLI，服务器、NAS、树莓派等无图形界面场景也能调用 AI 选路。与桌面端拖拽相比，命令行一次性可写入几十条线路并立即生效，省去逐条点选。对每天凌晨需自动切出口 IP 的爬虫或灰度发布系统，这条指令就是 CI/CD 里的原子步骤。

下文用「CLI 导入」「批量导入」指代同一操作，避免关键词堆叠。示例路径基于 Debian 12 与官方 .deb 包；若用 RPM 或 AArch64，把 apt 换成 dnf/zypper 即可，命令本体不变。

前置条件：安装 CLI 与登录态

1. 下载最新安装包

截至当前，官方提供 .deb、.rpm、.tar.gz 三种格式。x86_64 Debian 系示例如下：

wget https://dl.quicklinkprivacy tool.com/linux/stable/quicklink-cli_amd64.deb
sudo dpkg -i quicklink-cli_amd64.deb

安装后，/usr/local/bin/ql 可用，配置根目录为 ~/.config/quicklink/。若曾装旧版，建议先 sudo apt remove quicklink-cli 避免 TAP 驱动残留。

2. 登录并固化 Token

CLI 不弹网页，需先在桌面端或手机端生成「设备授权码」：快连 App → 设置 → 高级 → CLI 授权 → 生成一次性码（30 分钟内有效）。回到终端：

ql login --code ABCD-1234

成功后将 JWT 写入 ~/.config/quicklink/credential，后续子命令免扫码。CI 容器可把该文件挂载为只读 secret，防止日志泄露。

节点配置文件的格式与来源

1. 官方导出：桌面端「导出 CLI 配置」

在 Windows/macOS 客户端选好节点后，节点列表 → 导出 → CLI 配置，会生成 ql-nodes-2026-03-22.json，内含线路 ID、延迟、带宽、入口 IP、混淆方式等字段，可直接导入，无需改键名。

2. 自建拼装：最小可用字段

若仅把公司内网跳板机加入列表，可手写简化版：

[{
  "id": "biz-jump-01",
  "label": "CN-SH-Office",
  "proto": "tls",
  "addr": "jump.example.com",
  "port": 443,
  "username": "${USER}",
  "password": "${SSH_PASS}"
}]

CLI 目前仅支持 tls|quic|ws 三种 proto；ss 与 ssr 需先转义成 tls+udp，否则导入会被拒绝。

核心命令：ql import 的三种模式

1. 覆盖模式（默认）

ql import --file nodes.json --mode replace

先清空本地节点缓存，再写入新列表，适合「每日凌晨拉取最新线路」的自动化场景。Cron 里建议加 --silent 抑制彩色输出，避免邮件告警乱码。

2. 增量模式

ql import --file nodes.json --mode merge

多业务组各自维护节点文件时，merge 可把新节点追加到本地，冲突 ID 以本地为准。经验性观察：若 ID 命名规则为「地区-序号」，重复概率低于 2%；UUID 命名几乎无冲突。

3. 试运行模式

ql import --file nodes.json --dry-run

不写入数据库，仅输出「新增 x 条/跳过 y 条/报错 z 条」摘要，可在 GitLab CI 里做 MR 门禁。z>0 时流水线直接 fail，确保只有格式合法的 PR 才能合并进 main。

自动化示例：GitLab CI nightly pipeline

假设运维组把最新线路放在 config/nodes-prod.json，每天 02:30 自动推送到边缘节点：

stages:
  - deploy

update-nodes:
  stage: deploy
  image: debian:12-slim
  before_script:
    - apt-get update -qq && apt-get install -y wget
    - wget -qO- https://dl.quicklinkprivacy tool.com/linux/stable/quicklink-cli_amd64.deb > ql.deb
    - dpkg -i ql.deb || apt-get install -f -y
    - cp $NODES_CREDENTIAL ~/.config/quicklink/credential
  script:
    - ql import --file config/nodes-prod.json --mode replace --silent
    - ql connect --smart
  retry: 2
  only:
    - schedules

$NODES_CREDENTIAL 是 GitLab CI 变量里上传的 credential 文件，类型 File；retry 2 可防止偶发 TLS 超时导致的误判。

验证与观测：确认导入已生效

1. 列表比对

ql node list --format json | jq '.[].id'

返回的 ID 若与导入文件一致，即写入成功。若缺失，先检查 JSON 数组顶层是否被意外包裹；再确认 proto 字段是否在允许范围内。

2. 实时日志

ql logs --follow | grep -E "node_id|latency"

流量切换后，日志会打印选中节点 ID 与实时延迟，方便与导入前的基线对比。

3. 指标导出（可选）

v11.4.6 起，ql metrics 子命令以 Prometheus 格式暴露 quicklink_node_rtt_ms 等指标，可接入自建 Grafana 看板，观察批量导入后的延迟分布变化。

小结与未来趋势

通过 ql import，运维可把「选路-下发-生效」压缩成一条原子指令，配合定时任务或 GitOps，实现无人值守的节点热更新。经验性观察，官方在 v11.4 nightly 分支已出现 --template 参数雏形，未来或支持按标签动态筛选节点，届时同一文件即可在不同机房自动衍生出「国内版」「海外版」两份配置，无需人工拆表。保持 CLI 升级，即可在现有流水线内无缝获得新能力。