功能定位：为什么要在 Ubuntu 终端里“点名”节点
在合规与可审计场景下，kuailian命令行启动并指定节点能把“走哪条线”写进脚本，方便 CI、跳板机或自动化运维留痕。相比 GUI 的“一键加速”，CLI 把出口 IP、协议、时间戳一次性落在 syslog，正好满足“谁、什么时候、去了哪里”的审计字段要求。
另一方面，Ubuntu Server 往往没有桌面环境，依赖 systemd 或 cron 拉起任务；用官方 CLI 可直接读取 /etc/kuailian/node.conf，实现“掉线自启+指定节点”双保险，而 GUI 客户端无法在纯终端安装。
前置条件与版本边界
1. 系统与架构
- Ubuntu 20.04 LTS 及以上，x86_64 或 arm64 均可；经验性观察：22.04 对 WireGuard 内核模块支持更完整。
- 已启用
universe仓库，用于安装wireguard-tools等依赖。
2. 快连 CLI 版本
截至当前的最新版本为 5.3.x 系列；安装包名统一为 kuailian-cli，不再区分 -wg/-hy 子包，安装后可通过 kuailian-cli version 回显确认。
安装与首次登录
1. 一键安装脚本
脚本会自动识别 apt/dnf 并写入 repo；若服务器在内网，可手动下载.deb后执行dpkg -i kuailian-cli*.deb。
2. 账号登录与 Token 缓存
执行 kuailian-cli login，按提示输入订阅手机号+验证码；登录成功后，Token 明文保存在 ~/.config/kuailian/credentials.json，权限 600。CI 场景可预置该文件，实现无人值守。
列出可用节点：如何找到“节点代号”
返回示例（节选）：
其中 id 字段即为后续 --node 参数要填入的“节点代号”；若只想看专线，可加 --line IEPL。
命令行启动并指定节点：最简可达路径
参数说明：
--node：节点代号，必须；如果拼写错误，CLI 会返回 404 并给出最近似候选。--protocol：可选wireguard|hysteria2|vless；默认自动，但手动指定可让脚本更可预测。--log-level：写屏同时写/var/log/kuailian-cli.log，方便后续审计。
systemd 固化：开机自启+掉线重连
新建 /etc/systemd/system/kuailian.service：
然后 systemctl daemon-reload && systemctl enable --now kuailian 即可；Restart=on-failure 保证隧道异常退出后 5 秒自举。
验证与回退：确保真的走了指定节点
1. 实时验证
返回 "SG" 即代表已切到新加坡；若仍显示国内，检查 --bypass-cn 是否误开。
2. 日志审计
每行会打印节点 ID、协议、握手耗时，方便与外部审计系统对接。
3. 快速回退
若节点异常，可 systemctl stop kuailian 后执行 kuailian-cli connect --auto 回到智能选路；或直接把 --node 改成其他 ID 后 systemctl restart kuailian，全程 < 10 秒。
例外与副作用：什么时候不该硬编码节点
警告
IEPL 专线在高并发爬虫场景会被限速至 30 Mbps（经验性观察），若用于批量下载需在脚本里加 --rate-limit 或改用 P2P 节点。
- 政务/银行白名单：合规模式开启后，硬编码海外节点会导致访问财政部网站被强制重置；解决办法是在
/etc/kuailian/compliance.conf里把*.gov.cn写进直连列表。 - 家庭共享子账号：主号若被风控，连带子号会同时掉线；CLI 不会自动切换账号，需提前在跳板机部署两个服务实例做冷备。
与第三方工具协同：最小权限原则
在 Ansible playbook 里调用 kuailian-cli，建议单独创建 privacy tool 用户，仅授予 CAP_NET_ADMIN 能力：
这样无需全程 sudo，日志也能区分 privacy tool 用户与 root 操作，满足“可审计”要求。
故障排查：现象→原因→处置
| 现象 | 可能原因 | 验证 | 处置 |
|---|---|---|---|
| CLI 报 401 Unauthorized | Token 过期 | stat ~/.config/kuailian/credentials.json | kuailian-cli login 重新获取 |
| 握手成功但无法解析域名 | 私有 DNS 被本地 systemd-resolved 覆盖 | resolvectl status | grep "DNS Domain" | 在 /etc/resolv.conf 首行加 nameserver 10.255.0.1 |
| systemd 重启间隔 < 3 秒 | 节点被后台置灰 | kuailian-cli node list | grep sg-iepl-05 | 换节点或加 --auto |
适用/不适用场景清单
- 适用：合规审计、CI/CD 海外依赖下载、高校服务器定时同步 Docker Hub、运维跳板机 SSH 海外资产。
- 不适用：需要频繁切换出口 IP 的爬虫、大流量 PT 公开种子（P2P 节点仍建议用桌面 GUI 手动开端口转发）、对 IPv6-only 教育网资源的访问（快连 CLI 目前仅 IPv4 出口）。
最佳实践 5 条
- 脚本里永远写
--node + --protocol双参数，防止后台默认策略变动导致出口漂移。 - 把
kuailian-cli version输出重定向到日志，方便半年后回溯“当时用的哪一版”。 - systemd 实例命名带上节点 ID，例如
[email protected]，可并行起多隧道做分流。 - 定期
logrotate，避免/var/log/kuailian-cli.log撑爆/var分区。 - 合规模式下，至少每季度 diff 一次
compliance.conf与央行白名单公告，防止新增本地域名被误代理。
版本差异与迁移建议
5.2→5.3 最大变化是配置文件目录从 ~/.kuailian 迁移到 ~/.config/kuailian，符合 XDG 规范；升级后首次启动会自动迁移，若同台多用户需检查权限是否继承。
FAQ：命令行常见疑问
可以在同一台机器起多个不同节点的隧道吗？
可以，用不同 systemd 模板实例即可；每个实例需独立 --device wg1/wg2 与路由表，避免冲突。
Token 多久过期？
经验性观察：30 天无活动会失效；若通过 systemd 常驻，每 24 h 有保活心跳，不会过期。
如何彻底卸载？
sudo apt purge kuailian-cli && sudo rm -rf /etc/kuailian ~/.config/kuailian；卸载后 wg 接口会自动销毁。
收尾：下一步行动
至此，你已能在 Ubuntu 终端用一句命令精确指定快连节点，并固化到 systemd 实现“掉线自举+审计留痕”。建议先在测试机跑 24 h，确认日志无异常后再推到生产；每季度回顾一次节点列表，及时淘汰被置灰的 ID，保持脚本长期可维护。
如果后续需要动态分流（比如国内 CDN 直连、海外走隧道），可把 --node 参数写成变量，通过 Ansible 或 SaltStack 下发放行，进一步把“合规+自动化”做成闭环。
