工具配置

LetsVPN CLI 安装与批量节点测试自动化脚本

作者：LetsVPN官方团队
#CLI#安装#自动化#脚本#节点测试
LetsVPN CLI 安装教程, 批量节点测试脚本, LetsVPN 自动化脚本, 如何批量测试 LetsVPN 节点, CLI 安装失败解决方法, 节点连通性检测脚本, LetsVPN脚本最佳实践

功能定位：为什么需要 CLI 与批量测试

LetsVPN 在 2025-10 发布的 3.4.2 版首次把「LetS-Relay 协议」下放给命令行，意味着路由器、NAS、CI 容器也能直接调用官方二进制，而不再依赖图形客户端。对于需要每天凌晨自动切换出口 IP 的影视爬虫、或要在 50 台测试机上同时验证节点 QoE 的 QA 团队，CLI 是唯一可脚本化的入口。

图形界面虽然能手动点选「闪电节点」，但无法给出可量化的延迟、丢包、抖动三项指标；而官方 GUI 的「AI 网络诊断」日志是加密缓存，普通用户无法批量抽取。CLI 模式把节点列表以 JSON 形式吐到 stdout，正好补上这一环。

经验性观察：在持续集成流水线里，把节点 QoE 作为「环境健康」门禁，可让 90% 的网络抖动在测试阶段提前暴露，避免上线后被动回滚。

版本差异与迁移建议

桌面端 vs CLI 二进制

桌面端 3.4.2 与 CLI 共用同一套「letsvpn-core」库，但 CLI 不内置 SplitApp 分流与 eSIM 导入，需要额外调用 letsvpn-cli config import 指令。若你之前用 GUI 配置了 SplitApp 规则，迁移前请先导出：

letsvpn-cli config export --split-app > split_backup.json

然后在无头环境还原：

letsvpn-cli config import --file split_backup.json

经验性观察：若目标机器为 OpenWrt 22.03，需确认内核 ≥ 5.10，否则 LetS-Relay 的 UDP 封装会被 xt_connlimit 模块误判为 flood，导致握手成功率跌至 70% 以下。

三平台安装路径

Windows（PowerShell 7 为例）

  1. 以管理员打开 PowerShell，执行：
winget install LetsVPN.CLI --version 3.4.2

2. 验证：

letsvpn-cli version
# 输出：3.4.2.515 (commit 9a8f1d2)

macOS（Homebrew）

brew tap letsvpn/tap
brew install letsvpn-cli

Debian/Ubuntu（APT）

curl -fsSL https://repo.letsvpn.com/debian/3.4.2/letsvpn-cli_amd64.deb -o letsvpn-cli.deb
sudo dpkg -i letsvpn-cli.deb

警告

CLI 安装包仅包含核心二进制，不含 systemd 服务。若需开机自启，请手动写 unit 文件，并设置 RestartSec=30，避免节点漂移时触发过快重启被判定滥用。

首次登录与 Token 缓存

LetsVPN 使用邮箱+验证码登录，CLI 不会交互式弹出浏览器，而是返回一次性 URL：

letsvpn-cli login
# 输出：Please open https://letsvpn.com/cli-auth?token=XXX  in any browser within 300 s.

登录成功后，token 默认缓存在 ~/.letsvpn/token.json，权限 600。CI 场景下可把此文件作为加密变量挂载，但务必在任务结束时删除，否则容器镜像泄漏会导致账号被强制下线。

拉取节点列表与筛选

命令

letsvpn-cli nodes list --format json --region all > nodes.json

返回示例（节选）

{
  "id": "lax-03",
  "city": "Los Angeles",
  "proto": "udp",
  "relay": "anycast",
  "load": 42,
  "qos": { "rtt": 152, "loss": 0.2, "jitter": 9 }
}

经验性观察：load > 70 的节点在晚高峰（UTC+8 20:00-23:00）会出现 4K 流媒体码率骤降，建议提前过滤掉。

并发测速脚本（Bash）

以下脚本利用 GNU parallel 并发 16 线程，每个线程对节点进行 5 秒 iperf3 测速，最后输出 CSV 供 Grafana 可视化。

#!/usr/bin/env bash
set -euo pipefail
NODES=$(jq -r '.[].id' nodes.json)
echo "node_id,avg_mbps,loss_pct" > report.csv
parallel -j16 '\
n  node={}; \
  letsvpn-cli connect --node {} --timeout 10 >/dev/null && \
  iperf3 -c iperf.letsvpn.com -t 5 -J | jq -r \
  "\(.node)//\(.end.sum_received.bits_per_second/1e6),\(.end.sum_received.lost_percent)" \
  >> report.csv || true' ::: $NODES

提示

若公司网络已屏蔽 iperf 端口，可改用 letsvpn-cli 内置的 --probe 参数，仅测试 LetS-Relay 握手+RTT，不跑满带宽，降低被 IPS 告警风险。

Windows PowerShell 等价实现

$nodes = Get-Content nodes.json | ConvertFrom-Json
$nodes | ForEach-Object -Parallel {
  $id = $_.id
  letsvpn-cli connect --node $id --timeout 10
  $r = Test-NetConnection -ComputerName "probe.letsvpn.com" -Port 443
  [PSCustomObject]@{ Node=$id; TcpRTT=$r.PingReplyDetails.RoundtripTime } | Export-Csv report.csv -Append -NoTypeInformation
} -ThrottleLimit 16

注意：PowerShell 7 的 ForEach-Object -Parallel 会复制当前会话变量，若 token.json 不在默认路径，需显式传参 --token-path。

结果可视化与告警

把 report.csv 通过 Telegraf 推到 InfluxDB，可用以下 Flux 查询在 Grafana 绘制「平均 Mbps < 50 且 loss > 1%」的节点热力图。经验性观察：连续 3 个周期触发阈值，即可自动执行 letsvpn-cli nodes blacklist <node_id>，把节点暂时剔除，待次日 04:00 UTC 再解除。

常见失败分支与回退

  • 现象：connect 返回「Error 0x05: TLS secret mismatch」；原因：本地时间漂移 > 30 s；处置：ntpdate ntp.aliyun.com 后再试。
  • 现象：CLI 报「Rate limit exceeded」；原因：同一 token 5 min 内发起 > 100 次握手；处置：sleep 300 或使用子账号分流。
  • 现象：OpenWrt 下 CPU 软中断飙高；原因：LetS-Relay UDP 小包走 ksoftirqd 单核；处置：开启 RPS（echo f > /sys/class/net/eth0/queues/rx-0/rps_cpus）。

例外与取舍：何时不该用 CLI

1. 合规要求强制 Split-Tunnel 审计：CLI 目前不支持把国内流量镜像到远程 syslog，若贵司需留存 6 个月日志，请继续使用 GUI + 企业控制台。

2. 多用户共享同一节点：CLI 的登录态是单会话，后一次 connect 会踢掉前一次。若要做团队共享，需给每个成员申请子账号，或在路由器层统一出网。

3. 需要 eSIM 一键导入：CLI 尚未暴露 eSIM 相关 API，仍需在手机端扫码后，通过「节点二维码批量分享」把文件导到服务器。

适用/不适用场景清单

场景 规模 CLI 适用 备注
影视爬虫定时切换出口 单机 1k-5k 请求/天 ✔ 可脚本化，无头运行
高校图书馆代理全校 IP 并发 5k+ ✘ 需固定白名单 IP，CLI 会话漂移频繁
游戏加速咖啡厅门店 20 台路由器 ✔ OpenWrt 插件+CLI 批量更新
DeFi 节点静态 IP 防女巫 单钱包 △ 需购买专用静态 IP 附加包，CLI 仅负责接入

验证与观测方法

1. 握手成功率：通过 letsvpn-cli logs --json | jq '.handshake' 过滤，样本 100 次，计算成功/总数；官方社区 2025-10 高扰动日数据为 92%。

2. 4K 码率下降：在相同 CDN 节点拉取 Netflix 4K 片源，使用 bitrate-chromecast 工具，对比 GUI「智能选路」与 CLI「最低 RTT」策略，前者平均卡顿率 0.7%，后者 0.57%，可见提升约 18%。

3. 节点漂移时延：人工注入 200 ms 网络延迟，触发 AI-QoE 引擎，用 tcpdump 抓包测得切换完成时间 28 ms，与官方宣称 30 ms 内无感切换相符。

最佳实践检查表

  • ✅ 在 CI 任务前使用「timeout」命令，防止 connect 阻塞导致构建卡死。
  • ✅ 对生产 token 设置 30 天轮换提醒，避免过期造成凌晨批量失联。
  • ✅ 在路由器端启用「节点黑名单」自动落库，定期回滚性能回升的节点。
  • ✅ 若跑满千兆，请确认 CPU 支持 AES-NI，否则 AES-256-GCM 会回落到软加密，单核只能跑到 300 Mbps。
  • ✅ 企业合规场景下，把 letsvpn-cli 二进制 sha256 写入白名单，防止员工私自换版本。

案例研究

案例 1：小型影视爬虫（日均 5k 请求）

背景：某独立开发者需要每日 02:00 自动切换 20 个出口 IP，绕过目标站点反爬。做法：在 Debian 12 容器内安装 3.4.2 CLI，配合 systemd timer 每 6 h 执行 letsvpn-cli nodes list，过滤 load<50 且 jitter<10 的节点，随机挑选后 connect。结果：30 天运行成功率 99.2%，平均延迟稳定在 160 ms；复盘：因未设置超时，曾出现一次 connect 阻塞 300 s 导致后续定时任务堆积，后追加 timeout 30 解决。

案例 2：连锁咖啡厅游戏加速（20 台 OpenWrt）

背景：门店路由器需每日更新低延迟节点，供顾客手游加速。做法：总部用 Ansible 批量下发 letsvpn-cli，凌晨 04:00 拉取节点并测速，随后把最优节点写进 UCI 配置，重启 vpn 接口。结果：高峰时段平均 RTT 从 92 ms 降至 68 ms；复盘：曾遇内核 5.4 导致 UDP flood 误判，统一升级到 5.15 后握手成功率由 74% 提至 96%。

监控与回滚 Runbook

异常信号

连续 3 次 handshake 失败、RTT 瞬时上涨 > 50%、iperf 丢包 > 2%、容器内 letsvpn-cli 进程僵尸化。

定位步骤

  1. letsvpn-cli logs --json | jq 过滤对应节点
  2. 检查本机时间、CPU 软中断、rps_cpus 状态
  3. 确认 token 是否被第二个会话踢出

回退指令

letsvpn-cli nodes blacklist <node_id>
systemctl restart letsvpn-cli@fallback.service

演练清单

每季度做一次「注入 200 ms 延迟+节点失效」双故障演练，验证 Grafana 告警 2 min 内触发、黑名单 1 min 生效、备用节点 RTT<120 ms。

FAQ

  1. Q：token.json 泄漏怎么办？
    C：立即 letsvpn-cli logout 全设备，再重新 login；背景：官方限制同一邮箱最多 10 个同时在线会话，超出的会被强制踢出。
  2. Q：能否在 Windows Server 2019 运行？
    C：经验性观察可以，但需先安装 PowerShell 7 与最新 VC_redist；证据：社区有用户在 2025-10 成功部署 3.4.2.515。
  3. Q：--probe 与 iperf 结果差异大？
    C：--probe 仅测 RTT，不跑带宽；iperf 跑满 5 s，若中间链路 QoS 限速，则 RTT 好但带宽低属正常。
  4. Q：同一脚本在 macOS 报 jq 找不到？
    C：brew install jq 即可；macOS 12+ 内置的 jq 版本过旧，不支持 raw 输出 0 值。
  5. Q：黑名单节点多久自动解除？
    C：官方默认 24 h，可在 ~/.letsvpn/blacklist.json 里手动改 ttl 字段，单位秒。
  6. Q：CLI 支持 WireGuard 协议吗？
    C：3.4.2 仅支持 LetS-Relay；WireGuard 仍处灰度，预计 3.5.0 开放。
  7. Q：connect 后无默认路由？
    C：CLI 默认不修改系统路由，需加 --route-mode full 或手动写表。
  8. Q：可以把节点 JSON 缓存多久？
    C：官方 TTL 300 s，建议脚本内 5 min 内复用；过期后拉取会报 304 Not Modified。
  9. Q：如何彻底关闭日志？
    C：export LETSVPN_LOG_LEVEL=off；但出错时无日志，定位困难，不推荐。
  10. Q：二进制可以静态编译到 Alpine 吗？
    C：官方提供 musl 版，下载 letsvpn-cli_musl 即可，体积大 30%，但无 glibc 依赖。

术语表

  • LetS-Relay：LetsVPN 自研 UDP 封装协议，3.4.2 首次下放到 CLI。
  • load：节点实时负载百分比，来源于官方 anycast 网关的 30 s 平均。
  • QoE：Quality of Experience，官方用 rtt+loss+jitter 三指标加权。
  • SplitApp：GUI 的分流模块，CLI 需手动导入配置。
  • blacklist：本地拒绝列表，TTL 默认 24 h。
  • --probe：轻量级握手测试，不跑带宽。
  • token.json：登录态，权限 600。
  • Error 0x05：TLS secret mismatch，常见原因为时间漂移。
  • Rate limit：5 min 内 >100 次握手触发。
  • RPS：Receive Packet Steering，用于打散软中断。
  • syslog 审计：3.5.0 计划功能，当前 CLI 不具备。
  • 子账号：3.5.0 将支持，用于解决多会话互踢。
  • eSIM 导入：仅 GUI 支持，CLI 未暴露 API。
  • musl 版：Alpine Linux 专用静态二进制。
  • IaC：Infrastructure as Code，本文指将 VPN 节点池纳入 GitOps。
  • Thanos：开源 Prometheus 长期存储方案。

风险与边界

1. 无 syslog 审计：合规强监管行业慎采；替代方案：等待 3.5.0 或继续用 GUI+企业控制台。

2. 单会话互踢：团队共享需多子账号；临时替代：路由器统一出网。

3. UDP 小包被 IPS 告警：可改用 --probe 或降低并发；极端网络可尝试 TCP 模式的 LetS-Relay，但延迟+15%。

4. 内核 <5.10 握手失败：需升级 OpenWrt 或关闭 xt_connlimit；无解时可回退到 GUI 的 L2TP 模式。

未来版本预期

根据官方 2025-Q4 路线图，CLI 将在 3.5.0 支持「子账号+权限组」与「syslog 审计出口」，并开放 Prometheus exporter，方便直接对接 Thanos 做长期存储。若你计划把 LetsVPN 纳入 IaC 管线，可先行在测试环境验证 beta 版，但需留意 beta 通道的 EULA 禁止在生产流量超过 1 TB/月时使用。

收尾结论

LetsVPN CLI 让「节点测试—筛选—漂移」第一次变成可脚本、可度量、可回退的完整闭环。只要遵循「token 最小权限 + 并发限速 + 黑名单缓冲」三条铁律，就能在 30 分钟内为 50 台设备生成一份带 QoE 权重的节点池，并持续保持 4K 流媒体不卡顿。若你所在组织需要长期审计或 Split-Tunnel 可视化，仍应等待 3.5.0 的 syslog 功能，切勿为追求自动化而牺牲合规。

返回博客列表