快连命令行 CLI 安装与自动化脚本

对于习惯使用终端的开发者来说，图形界面虽然直观，但在服务器、容器或批量运维场景下并不方便。快连命令行工具（CLI）正是为这类用户设计的：它把客户端的核心能力封装成一组简洁的命令，您可以在终端里完成登录、连接、切换节点、查询用量等操作，并且能轻松嵌入到 Shell 脚本、CI/CD 流水线或定时任务中。本文将从安装开始，逐步介绍常用命令、配置方式，以及几个实用的自动化脚本示例。

如果您更喜欢图形界面，也可以先前往 快连下载 页面安装桌面客户端，熟悉基本概念之后再回到命令行，会更容易理解各参数的含义。

一、快连 CLI 适合哪些场景？

命令行工具并不是要取代客户端，而是补充了一些客户端不擅长的场景。以下几类用户会明显受益：

• 服务器运维：在无图形界面的 Linux 服务器上，通过 CLI 建立代理，让 yum、apt、pip 等工具顺利访问外部源。
• 容器与 CI/CD：在 Docker 镜像或 GitHub Actions 中安装 CLI，让构建过程自动走代理，拉取依赖更稳定。
• 批量设备管理：通过 SSH 在几十台机器上统一执行命令，无需逐台打开客户端。
• 自定义监控：定时执行命令查询连接状态、流量用量，写入自己的监控系统。
• 开发调试：在本地快速切换节点或代理模式，验证不同网络环境下的程序行为。

这些场景的共同点是：需要无人值守、可脚本化、可重复执行。CLI 的设计目标正是让这些操作变得简单可靠。

二、三平台安装方式

快连 CLI 支持 Windows、macOS、Linux 三大平台。安装方式略有不同，请根据您的系统选择对应步骤。

1. Windows

推荐使用官方提供的安装包。下载后双击运行，安装向导会询问是否将 kualian 添加到系统 PATH，请务必勾选。安装完成后，打开 PowerShell 或 CMD，执行 kualian --version，如果输出版本号说明安装成功。

2. macOS

推荐使用 Homebrew 安装：

brew tap kuailian/tap
brew install kuailian

如果没有 Homebrew，也可以下载官方 pkg 安装包，双击安装。安装后终端执行 kualian --version 验证。如果提示 command not found，请检查 /usr/local/bin 下是否存在软链接。

3. Linux

Debian / Ubuntu 用户可以使用 apt 源安装：

curl -fsSL https://cli.kualianlm.com.cn/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/kuailian.gpg
echo "deb [signed-by=/usr/share/keyrings/kuailian.gpg] https://cli.kualianlm.com.cn/apt stable main" | sudo tee /etc/apt/sources.list.d/kuailian.list
sudo apt update
sudo apt install kualian

CentOS / RHEL 用户可以使用 yum 源，或直接下载静态二进制文件放到 /usr/local/bin。安装完成后同样用 kualian --version 验证。

三、登录与初始化

安装完成后，第一步是登录。CLI 提供两种登录方式：交互式登录和令牌登录。

交互式登录

直接在终端执行：

kualian login

程序会提示您输入账号和密码，登录成功后会生成一个本地配置文件，默认位于 ~/.kuailian/config.yaml。之后执行命令时无需重复登录。

令牌登录（推荐用于服务器）

如果需要在服务器上无人值守运行，交互式输入密码并不方便。此时可以在官网控制台创建一个 API 密钥，然后使用：

kualian login --token kl_xxxxxxxxxxxxxxxx

令牌登录不会保存您的账号密码，只保存密钥本身，安全性更高，也便于后续轮换。

四、常用命令一览

快连 CLI 的命令设计遵循“动词 + 名词”的风格，易于记忆。以下是日常使用频率最高的命令：

命令	功能	常用参数
kualian connect	建立连接	--node 指定节点，--mode 指定代理模式
kualian disconnect	断开连接	无
kualian status	查看当前状态	--json 输出 JSON 格式
kualian nodes list	列出所有节点	--region 按地区筛选
kualian nodes test	测试节点延迟	--top 10 只显示前 10 个
kualian usage	查询流量用量	--today 仅显示今日
kualian config set	修改配置项	key value 形式

例如，连接到延迟最低的节点并输出状态：

kualian connect --node auto --mode rule
kualian status --json

再比如，列出日本地区节点并按延迟排序：

kualian nodes list --region jp --sort latency

这些命令都支持 --help 参数，遇到不熟悉的选项时可以随时查看帮助。

五、Shell 自动化脚本示例

CLI 的真正价值在于可以与其他工具组合。下面是一个实用的 Shell 脚本，它会先测试节点延迟，选择最快的节点连接，然后执行一段需要网络的命令：

#!/bin/bash
set -e

# 测试节点并按延迟排序，取第一个
BEST_NODE=$(kualian nodes test --sort latency --limit 1 --format name)

echo "选择节点: $BEST_NODE"

# 连接该节点
kualian connect --node "$BEST_NODE" --mode rule

# 等待连接就绪
sleep 3

# 执行需要代理的命令，例如拉取依赖
pip install -r requirements.txt

# 任务完成后断开
kualian disconnect

echo "任务完成"

把这段脚本保存为 build.sh，加上执行权限后即可在 CI 流水线中调用。它的好处是每次构建都会自动选择当前最快的节点，避免因固定节点拥堵导致构建失败。

六、Python 调用示例

如果您的自动化流程使用 Python，也可以通过 subprocess 调用 CLI，或直接使用快连 API。下面是使用 subprocess 的例子：

import subprocess
import json

def get_status():
    result = subprocess.run(
        ["kualian", "status", "--json"],
        capture_output=True,
        text=True,
        check=True
    )
    return json.loads(result.stdout)

def connect_best_node():
    # 获取延迟最低的节点名称
    result = subprocess.run(
        ["kualian", "nodes", "test", "--sort", "latency", "--limit", "1", "--format", "name"],
        capture_output=True,
        text=True,
        check=True
    )
    node = result.stdout.strip()
    print(f"连接节点: {node}")
    subprocess.run(["kualian", "connect", "--node", node], check=True)

if __name__ == "__main__":
    connect_best_node()
    status = get_status()
    print(f"当前状态: {status['state']}")
    print(f"当前节点: {status['node']}")
    print(f"出口 IP: {status['ip']}")

这段代码展示了如何把 CLI 的输出解析为结构化数据，再根据业务逻辑做决策。例如，如果发现出口 IP 不是预期的地区，可以自动切换到另一个节点。如果您希望直接调用接口而非 CLI，可以参考 快连 API 接口调用与密钥管理 一文。

七、配置管理

CLI 的配置文件默认位于 ~/.kuailian/config.yaml，采用 YAML 格式，可以直接编辑，也可以通过 kualian config set 命令修改。常用配置项包括：

• default_mode：默认代理模式，可选 global、rule、direct
• default_region：默认地区，例如 hk、jp、us
• auto_connect：是否在启动时自动连接
• log_level：日志级别，可选 debug、info、warn、error
• proxy_port：本地代理端口，默认 7890

例如，把默认端口改为 8899：

kualian config set proxy_port 8899

修改后需要重启 CLI 服务或重新连接才会生效。

八、常见问题排查

1. command not found

说明可执行文件没有加入 PATH。请检查安装目录是否已添加到环境变量，重新打开终端后执行 kualian --version 测试。macOS 与 Linux 用户可检查 /usr/local/bin 下是否存在软链接，Windows 用户需确认安装时勾选了“添加到 PATH”。

2. 权限不足

部分命令需要管理员权限才能修改系统代理设置。Linux 与 macOS 用户可在命令前加 sudo，Windows 用户需以管理员身份运行终端。但请注意，令牌登录信息保存在用户目录下，使用 sudo 时可能会读取不到，建议先配置好权限再执行。

3. 端口被占用

如果客户端与 CLI 同时运行，可能争夺同一个代理端口。可以修改 CLI 的 proxy_port 配置，或关闭其中一个程序。

4. 连接成功但命令仍不走代理

CLI 默认使用系统代理模式，但部分命令（如 curl、wget）可能忽略系统代理设置。此时可以显式指定代理环境变量：

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

5. 日志排查

遇到问题时，可以把日志级别调为 debug：

kualian config set log_level debug
kualian connect

日志默认输出到 ~/.kuailian/logs/cli.log，包含了详细的连接过程和错误信息，便于定位问题。

九、常见问题 FAQ

Q1：快连 CLI 提示 command not found 怎么办？

说明可执行文件没有加入系统 PATH。请检查安装目录是否已添加到环境变量，重新打开终端后执行 kualian --version 测试。macOS 与 Linux 用户可检查 /usr/local/bin 下是否存在软链接，Windows 用户需确认安装时勾选了“添加到 PATH”。

Q2：快连 CLI 可以在服务器上无人值守运行吗？

可以。使用 kualian login --token 方式登录，避免交互式输入密码；再配合 systemd、supervisor 或 nohup 让进程常驻即可。建议为服务器单独创建一个 API 密钥，并限制其权限范围。

Q3：快连 CLI 和客户端可以同时使用吗？

可以，但要注意两者不要争夺同一个代理端口。CLI 默认使用独立端口和配置目录，一般不会冲突。如果确实出现端口占用，可以在 CLI 配置文件中修改监听端口。

Q4：CLI 的输出可以保存为文件吗？

可以。大部分命令支持 --format json 或 --json 参数，您可以把输出重定向到文件，例如 kualian nodes list --json > nodes.json，便于后续程序解析。

Q5：CLI 会保存我的账号密码吗？

不会。令牌登录方式只保存 API 密钥，不保存账号密码。密钥会加密存储在本地配置文件中，且权限设置为仅当前用户可读。如果您仍不放心，可以定期轮换密钥。

命令行工具把快连的能力从图形界面中解放出来，让网络连接真正成为可编程的基础设施。无论是服务器运维、容器构建还是批量设备管理，CLI 都能帮助您把重复操作变成一行命令或一段脚本。掌握它之后，您会发现很多原本繁琐的网络配置工作，都可以用几行代码轻松完成。如果本文没有覆盖您遇到的问题，欢迎访问 常见问题 页面，那里汇总了更多排查方案。