快连kuailian macOS CLI如何批量导入节点配置？

功能定位：为什么需要 CLI 批量导入

在跨境电商或流媒体运维场景里，每天要在数十台 macOS 编译机、CI 容器或测试真机上切换出口节点。若用图形客户端逐一手动添加，平均耗时约 90 秒/条，且容易输错 Base64 密钥。快连 kuailian 提供的 kuailian-cli 支持一次性导入 YAML/JSON 列表，把重复操作压缩到 10 秒内，同时可与 Ansible、Zsh 循环脚本直接对接，实现「配置即代码」。需要明确的是，CLI 批量导入仅影响本地节点簿，不会同步到云端账号；若后续在 GUI 里执行「同步配置」，本地未分组节点将被云端视图覆盖。理解这一边界后，才能把脚本用在正确的生命周期里。

前置条件与版本差异

截至当前的最新版本（2026-05 发布的 7.3 系列），kuailian-cli 已集成在 macOS 标准安装包内，无需单独下载。若你在旧版（7.2 及以前）找不到命令，请卸载后重新拖入 Applications，系统会自动把可执行文件软链到 /usr/local/bin。经验性观察：在 10.13-14 系统上，若之前通过 Homebrew 安装过测试通道版本，可能残留同名符号链接，导致 which kuailian-cli 指向旧路径。解决方法是先 brew unlink kuailian，再重装官方 DMG。

节点文件格式：YAML 与 JSON 二选一

CLI 要求字段与图形端保持一致，必须包含 name、addr、port、uuid、proto 五项，其余如 group、mtu 为可选。以下给出最小 YAML 示例：

nodes:
  - name: SG-HK-01
    addr: sgp-01.hk.kuailian.net
    port: 443
    uuid: 3b5f…
    proto: klp-udp
  - name: US-NYC-03
    addr: us-nyc-03.kuailian.net
    port: 8443
    uuid: 7c2e…
    proto: wireguard

若你更习惯 JSON，可执行 kuailian-cli import --format json，但需保证顶层为对象且含 nodes 数组。格式写错时，CLI 会回显首行解析错误并返回非 0 状态码，方便在 CI 里中断后续流程。

标准导入命令与参数拆解

打开终端，进入存放节点文件的目录，运行：

kuailian-cli import -f ./nodes.yaml --group "ProjectX" --dry-run

参数含义：

-f 指定文件路径，支持相对/绝对路径；
--group 把导入节点统一放入名为 ProjectX 的分组，若省略则写入「未分组」；
--dry-run 仅做语法校验，不写入数据库，适合在 GitHub Actions 里做 PR 预检。

验证无误后，再次去掉 --dry-run 即可真正落库。成功后会回显 Imported N nodes, skipped M duplicates，其中重复判定以 addr+port+uuid 三元组为准。

批量生成模板：用脚本把 Excel 转 YAML

运维同事常把节点信息维护在 Google Sheets 里，导出为 CSV 后即可用以下单行命令生成合规 YAML：

awk -F',' 'NR>1 {print "  - name: " $1 "\n    addr: " $2 "\n    port: " $3 "\n    uuid: " $4 "\n    proto: " $5}' nodes.csv > nodes.yaml

经验性观察：当 CSV 行尾含 Windows 换行符时，可能出现解析失败。可提前执行 dos2unix 或在 awk 后加 sub(/\r$/,"") 清理回车符。

与 Ansible 集成：最小 Playbook 示例

对于需要给 30 台编译机下发同一批节点的场景，可在 Playbook 里调用 CLI：

- hosts: macos-ci
  tasks:
    - name: Copy node YAML to remote
      copy: src=nodes.yaml dest=/tmp/nodes.yaml
    - name: Import nodes
      command: kuailian-cli import -f /tmp/nodes.yaml --group CI
      become: no

注意：kuailian-cli 依赖当前用户下的 LaunchAgent 守护进程，若用 become: yes 会切换到 root，导致无法与守护进程通信，出现「Transport not found」错误。

常见失败分支与回退方案

1. 报错「Signature verify failed」

原因：YAML 里 uuid 字段长度不足或含多余空格。解决：用 cat nodes.yaml | tr -d ' ' 去空格后再导入。

2. 报错「Database is locked」

原因：GUI 客户端正在写库。解决：退出 GUI 或在 GUI「设置-高级」里关闭「实时同步」后重试。

3. 想回退到导入前状态

CLI 暂未提供事务级回滚，但你可以在导入前手动备份数据库：

cp ~/Library/Application\ Support/Kuailian/nodes.db ~/nodes.db.bak

若导入后发现问题，可关闭客户端，还原备份，再重启即可。

验证与观测方法

导入完成后，可用：

kuailian-cli list --group ProjectX --json | jq '.[] | .name'

确认节点已写入；随后执行：

kuailian-cli ping -n SG-HK-01 -c 10

若往返延迟在预期区间（经验性观察：亚洲节点 30-60 ms），说明配置生效。若超时，请检查本地防火墙是否放行 UDP 443。

适用/不适用场景清单

场景	是否推荐	理由
CI 流水线每日重置节点	✅ 强烈推荐	自动化友好，零人工干预
个人电脑偶尔手动换节点	❌ 不建议	GUI 拖拽更快，无需学 CLI
节点含敏感政府出口 IP	⚠️ 谨慎	需先评估合规，避免批量误用

FAQ（结构化数据）

导入后图形界面没看到节点？

请确认 GUI 已升级到 7.3 系列并点击「同步配置」；若云端为空，本地节点会被视为「未同步」而隐藏。

能否加密存放 YAML 里的 uuid？

CLI 当前仅支持明文，建议把文件权限设为 600，并存入私有 Git 仓库；官方未提供本地密钥库解密功能。

一次导入最多支持多少条？

经验性观察：在 M2 芯片 + 16 GB 内存的测试环境下，导入 1200 条节点耗时约 25 秒，超过 1500 条可能出现「数据库 busy」提示，建议分批。

最佳实践清单（快速决策）

任何自动化前，先用 --dry-run 做语法校验；
YAML/JSON 统一用 UTF-8 无 BOM，避免中文空格；
把导入脚本纳入 Git，节点文件放另一个私有库，实现「代码与数据分离」；
CI 任务里加入 kuailian-cli list 计数断言，防止空导入被漏检；
生产环境先灰度 5 台，确认 ping 值稳定后再全量推送。

收尾与下一步

快连 kuailian macOS CLI 的批量导入功能，把「重复手工」转化为「可审计脚本」，在节点规模超过 20 台时 ROI 最高。若你当前只需偶尔换线，图形界面仍是更低认知负担的选择；但一旦涉及多设备、多账号、频繁回收 IP，建议立刻把本文示例脚本纳入仓库，并在每次官方发布新节点列表后，用 CI 自动校验、自动下发，实现真正的「配置即代码」。下一步，可尝试将相同思路迁移到 Linux 服务端，结合 WireGuard 模板生成，进一步统一全网加速策略。