快连CLI模式如何开启并配置分流规则？

功能定位：CLI 模式到底解决什么问题

快连 CLI 模式（Command-Line Interface）把图形界面的“一键加速”拆成可脚本化的子命令，让自动化平台、CI 流水线乃至家庭网关都能直接调用。与 GUI 相比，CLI 的核心价值是“可编排”：你可以在 macOS 的 launchd、Linux 的 systemd、Windows 的 Task Scheduler 里定时切换节点；也能在 GitHub Actions 里先连海外节点跑 npm install，再切回国内节点 docker push，全程无需人工点击。

分流规则（Split Tunnel Rules）则是 CLI 模式里最常被误用的部分：它允许你把“指定域名或 IP 段”排除在加密隧道之外，从而把延迟敏感的局域网打印机、公司内网 DNS、国内直播 CDN 留在直连通道。理解“谁该走隧道、谁该直连”是开启 CLI 前的先修课，否则会出现“开了 CLI 反而打不开网页”的错觉。

前置条件与版本边界

截至当前最新版本（2026-02-28 发布的 v6.3.0）已将 CLI 二进制单独拆包，Windows 对应 KuailianCLI.exe，macOS/Linux 对应 kuailian-cli。桌面端 GUI 与 CLI 共用同一套配置文件，但 CLI 不会自动同步 GUI 的“智能分流”开关；换言之，谁先写配置文件谁占优，后启动的一方会收到“config file locked”提示。

经验性观察：在 Windows 上若同时开启 GUI 的“开机自启”与 systemd 定时 CLI，后者大概率因端口占用失败；建议把 GUI 自启关闭，仅用 CLI 托管。

安装与首次登录

Windows 路径

1. 在官网下载页勾选“CLI 独立包”，解压到 D:\KuailianCLI。
2. 以管理员身份打开 PowerShell，执行
   .\KuailianCLI.exe login --token YOUR_TOKEN
   Token 获取：GUI → 我的 → 开发者令牌 → 生成，一次性有效期 30 天。
3. 出现“Login OK, profile saved to %USERPROFILE%\.kuailian\config.json”即成功。

macOS / Linux 路径

1. Homebrew 尚未收录，官方提供静态编译 tar.gz；解压到 /usr/local/bin 并 chmod +x。
2. kuailian-cli login --token YOUR_TOKEN
3. 配置文件落盘在 ~/.kuailian/config.json。

开启 CLI 模式：两条主流入口

入口 A：直接前台运行

适合临时调试。命令：
kuailian-cli connect --node "Hong Kong 05" --protocol wireguard
节点别名可用 kuailian-cli list --region hk 查看。前台运行会阻塞终端，Ctrl-C 即断线，配置不会被守护进程复用。

入口 B：守护进程（推荐）

Windows 用 WinSW 包装成服务；macOS 用 launchd；Linux 用 systemd。官方示例单元文件已放在解压包的 examples 目录，只需把用户名与令牌换成自己的即可。守护模式会锁定配置文件，GUI 再想切换节点就必须先停止服务。

分流规则语法速览

快连 CLI 采用 YAML 片段描述规则，文件路径因系统而异（Windows 在 %USERPROFILE%\.kuailian\rules\custom.yml，macOS/Linux 在 ~/.kuailian/rules/custom.yml）。规则自上而下匹配，命中即停止。

# custom.yml 示例
- name: 公司内网直连
  action: direct
  dst: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16

- name: 国内流媒体走直连
  action: direct
  domain_suffix:
    - bilibili.com
    - iqiyi.com

- name: 其余全部代理
  action: proxy
  dst: 0.0.0.0/0

动作只有两种：direct=直连，proxy=走隧道。CLI 在启动时加 --rule custom 即可加载；若省略，则默认走全局代理，相当于无分流。

如何验证规则生效

1. 开两条终端，一条执行 kuailian-cli status --verbose，会实时打印“DOMAIN_HIT”或“IP_HIT”。
2. 另一条用 curl 带 -x 参数强制走本地 SOCKS5（默认端口 2080）：
   curl -x socks5://127.0.0.1:2080 https://www.iqiyi.com
   若规则命中 direct，CLI 日志会显示 bypass，同时出口 IP 仍为你本地宽带地址。
3. 把域名换成 google.com，应看到出口 IP 变为节点地址，证明其余流量已进隧道。

平台差异与回退方案

Windows 特有问题

WinSW 服务如果选用“LocalSystem”账户，会导致规则文件无写入权限；务必把服务登录身份改成本地真实用户，否则修改 custom.yml 后不会热加载。

macOS 特有问题

15.3 以后系统扩展需手动授权，CLI 首次启动会弹“系统扩展已阻止”；按官方 FAQ 在恢复模式执行 spctl kext-consent add 7KT7JXG9V8 即可，否则分流规则在 TUN 模式不生效。

Linux 特有问题

systemd 单元默认写死 /usr/local/bin/kuailian-cli；如果你把二进制放到 ~/bin，需要改 ExecStart 绝对路径，否则守护进程会无限重启。

不适用场景清单

• 公司网络已强制 WPAD/PAC 代理：CLI 的 TUN 模式会与 PAC 冲突，导致内网门户无法打开；此时只能改用 GUI 的“浏览器插件模式”。
• 需要按进程名分流：快连 CLI 目前只支持 IP/域名维度，无法识别进程 PID；游戏多开玩家仍需依赖 GUI 的 Split-App 功能。
• IPv6-only 环境：截至当前版本，CLI 在纯 IPv6 链路上会回退至 4in6 隧道，延迟明显升高；建议关闭 IPv6 再使用。

最佳实践 10 条

1. 先用前台模式调试通过，再写成服务，减少排障面。
2. 规则文件加入 git，变更回滚只需 git checkout。
3. 把公司内网网段写死在最前，避免误走海外节点导致 OA 超时。
4. 每月用 kuailian-cli update-rule 拉取官方广告过滤列表，与自定义规则合并，而不是直接覆盖。
5. 在 CI 流水线里把 --log-level error 打开，否则 Actions 日志会被 debug 淹没。
6. 节点别名带空格时必须加双引号，否则 PowerShell 会截断。
7. 若需同时跑两条链路（双通道冗余），给第二条 CLI 指定不同 config 目录 --config-dir ~/.kuailian2，避免端口冲突。
8. systemd 里加 RestartSec=10，防止节点临时维护时无限快速重启被系统限流。
9. 分流规则命中数可通过 kuailian-cli metrics 输出，结合 Prometheus exporter 做 Grafana 面板。
10. Vision Pro 2 空间办公模式下，CLI 仍走 TUN，但虚拟大屏播放器需额外加一条 domain_suffix: disneyplus.com 直连，否则 DRM 会识别隧道 IP 为代理而降级 1080P。

故障排查速查表

现象	最可能原因	验证命令	处置
connect 报 "auth failed"	令牌过期	GUI 重新生成令牌	login 更新
status 显示 "rules not found"	custom.yml 路径错	ls ~/.kuailian/rules	移动文件到正确目录
Disney+ 仅 1080P	DRM 识别代理 IP	curl ifconfig.me	加 domain 直连规则

FAQ（结构化数据）

收尾：下一步行动清单

读完本文，你应已能判断“CLI 模式+分流规则”是否值得在自身场景落地。建议先用前台命令验证规则，确认无断网、无 DRM 降级后，再写成守护进程并纳入 Git 版本。记得把公司内网段放在规则最前，每月拉取官方过滤列表，才能既享受 AI 链路自愈的低延迟，又不让 OA 系统偶发超时。下一步，打开终端，输入第一条 kuailian-cli login，开始你的可编排网络之旅吧。