EasyCat

EasyCat 是 Tailcat 与 EasyTier 的按需引导工具：当正常入口不可达时，临时使用 Tailcat 把远端 Linux 机器的 EasyTier TCP 监听端口映射到本机；EasyTier 建立独立路径后实际撤桥验证，成功才关闭两端 Tailcat。

当前支持范围

• 控制端：Windows amd64/arm64、Linux amd64/arm64/armv7。
• SSH 目标端：Linux amd64/arm64/armv7。
• 使用系统 ssh、scp，支持 SSH 密钥；默认开启 BatchMode，不会把密码保存到程序里。
• 从 Tailcat 官方 GitHub Release 下载并用官方 checksums.txt 校验。
• Tailcat 只上传到目标的 ~/.cache/easycat/<版本>/，不安装服务。
• 当前版本通过文本启发式检查 EasyTier 独立 peer；正式使用前应针对你的 easytier-cli peer 输出调整检查器。

1. 预下载所有常用平台

easycat.cmd prefetch

固定版本：

easycat.cmd prefetch --version v0.3.0

只缓存部分平台：

easycat.cmd prefetch --target windows-amd64 --target linux-amd64 --target linux-arm64

查看缓存：

easycat.cmd inventory

环境自检：

easycat.cmd doctor

2. 探测并上传

easycat.cmd probe --host user@server --identity C:\keys\id_ed25519
easycat.cmd deploy --host user@server --identity C:\keys\id_ed25519

目标不需要访问 GitHub；二进制由本机通过 SCP 发送。

3. 按需引导

目标 EasyTier 必须正在监听 TCP 11010。启动引导：

easycat.cmd bootstrap `
  --host user@server `
  --identity C:\keys\id_ed25519

程序会打印：

EasyTier bootstrap peer: tcp://127.0.0.1:11110

把它作为新节点 EasyTier 的临时 peer。确认存在独立路径后按 Ctrl+C，程序会同时关闭两端 Tailcat。

也可让 EasyCat 启动 EasyTier并自动检查：

easycat.cmd bootstrap `
  --host user@server `
  --identity C:\keys\id_ed25519 `
  --easytier-command 'easytier-core.exe --dhcp --network-name mynet --network-secret secret --peers {peer}' `
  --verify-command 'ping -n 1 10.126.126.2' `
  --wait 180

程序先等待已知的 EasyTier 虚拟地址可达，然后等待路径发现，实际撤掉本地 Tailcat 通道，再连续三次执行相同的端到端检查。只有撤掉 Tailcat 后仍然成功，才会关闭远端 Tailcat。默认不会终止 EasyTier。

如果撤掉通道后检查失败，程序会自动恢复本地 Tailcat 桥并保持运行，避免把刚加入的节点直接断开。此时可按 Ctrl+C 结束，或让它暂时作为保底通道运行。

安全与限制

• 第一次上传必须有一条可用 SSH 路径；完全不可达且没有 Tailcat 的机器无法远程注入程序。
• 默认 SSH BatchMode=yes，请预先配置密钥和 known_hosts。
• 远端 Tailcat token 会出现在控制台；应当像临时密码一样保护日志。
• 当前远端 Tailcat 使用临时密钥，SSH 会话断开后进程退出，token 随即失效。
• Tailcat 官方目前不承诺 CLI、API 或线协议稳定性，因此生产环境建议固定已验证版本。
• 如果 EasyTier 始终没有建立独立路径，关闭 Tailcat 就会断网。自动模式超时会报告失败，但仍会清理临时 Tailcat；如需长期保底，应使用常驻桥模式。

报错格式

错误会给出稳定错误码、中文原因、建议和必要的底层详情，例如：

[E202] SSH 身份验证失败
建议：确认用户名、私钥及目标 authorized_keys；程序默认 BatchMode，不会弹出密码框。
详情：user@host: Permission denied (publickey).

常见类别：E1xx 下载/Release、E2xx SSH/SCP、E3xx 本地桥、E4xx 远端 Tailcat、E9xx 配置或未预期错误。程序不会在错误信息中主动打印网络密钥；Tailcat token 仍应按临时密码保护。